@wtfalch/foundry 0.16.15 → 0.17.0

package/dist/plan/entry-files-key.d.ts

@@ -1,5 +1,5 @@
 import { type DeclaredOrg, type HostingEntry } from '../org.js';
-import type { PlannedStep } from './diff.js';
+import type { DraftStep } from './diff.js';
 import type { OrgPlatformReadiness } from './platform-org.js';
 /**
  * F6b: the org's own files key, minted below the files organisation's
@@ -56,8 +56,10 @@ export interface EntryFilesWant {
     permissions: string[];
     collections: string[];
     filesUrl: string;
+    /** `https://share.<domain>`, set only when the entry declares `shareHost`. */
+    shareOrigin?: string;
 }
-export declare function wantedEntryFiles(entry: HostingEntry, filesUrl: string): EntryFilesWant;
+export declare function wantedEntryFiles(entry: HostingEntry, filesUrl: string, shareHostname?: string | null): EntryFilesWant;
 export type EntryFilesMode = 'mint' | 'renew' | 'settings' | 'finish' | 'retire';
 type Blocked = Array<{
     description: string;
@@ -75,8 +77,8 @@ type Blocked = Array<{
  * it by its own `renew` step, and only then does `revoke-previous` revoke the
  * old org key, which revokes everything still below it.
  */
-export declare function planFilesKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly PlannedStep[], readiness: OrgPlatformReadiness, now: number): {
-    steps: PlannedStep[];
+export declare function planFilesKeys(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], readiness: OrgPlatformReadiness, now: number): {
+    steps: DraftStep[];
     blocked: Blocked;
 };
 export {};

package/dist/plan/entry-files-key.js

@@ -1,4 +1,5 @@
 import { FILES_ENTRY_PERMISSIONS } from '../org.js';
+import { filesShareHostname } from './hostnames.js';
 import { appStepKey } from './platform-diff.js';
 /**
  * F6b: the org's own files key, minted below the files organisation's
@@ -67,12 +68,13 @@ export function filesOwnerUserId(org, recordedIds) {
     const first = org.owners[0];
     return first ? recordedIds[`zitadel:owner:${org.id}:${first.email.toLowerCase()}`] : undefined;
 }
-export function wantedEntryFiles(entry, filesUrl) {
+export function wantedEntryFiles(entry, filesUrl, shareHostname = null) {
     const files = entry.uses?.files;
     return {
         permissions: [...(files?.permissions ?? FILES_ENTRY_PERMISSIONS)],
         collections: [...(files?.collections ?? [])],
         filesUrl,
+        ...(files?.shareHost && shareHostname ? { shareOrigin: `https://${shareHostname}` } : {}),
     };
 }
 /**
@@ -157,14 +159,9 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
     }
     if (entries.length === 0 || !readiness.filesReady)
         return { steps, blocked };
-    for (const entry of entries) {
-        if (entry.uses?.files?.shareHost) {
-            blocked.push({
-                description: `${org.slug}'s ${entry.key} share host is blocked: the platform's files host has no route for share.<domain> yet, so FILES_SHARE_ORIGIN is not delivered`,
-                key: `files:share:${org.id}:${entry.key}`,
-            });
-        }
-    }
+    // The route and DNS for share.<domain> are planned with the tunnel; the org
+    // apply then gives the platform files runner the host (`FoundryPlanApply.apply`).
+    const shareHostname = filesShareHostname(org);
     // The org's own key: minted, or renewed when it is short or its expiry is unknown.
     const rootBlock = (why) => blocked.push({
         description: `${org.slug}'s own files key is blocked: ${why}`,
@@ -244,7 +241,7 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
             block("the entry's app is not recorded yet");
             continue;
         }
-        const want = wantedEntryFiles(entry, readiness.filesUrl);
+        const want = wantedEntryFiles(entry, readiness.filesUrl, shareHostname);
         const applied = recordedIds[entryFilesAppliedScopeKey(entry.key)];
         const wantJson = JSON.stringify(want);
         let mode = null;

package/dist/plan/executor.d.ts

@@ -183,10 +183,19 @@ export interface CoolifyPort {
      * `is_preview === false` the same way a deployed-config reader must.
      */
     listEnvs(applicationUuid: string): Promise<Array<{
+        uuid?: string;
         key: string;
         value: string;
         is_preview: boolean;
     }>>;
+    /**
+     * #436 round 2: removes one environment variable row by the `uuid`
+     * `listEnvs` names it under -- `bulkUpsertEnvs` only adds or updates, so
+     * this is the only way to make a var foundry wrote in an earlier release
+     * actually go away, rather than leaving it set to a value nothing reads
+     * any more (`provisionPlatformArchon`'s stale `FILES_MANAGEMENT_KEY`).
+     */
+    deleteEnv(applicationUuid: string, envUuid: string): Promise<unknown>;
     /** Escape hatch (`CoolifyClient.raw`) — used for stop/start, which have no typed method yet. */
     raw(method: string, path: string, body?: unknown): Promise<unknown>;
     /**
@@ -294,10 +303,13 @@ export interface CoolifyPort {
      * fresh Synapse/MAS config file, since a file-storage write alone does not
      * reach the running container until its next deploy (issue #128's "a
      * running app is redeployed when its config changed"). Fire-and-forget,
-     * like `restart` above: this executor does not poll a deployment to
-     * completion anywhere else, and `coolifyCalls` only calls this when the
-     * config it just wrote was actually freshly minted. Matches `CoolifyClient.
-     * deploy` method-for-method.
+     * like `restart` above: `coolifyCalls` only calls this when the config it
+     * just wrote was actually freshly minted, with nothing recorded afterward
+     * that depends on the new version actually being live. Matches
+     * `CoolifyClient.deploy` method-for-method. A step that records an applied
+     * hostname/gitRef after a deploy uses {@link CoolifyPort.deployAndWait}
+     * instead (#252) — `deploy-health.ts`'s `waitForNewDeployment` is the one
+     * shared helper every such step calls, never this method directly.
      */
     deploy(uuid: string, force?: boolean): Promise<unknown>;
     /**
@@ -361,6 +373,27 @@ export interface CoolifyPort {
     }): Promise<{
         uuid: string;
     }>;
+    /**
+     * Deploys and blocks until Coolify's own deployment record reaches a
+     * terminal state (#252) — matches `CoolifyClient.deployAndWait`
+     * method-for-method. Unlike `deploy` above, or unlike polling
+     * `getApplication`'s live `status`, this is the one honest answer to
+     * "did the new version actually land": a failed build leaves the previous
+     * container running and healthy, so `status` and a served request read
+     * identically whether the deploy succeeded or not (`CoolifyDeploymentRecord`'s
+     * own doc comment in `@wtfalch/providers`). `force` defaults to `true` on
+     * the real client for the same reason its own doc comment gives — every
+     * caller here is provisioning or releasing, where a wrong "it's applied"
+     * costs more than a warm build cache.
+     */
+    deployAndWait(uuid: string, options?: {
+        force?: boolean;
+        attempts?: number;
+        intervalMs?: number;
+    }): Promise<{
+        deploymentUuid: string;
+        status: string;
+    }>;
 }
 /**
  * The Cloudflare calls this executor makes, shaped to match
@@ -812,7 +845,7 @@ export interface ZitadelPort {
         givenName: string;
         familyName: string;
         email: string;
-    }): Promise<{
+    }, urlTemplate?: string): Promise<{
         userId: string;
         created: boolean;
     }>;
@@ -1025,16 +1058,6 @@ export interface ZitadelListAppsRawApp {
  * `signManagementRequest`/`AssertionTrust`). A host can construct this without
  * any human session: it only needs the Ed25519 private key (`SigningIdentity`)
  * an operator's `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` pins.
- *
- * #177: `setQuota`/`setBudget` (`files/packages/sdk/src/client.ts:154-166`)
- * used to live on a separate `FilesOrgLimits` a host built per org through a
- * `filesLimitsFor(orgId)` factory on `FoundryStepExecutorPorts` — ceremony
- * left over from nothing but currying an id this port's own callers already
- * have in hand. The signed claim's `organisation` field selects the org per
- * call, so one shared keypair signs for every org already, the same signer
- * `provisionOrganisation` uses; there was never a per-org client to build,
- * only an org id to pass. Both methods now take it explicitly, like
- * `provisionOrganisation` always did, and `filesLimitsFor` is gone.
  */
 export interface FilesOrganisationPort {
     provisionOrganisation(input: {
@@ -1064,9 +1087,6 @@ export interface FilesOrganisationPort {
             secret: string;
         };
     }>;
-    /** #27, #177: the org's own spend limit on Files -- see this interface's own doc comment for why `organisationId` is explicit here. */
-    setQuota(organisationId: string, limitBytes: string | null): Promise<unknown>;
-    setBudget(organisationId: string, limitMicros: string | null): Promise<unknown>;
     /**
      * F6b: mints the organisation's own key, matching files'
      * `POST /v1/manage/organisations/:organisationId/keys` (SDK
@@ -1227,10 +1247,10 @@ export interface AiOrganisationPort {
      * `ai/packages/sdk/src/client.ts:94-101`'s `updateBudget` (`UpdateBudget`
      * from `ai/packages/sdk/src/types.ts:134-137`). Used to live on a separate
      * `AiOrgLimits` a host built per org through an `aiLimitsFor(orgId)`
-     * factory on `FoundryStepExecutorPorts` -- the same dead currying
-     * {@link FilesOrganisationPort}'s own doc comment explains for
-     * `setQuota`/`setBudget`. `organisationId` is explicit here now, like
-     * every other method on this port.
+     * factory on `FoundryStepExecutorPorts` -- ceremony left over from nothing
+     * but currying an id this port's own callers already have in hand.
+     * `organisationId` is explicit here now, like every other method on this
+     * port.
      */
     updateBudget(organisationId: string, input: {
         keyId: string | null;
@@ -1341,6 +1361,16 @@ export interface FoundryStepExecutorPorts {
      * themselves.
      */
     deliverSecret(ref: string, secret: string): Promise<void>;
+    /**
+     * Archon's held keys, for an entry env from `sharedSecret` (read, else
+     * generate and `put`) and `platformMailKey` (read only). Optional: without
+     * it, or without `put`, such an env is omitted and the plan reports it
+     * blocked. A value goes to the entry's env and nowhere else.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null | undefined>;
+        put?(ref: string, value: string): Promise<void>;
+    };
     /**
      * Read access to the declared-org store, narrowed to the one query
      * `cloudflareZone` needs for its cross-org refusal check (#131) -- see that
@@ -1560,6 +1590,20 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private findRecreatedApp;
     private ensureZitadelProject;
     private ensureCoolifyProject;
+    /**
+     * #445: one company lands on one Coolify server. The first call for an
+     * org picks a usable, reachable server and records it
+     * ({@link COOLIFY_SERVER_SCOPE_KEY}); every later call -- this apply, or a
+     * later one -- reads that recording back and returns the same server,
+     * regardless of what the pool's order or health looks like by then. A
+     * recorded server that has gone unusable or unreachable is reported
+     * blocked (never silently replaced with a second host, which would split
+     * the org's resources across servers and break their internal container
+     * URLs); a recorded server no longer registered at all is the same.
+     * Deliberately no fallback to `servers[0]` when nothing is usable: an
+     * unusable server picked blind is not a server anyone's resources could
+     * actually be created on.
+     */
     private resolveServer;
     private coolifyApp;
     /**
@@ -1636,6 +1680,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
+    /**
+     * The org's shared secret `name`: read from the held keys, else generated
+     * and held first, so a crash after the `put` and before the env write
+     * hands the same value out on the next apply. Only called when `put` exists.
+     * An error here names the ref, never a value.
+     */
+    private ensureSharedSecret;
     /**
      * F5: the app's `AUTH_APP_KEY`, minted once and only when the app has none
      * of at least 32 characters (the broker refuses a shorter one). `null` once
@@ -1897,6 +1948,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `coolifyApp`'s own analogous gap (it never restarted a found-but-stopped
      * app either) has since closed the same way, inline in that method (#130);
      * this method is `cmsSite`'s only caller.
+     *
+     * `repo` (#245) lets the site app build from an org's own skin repo
+     * (`org.site.repo`) instead of the shared `CMS_REPO`; `cmsSite` always
+     * passes `CMS_REPO` for the cms admin app, which is never org-specific.
      */
     private findOrCreateCmsApp;
     /**
@@ -2050,6 +2105,19 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * pushed once calls are on and this org's calls service app carries its
      * internal name (`desiredAgoraEnv` reads that marker from the recorded ids,
      * not the host values).
+     *
+     * #442: a found-but-already-running app's container binds env only at
+     * start, so writing it alone leaves that process on its old config --
+     * restarted (never redeployed: no new image, so `restart` is the same
+     * primitive `ensureLogVolume`'s own restart uses) whenever the live env
+     * actually differs, or whenever the last restart this step confirmed
+     * ({@link AGORA_ACTIVATED_ENV_SCOPE_KEY}) is not this exact env (an org
+     * applied before this existed, whose live env already matched desired
+     * with nothing ever confirmed running it). A brand new app has nothing
+     * running yet to restart. The activation marker is recorded last, after
+     * the restart (if any) returns without throwing, so a failed restart
+     * leaves it stale and the next plan replans this step even though
+     * Coolify's own env store already matches desired.
      */
     private coolifyAgora;
     /**
@@ -2354,17 +2422,31 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private ensureLettermintDmarcRecord;
     /**
-     * #80: provisions the org's own organisation on Files, before
-     * {@link filesStorage} can set its spend limit. `provisionOrganisation` is
-     * safely repeatable on its own (`FilesOrganisationPort`'s doc comment), so
-     * this is called every time regardless of whether it already ran --
-     * idempotent by find-or-create, not by checking `recordedIds` first.
+     * #80: provisions the org's own organisation on Files.
+     * `provisionOrganisation` is safely repeatable on its own
+     * (`FilesOrganisationPort`'s doc comment), so this is called every time
+     * regardless of whether it already ran -- idempotent by find-or-create,
+     * not by checking `recordedIds` first.
+     *
+     * F6b: `action.desired.shareHost` (`diff.ts`'s `planFilesOrganisation`) is
+     * passed through every time, even though `entry-files-key.ts` reports the
+     * route itself as blocked until the platform's files host can serve
+     * `share.<domain>` -- this is the one place the name reaches files at all,
+     * so files can act on it the moment its own route exists.
      *
      * #273: also ensures the org's Agora origin is on the files host's CORS
      * allowlist (`FilesOrganisationPort.ensureAllowedOrigin`), the same
      * repeat-is-a-no-op shape as `provisionOrganisation` itself -- every org
      * gets an Agora (#164), so `diff.ts`'s `planFilesOrganisation` always sets
      * `desired.agoraOrigin`.
+     *
+     * #437: the owner member/name, the core ZITADEL files project and the core
+     * collection (`core-files.ts`) are no longer conditioned on a hosting entry
+     * declaring `uses.files` -- the core bundle (Agora's own uploads) needs
+     * all three just as much as a bespoke entry does, and withholding them
+     * until one existed is why a plain Agora/Boule org never got a usable
+     * Files setup at all. Both the project and the collection are idempotent
+     * by name, so a re-run that already created either finds it instead.
      */
     private filesOrganisation;
     /**
@@ -2375,7 +2457,6 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * that fails revokes the key again instead of leaving a live key nobody holds.
      */
     private deliverFilesAgoraKey;
-    private filesStorage;
     /**
      * #80: provisions the org's own organisation on AI and switches its AI use
      * on, before {@link aiBudget} can set its own spend limit. Both