@wtfalch/foundry 0.47.0 → 0.48.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, OrgRefusal, OrgRefusalCode, WorkerAppConfig, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceDatabase, OrgServiceSchema, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, HostingEntry, BlueGreenConfig, OrgBuiltinApp, OrgRefusal, OrgRefusalCode, WorkerAppConfig, EntryGate, EntryVolume, HostingEntryUses, EntryAuth, EntryFiles, EntryAi, EnvValue, EnvHeldSecret, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, OwnerMailbox, DeclaredOrg, OrgServiceDatabase, OrgServiceSchema, ServicesConfig, SignInConfig, VersionPin, VersionPinPart, } from './org.js';
 export { APP_ENTRY_KEY, DEFAULT_GATE_LIMIT, FILES_ENTRY_PERMISSIONS, AI_ENTRY_PERMISSIONS, DEFAULT_MAIL_APPS, ORG_SERVICE_SCHEMAS, orgServiceDatabase, orgServiceDatabases, SFU_SLOT_MAX, VERSION_PIN_PARTS, isMainEntry, mainEntry, heldEnvRef, ownerMailboxes, ownsServices, validateBuyerIdentity, validateHosting, validateMail, validateOwners, validateServices, validateCustomers, validateSignIn, validateVersionPin, validateSite, } from './org.js';
 export { refuseOrg } from './refuse-org.js';
 export { workerAppHasBuild } from './worker-app-config.js';
@@ -29,6 +29,8 @@ export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAudit
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, StepSystem, PlanDetail, OrgPostgresPlan, PlatformPlanDetail, MailRoute, AdoptCandidate, AdoptInput, AdoptPlan, AdoptSnapshot, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, FoundryApplyOptions, UnconfirmedUpgrade, } from './plan/index.js';
 export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
+export { DumpError, dumpNow } from './plan/index.js';
+export type { DatabaseDump } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export type { OrgPostgresMigrationConfirmation } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';

package/dist/index.js

@@ -18,6 +18,7 @@ export { createPostgresReleaseStore } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAppliedVersions, foundryAuditEvents, foundryDeclaredPlatform, foundryReleaseRequests, foundryRequestedChanges, } from './store/schema.js';
 export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './plan/index.js';
 export { AdoptRefusedError } from './plan/index.js';
+export { DumpError, dumpNow } from './plan/index.js';
 export { InvalidMigrationConfirmationError, ORG_POSTGRES_MIGRATION_CONFIRMED_SCOPE_KEY, OrgPostgresMigrationBackupMissingError, OrgPostgresMigrationNotConfirmedError, } from './plan/index.js';
 export { NetworkMoveBackupMissingError, UpgradeBackupMissingError } from './plan/index.js';
 export { createEdgeAccess, createEdgeDns, edgeDnsRecordOwners, createEdgeRateLimits, createEdgeTunnels, createEdgeWorkers, createEdgeZones, } from './plan/index.js';

package/dist/migrations/0059_org_builtin_blue_green.sql

@@ -0,0 +1,9 @@
+-- @wtfalch/foundry: `boule_blue_green` and `agora_blue_green` are `org.boule.blueGreen` and
+-- `org.agora.blueGreen` as JSON ({ steps?, stepHoldMinutes? }); null (the default) keeps the company's
+-- Boule or Agora on one app. Copies 0056_platform_archon_blue_green.sql: nullable columns added with
+-- `if not exists`, so it is safe to run at container start on live rows.
+-- Mirrors src/store/schema.ts's `declaredOrgs`.
+
+alter table foundry_declared_orgs
+  add column if not exists boule_blue_green jsonb,
+  add column if not exists agora_blue_green jsonb;

package/dist/org.d.ts

@@ -283,7 +283,7 @@ export type AccessRule = {
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
 /** Why a validator refused. `code` is stable and never reworded; `message` is for people. */
-export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'entry_key_invalid' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'client_name_taken' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
+export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'client_name_taken' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
 /**
  * One refusal: a stable `code`, the dotted `path` into {@link DeclaredOrg} it is about
  * (`hosting.entries.terminal.uses.auth.registration`) and the sentence for people.
@@ -385,6 +385,14 @@ export interface HostingEntry {
      */
     blueGreen?: BlueGreenConfig;
 }
+/**
+ * `boule` and `agora` on a company: the built-in apps foundry runs for every company (`<slug>-boule`,
+ * `<slug>-agora`). Only blue/green is declared here; absent means off. Optional so every existing literal and
+ * fixture compiles unchanged.
+ */
+export interface OrgBuiltinApp {
+    blueGreen?: BlueGreenConfig;
+}
 /** The traffic steps (percent to the new color) and the hold at each step. Both default in `plan/blue-green.ts`. */
 export interface BlueGreenConfig {
     /** Ascending, each 1..100, ending at 100. */
@@ -615,11 +623,15 @@ export interface HostingNames {
     locked: ReadonlySet<string>;
     slug?: string;
     siteOwnsApex?: boolean;
+    /** Boule or Agora declares `blueGreen`: the blue/green key names are reserved for the entries too. */
+    builtinBlueGreen?: boolean;
 }
 /** {@link validateHosting} with the code and path of the first refusal. */
 export declare function refuseHosting(hosting: HostingConfig, names?: HostingNames): OrgRefusal | null;
 /** `blueGreen`: steps ascending, each a whole number 1..100, the last 100; a hold of 1..1440 minutes. */
 export declare function validateBlueGreen(value: unknown, at: string): string | null;
+/** {@link refuseBlueGreen} for the `blueGreen` of the company's Boule and Agora; the same codes. */
+export declare function refuseBuiltinBlueGreen(org: Pick<DeclaredOrg, 'boule' | 'agora'>): OrgRefusal | null;
 export declare function validateDomain(domain: string): string | null;
 /**
  * A broker entry name foundry writes itself: Archon's, and any company's Boule.
@@ -1035,6 +1047,10 @@ export interface DeclaredOrg {
     services?: ServicesConfig;
     /** Absent means `{ inApp: false }`. Optional so every existing literal and fixture compiles unchanged. */
     signIn?: SignInConfig;
+    /** The company's Boule. Absent means no blue/green. */
+    boule?: OrgBuiltinApp;
+    /** The company's Agora, a static app: its release moves on hard fails and time only. Absent means no blue/green. */
+    agora?: OrgBuiltinApp;
     /** Absent means `{ enabled: false, signUp: false }`. Optional so every existing literal and fixture compiles unchanged. */
     customers?: CustomersConfig;
     /** Parts of this company held on their own version. Absent or null follows the platform. Ignored for the owner company. */

package/dist/org.js

@@ -156,13 +156,14 @@ export function refuseHosting(hosting, names) {
     if (hosting.enabled && hosting.entries.length === 0) {
         return refusal('hosting_needs_entry', 'hosting.entries', 'hosting.enabled requires at least one entry');
     }
+    const reserveKeys = names?.builtinBlueGreen === true || hosting.entries.some((e) => e.blueGreen !== undefined);
     const seenKeys = new Set();
     for (const entry of hosting.entries) {
         if (seenKeys.has(entry.key)) {
             return refusal('entry_key_not_unique', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' is not unique`);
         }
         seenKeys.add(entry.key);
-        const invalid = validateHostingEntry(entry, hosting.enabled);
+        const invalid = validateHostingEntry(entry, hosting.enabled, reserveKeys);
         if (invalid)
             return invalid;
         const invalidAuth = validateEntryAuth(entry, hosting, names?.domain);
@@ -358,6 +359,8 @@ function validateEntryHostnames(hosting, names) {
     return null;
 }
 const ENTRY_KEY = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/** Names of the parts blue/green adds to an app (`<app>-stage`, `-blue`, `-green`, `-lb`): an entry of that name would adopt one. */
+const RESERVED_ENTRY_KEY = /^(stage|blue|green|lb)$|-(stage|blue|green|lb)$/;
 const VOLUME_MOUNT_PATH = /^(\/(?!\.\.?(\/|$))[A-Za-z0-9._-]+)+$/;
 /** The log volume's mount path; `executor.ts`'s `LOG_DIR` is the same value. */
 const LOG_DIR_PATH = '/app/logs';
@@ -381,15 +384,18 @@ const REPO = /^wtfalch\/[A-Za-z0-9._-]+$/;
 // The env names `pushAppEnv` and `pushDatabaseUrl` set themselves.
 const FOUNDRY_ENV_NAME = /^(APP_URL|LOG_DIR|OWNER_USER_ID|AUTH_.*|DATABASE_URL.*)$/;
 // Set only on the colors of a blueGreen entry; any other entry may declare them.
-const BLUE_GREEN_ENV_NAME = /^REPORTING_(COLOR|RELEASE|HEALTH_TOKEN)$/;
+const BLUE_GREEN_ENV_NAME = /^(REPORTING_(COLOR|RELEASE|HEALTH_TOKEN)|NEXT_SERVER_ACTIONS_ENCRYPTION_KEY)$/;
 const SECRET_ENV_NAME = /_(KEY|SECRET|TOKEN|PASSWORD)$/;
 const HELD_SECRETS = "declare it as { from: 'heldSecret' }, not a plain value";
 /** The rules for one {@link HostingEntry}; `null` when it is valid. */
-function validateHostingEntry(entry, enabled) {
+function validateHostingEntry(entry, enabled, reserveKeys) {
     const at = `hosting.entries '${entry.key}'`;
     if (!ENTRY_KEY.test(entry.key)) {
         return refusal('entry_key_invalid', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' must be a DNS label (lowercase letters, digits and hyphens, 1-63 characters)`);
     }
+    if (reserveKeys && RESERVED_ENTRY_KEY.test(entry.key)) {
+        return refusal('entry_key_reserved', `hosting.entries.${entry.key}.key`, `hosting.entries key '${entry.key}' is reserved: stage, blue, green and lb, and any key ending in -stage, -blue, -green or -lb, name the parts blue/green adds to an app`);
+    }
     if (entry.repo !== null && !REPO.test(entry.repo)) {
         return refusal('entry_repo_invalid', `hosting.entries.${entry.key}.repo`, `${at} repo must be a repo under wtfalch, or null`);
     }
@@ -494,6 +500,21 @@ function refuseBlueGreen(value, at, path) {
     }
     return null;
 }
+/** {@link refuseBlueGreen} for the `blueGreen` of the company's Boule and Agora; the same codes. */
+export function refuseBuiltinBlueGreen(org) {
+    for (const app of ['boule', 'agora']) {
+        const value = org[app];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            return refusal('builtin_app_invalid', app, `${app} must be an object with an optional blueGreen`);
+        }
+        const refused = refuseBlueGreen(value.blueGreen, app, `${app}.blueGreen`);
+        if (refused)
+            return refused;
+    }
+    return null;
+}
 /** `volumes`: a bounded list of named volumes at distinct absolute paths, none on the log volume's path or name,
  * on `/app` or under a system path. */
 function validateEntryVolumes(entry, at) {

package/dist/plan/archon-blue-green.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { sharedSecretRef } from '../org.js';
 import { applyBlueGreenServer } from './blue-green-apply.js';
-import { ARCHON_BG_ORIGIN_SCOPE_KEY, DEFAULT_WEIGHTS, PRIMARY_SERVER_SCOPE_KEY, bgKey, healthTokenName, lbOrigin, splitServers, } from './blue-green.js';
+import { ARCHON_BG_ORIGIN_SCOPE_KEY, DEFAULT_WEIGHTS, PRIMARY_SERVER_SCOPE_KEY, actionsKeyName, bgKey, healthTokenName, lbOrigin, mintActionsKey, splitServers, } from './blue-green.js';
 /**
  * platform-archon on the blue/green path (`platform.archon.blueGreen`): the archon app keeps its name and is
  * blue; green, the balancer and stage are new apps beside it on the primary server. The tunnel moves to the
@@ -58,6 +58,20 @@ export async function applyArchonBlueGreen(run) {
         primaryBlueAppId: run.blueAppId,
         logDir: run.logDir,
         isRunning: run.isRunning,
+        adoptRunningBlue: true,
+        actionsKey: async () => {
+            const key = await mintActionsKey({
+                id,
+                ref: sharedSecretRef(run.ownerOrgId, actionsKeyName(id)),
+                recorded: run.recorded,
+                record: run.record,
+                persist: run.persist,
+                heldKeys: run.heldKeys,
+                generate: () => randomBytes(32).toString('base64'),
+                secret: run.secret,
+            });
+            return key;
+        },
     };
     await applyBlueGreenServer(deps, subject, { uuid: primary, primaryUuid: primary });
     // The structure is applied and every part ran: now, and only now, the tunnel moves.

package/dist/plan/blue-green-apply.d.ts

@@ -3,6 +3,7 @@ import { ensureConnectorsOnServers } from './cloudflared-connector.js';
 import { type DeployHealthRuntime } from './deploy-health.js';
 import type { TunnelPort } from './edge-tunnels.js';
 import type { CoolifyPort } from './executor.js';
+import { type StageGuardDeps } from './stage-guards.js';
 /** The Coolify calls this module makes. */
 type Coolify = Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'deployAndWait' | 'listStorages' | 'createPersistentStorage' | 'createFileStorage' | 'updateFileStorage' | 'requireGithubApp' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw'> & {
     listApplicationDeployments?: CoolifyPort['listApplicationDeployments'];
@@ -31,6 +32,21 @@ export interface BlueGreenApplyDeps {
     primaryBlueAppId: string;
     logDir: string;
     isRunning: (status: string | undefined) => boolean;
+    /**
+     * The primary blue is the process running this apply (platform-archon). Its first apply writes the reporting
+     * env but does not redeploy it: a restart would cut the apply, and the env is read at its next start.
+     */
+    adoptRunningBlue?: boolean;
+    /**
+     * The subject's server actions key (held, minted once). Blue and green are built with it; stage gets a key of
+     * its own. Absent: no key is set.
+     */
+    actionsKey?: () => Promise<string>;
+    /**
+     * What stage's guards need from the host: the probe port and the Access gate. A missing part leaves that
+     * guard unrecorded ("not run", never passed), so `stageGuardsReady` stays false and the copy does not start.
+     */
+    stageGuards?: StageGuardDeps;
 }
 /** What writing a balancer's config needs; {@link BlueGreenApplyDeps} and the release runner both have it. */
 export interface LbConfigDeps {
@@ -60,6 +76,25 @@ export declare function applyBlueGreenWeights(deps: LbConfigDeps, subject: BlueG
     uuid: string;
     primaryUuid: string;
 }): Promise<void>;
+/**
+ * The primary blue's env for another color: the database host swapped when the server is not the primary, and
+ * never the reporting names or the actions key, which differ by design. The structure apply and a deploy both
+ * copy through this, so a color is never deployed with an older copy than the structure apply wrote.
+ */
+export declare function copiedEnv(deps: {
+    label: string;
+    secret: (value: string) => void;
+}, subject: Pick<BlueGreenSubject, 'base'>, source: Array<{
+    key: string;
+    value?: string;
+    is_preview?: boolean;
+}>, server: {
+    uuid: string;
+    primaryUuid: string;
+}): Array<{
+    key: string;
+    value: string;
+}>;
 /** A connector for the org's tunnel on each given server; the primary's is the existing one. */
 export declare function applyBlueGreenConnectors(input: {
     coolify: Parameters<typeof ensureConnectorsOnServers>[0]['coolify'];

package/dist/plan/blue-green-apply.js

@@ -1,10 +1,13 @@
 import { randomBytes } from 'node:crypto';
-import { COLORS, LB_CONFIG_PATH, bgKey, colorAppName, colorBackend, formatWeights, lbAppName, lbDockerfile, parseWeights, renderLbConfig, reportingEnv, stageAppName, structureHash, } from './blue-green.js';
+import { ACTIONS_KEY_ENV, COLORS, LB_CONFIG_PATH, bgKey, colorAppName, colorBackend, formatWeights, lbAppName, lbDockerfile, parseWeights, prodResources, renderLbConfig, reportingEnv, stageAppName, stageAppUrl, stageKindOf, stageResources, structureHash, } from './blue-green.js';
 import { recordBuiltCommit } from './build-record.js';
 import { ensureConnectorsOnServers } from './cloudflared-connector.js';
 import { waitForNewDeployment } from './deploy-health.js';
 import { ENTRY_CONTAINER_LABELS } from './proxy-labels.js';
 import { remoteDatabaseAddress, remoteDatabaseHost } from './remote-database.js';
+import { buildStageEnv } from './stage-env.js';
+import { buildStageProbes, runStageProbes, stageProbesRecord, } from './stage-guards.js';
+import { assertStageIsolated, envClass, stageIsolationHash, } from './stage-isolation.js';
 /** Env names whose value is a credential: registered before they are copied. */
 const SECRETISH = /(KEY|SECRET|TOKEN|PASSWORD|DATABASE_URL)/;
 /** The env names that name the database. */
@@ -35,10 +38,16 @@ export async function applyBlueGreenServer(deps, subject, server) {
     if (!weights)
         throw new Error(`${deps.label}: the recorded weights are not valid`);
     const ids = {};
-    if (isPrimary)
+    if (isPrimary) {
         ids.blue = deps.primaryBlueAppId;
+        // A merge must not redeploy blue past the release runner.
+        await coolify.updateApplication(deps.primaryBlueAppId, { is_auto_deploy_enabled: false });
+    }
     const sourceEnv = await coolify.listEnvs(deps.primaryBlueAppId);
-    const token = await deps.healthToken();
+    const token = subject.reporting ? await deps.healthToken() : null;
+    const actionsKey = subject.reporting && deps.actionsKey ? await deps.actionsKey() : null;
+    if (actionsKey)
+        deps.secret(actionsKey);
     for (const color of COLORS) {
         const name = isPrimary && color === 'blue' ? subject.primaryBlueName : colorAppName(subject.base, color);
         if (!ids[color]) {
@@ -53,12 +62,20 @@ export async function applyBlueGreenServer(deps, subject, server) {
         const appId = ids[color];
         const copied = isPrimary && color === 'blue' ? [] : copiedEnv(deps, subject, sourceEnv, server);
         const release = deps.recorded()[bgKey.digest(id, color)];
-        const reporting = reportingEnv({ color, release, healthToken: token });
+        const reporting = token === null ? [] : reportingEnv({ color, release, healthToken: token });
         // A running color reads its reporting env at start: when it changed, the color restarts before the
         // tunnel can move to it.
         const reportingChanged = await reportingEnvDiffers(deps, appId, reporting);
-        await upsertEnv(deps, appId, [...copied, ...reporting]);
-        await ensureDeployed(deps, appId, name, reportingChanged);
+        await upsertEnv(deps, appId, [
+            ...copied,
+            ...reporting,
+            ...(actionsKey ? [{ key: ACTIONS_KEY_ENV, value: actionsKey, buildTime: true }] : []),
+        ]);
+        const adoptingBlue = deps.adoptRunningBlue === true &&
+            isPrimary &&
+            color === 'blue' &&
+            !deps.recorded()[bgKey.applied(id, server.uuid)];
+        await ensureDeployed(deps, appId, name, reportingChanged && !adoptingBlue);
     }
     const lbName = lbAppName(subject.base);
     const lbId = await ensureLoadBalancer(deps, subject, server.uuid, lbName, isPrimary);
@@ -103,16 +120,24 @@ async function writeLbConfig(deps, subject, server, lbId, weights) {
     deps.record(bgKey.lb(subject.id, server.uuid), formatWeights(weights));
     await deps.persist();
 }
-/** The primary blue's env for another color: the database host swapped when the server is not the primary. */
-function copiedEnv(deps, subject, source, server) {
+/**
+ * The primary blue's env for another color: the database host swapped when the server is not the primary, and
+ * never the reporting names or the actions key, which differ by design. The structure apply and a deploy both
+ * copy through this, so a color is never deployed with an older copy than the structure apply wrote.
+ */
+export function copiedEnv(deps, subject, source, server) {
     const sidecar = server.uuid === server.primaryUuid
         ? null
         : remoteDatabaseHost(subject.base, server.uuid, server.primaryUuid);
     const dbHost = sidecar ? remoteDatabaseAddress(sidecar) : null;
     const out = [];
     for (const env of source) {
-        if (env.is_preview || env.value === undefined || env.key.startsWith('REPORTING_'))
+        if (env.is_preview ||
+            env.value === undefined ||
+            env.key.startsWith('REPORTING_') ||
+            env.key === ACTIONS_KEY_ENV) {
             continue;
+        }
         let value = env.value;
         if (dbHost && DATABASE_ENV.has(env.key)) {
             const swapped = withDatabaseHost(value, dbHost);
@@ -149,6 +174,8 @@ async function ensureGitApp(deps, subject, input) {
         ports_exposes: String(subject.port),
         git_branch: input.branch,
         is_preview_deployments_enabled: false,
+        is_auto_deploy_enabled: input.autoDeploy,
+        ...(subject.dockerfileLocation ? { dockerfile_location: subject.dockerfileLocation } : {}),
         ...(subject.folder === null ? {} : { base_directory: `/${subject.folder}` }),
     };
     const recorded = deps.recorded()[input.key];
@@ -188,6 +215,7 @@ async function ensureGitApp(deps, subject, input) {
         ports_exposes: isStatic ? '80' : String(subject.port),
         is_auto_deploy_enabled: input.autoDeploy,
         base_directory: subject.folder === null ? undefined : `/${subject.folder}`,
+        ...(subject.dockerfileLocation ? { dockerfile_location: subject.dockerfileLocation } : {}),
     });
     // Recorded before anything else is written, so a later failure never leaves an app nothing points at.
     deps.record(input.key, created.uuid);
@@ -273,12 +301,12 @@ async function ensureLoadBalancer(deps, subject, serverUuid, name, isPrimary) {
     }
     return lbId;
 }
-/** The stage app and its own empty database, on the primary. Holds no env from the live app. */
+/** The stage app and its own empty database, on the primary. Its env comes from the allowlist, never from a copy of the live app's. */
 async function ensureStage(deps, subject, serverUuid) {
     const { coolify } = deps;
     const name = stageAppName(subject.base);
     const appId = await stageAppId(deps, subject, name, serverUuid);
-    const envs = [{ key: 'LOG_DIR', value: deps.logDir }];
+    const database = [];
     if (subject.database) {
         const dbName = `${subject.base}-stage-db`;
         const pgName = dbName.replace(/-/g, '_');
@@ -302,7 +330,7 @@ async function ensureStage(deps, subject, serverUuid) {
         const db = await coolify.getDatabase(dbId);
         if (db.internal_db_url) {
             deps.secret(db.internal_db_url);
-            envs.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
+            database.push({ key: 'DATABASE_URL_OWNER', value: db.internal_db_url });
             const have = (await coolify.listEnvs(appId)).find((e) => e.key === 'DATABASE_URL' && !e.is_preview);
             if (!have) {
                 const password = randomBytes(24).toString('base64url');
@@ -310,21 +338,144 @@ async function ensureStage(deps, subject, serverUuid) {
                 const runtime = runtimeDatabaseUrl(db.internal_db_url, `${pgName}_rt`, password);
                 if (runtime) {
                     deps.secret(runtime);
-                    envs.push({ key: 'DATABASE_URL', value: runtime });
+                    database.push({ key: 'DATABASE_URL', value: runtime });
                 }
             }
         }
     }
-    // Stage never holds the live app's keys or secrets: its env is the log directory and its own database.
-    await upsertEnv(deps, appId, envs);
+    const kind = stageKindOf(subject);
+    const prodEnv = await coolify.listEnvs(deps.primaryBlueAppId);
+    const greenId = deps.recorded()[bgKey.app(subject.id, serverUuid, 'green')];
+    const greenEnv = greenId ? await coolify.listEnvs(greenId) : [];
+    const { env } = buildStageEnv({
+        kind,
+        appUrl: stageAppUrl(subject),
+        logDir: deps.logDir,
+        database,
+        prod: prodEnv,
+        existing: await coolify.listEnvs(appId),
+        mint: () => {
+            const value = randomBytes(32).toString('base64url');
+            deps.secret(value);
+            return value;
+        },
+    });
+    const stageEnv = [...env];
+    if (subject.reporting && deps.actionsKey) {
+        // Stage never shares a production secret: its key is its own, minted once and kept.
+        const have = (await coolify.listEnvs(appId)).find((e) => e.key === ACTIONS_KEY_ENV && !e.is_preview);
+        const key = have?.value || randomBytes(32).toString('base64');
+        deps.secret(key);
+        stageEnv.push({ key: ACTIONS_KEY_ENV, value: key, buildTime: true });
+    }
+    const stageSurface = {
+        env: stageEnv.map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
+        resources: stageResources(subject),
+    };
+    const violations = assertStageIsolated({
+        kind,
+        prod: {
+            env: [...prodEnv, ...greenEnv]
+                .filter((e) => !e.is_preview && e.value !== undefined)
+                .map((e) => ({ name: e.key, class: envClass(e.key), value: e.value })),
+            resources: prodResources(subject),
+            internalHosts: Object.values(prodResources(subject)),
+        },
+        stage: stageSurface,
+    });
+    if (violations.length > 0) {
+        // Stage fails closed for itself: nothing is written to it, production's structure goes on.
+        await stageFailed(deps, subject, `blocked:${violations.join(',')}`);
+        return;
+    }
+    // Stage's credentials are tried against production before they are written; one that production accepts
+    // blocks stage (nothing is written to it), and what was tried is recorded by name so the copy slice sees it.
+    const stageValues = new Map((await coolify.listEnvs(appId))
+        .filter((e) => !e.is_preview && e.value !== undefined)
+        .map((e) => [e.key, e.value]));
+    for (const e of stageEnv)
+        stageValues.set(e.key, e.value);
+    const isolationHash = stageIsolationHash(stageSurface);
+    let probeResult;
+    try {
+        probeResult = await runStageProbes(buildStageProbes({
+            port: deps.stageGuards?.probes,
+            stage: stageValues,
+            database: subject.database,
+            prod: new Map(prodEnv
+                .filter((e) => !e.is_preview && e.value !== undefined)
+                .map((e) => [e.key, e.value])),
+        }));
+    }
+    catch (error) {
+        // A connection URL that cannot be read: stage is blocked, production goes on.
+        await stageFailed(deps, subject, 'blocked:database', error);
+        return;
+    }
+    const probes = stageProbesRecord(probeResult, isolationHash, stageValues);
+    if (probeResult.failed.length > 0) {
+        deps.record(bgKey.stageProbes(subject.id), probes.value);
+        await stageFailed(deps, subject, `blocked:${probeResult.failed.join(',')}`);
+        return;
+    }
+    if (!(await ensureStageGate(deps, subject))) {
+        await stageFailed(deps, subject, 'blocked:gate');
+        return;
+    }
+    await upsertEnv(deps, appId, stageEnv);
+    deps.record(bgKey.stageIsolation(subject.id), isolationHash);
+    deps.record(bgKey.stageProbes(subject.id), probes.value);
+    await deps.persist();
     const live = await coolify.getApplication(appId);
     if (live.status === undefined || !deps.isRunning(live.status)) {
-        const built = await waitForNewDeployment(coolify, appId, noDeploy, deps.runtime, deps.sleep, `${deps.label} ${name}`, `${name} stays as it was`);
+        // Stage is a test copy: a failed build or health check must not fail production's structure apply.
+        // The next apply retries it (the plan keeps the step while the state is `unhealthy`).
+        let built;
+        try {
+            built = await waitForNewDeployment(coolify, appId, noDeploy, deps.runtime, deps.sleep, `${deps.label} ${name}`, `${name} stays as it was`);
+        }
+        catch (error) {
+            await stageFailed(deps, subject, 'unhealthy', error);
+            return;
+        }
         await recordBuiltCommit(coolify, { appId, deploymentUuid: built.deploymentUuid, name: subject.id }, (key, value) => {
             if (key.startsWith('built_commit_'))
                 deps.record(bgKey.stage(subject.id), value);
         });
     }
+    deps.record(bgKey.stageState(subject.id), 'ok');
+    await deps.persist();
+}
+/**
+ * Stage fails closed for itself only: its state is recorded and the apply of production goes on. The log line is
+ * fixed text and the error name; the cause can echo a credential, so it is never logged.
+ */
+async function stageFailed(deps, subject, state, error) {
+    const name = error === undefined ? 'refused' : error instanceof Error ? error.name : 'unknown';
+    console.error(`${deps.label}: stage is ${state.split(':')[0]} (${name}); production goes on`);
+    deps.record(bgKey.stageState(subject.id), state);
+    await deps.persist();
+}
+/**
+ * The Access gate over the stage host, made once. `false` when making it failed: stage is then blocked and not
+ * written to. No gate dependency: nothing is recorded (not run) and stage goes on.
+ */
+async function ensureStageGate(deps, subject) {
+    const gate = deps.stageGuards?.gate;
+    if (!gate || deps.recorded()[bgKey.stageGate(subject.id)])
+        return true;
+    let id;
+    try {
+        id = (await gate.create()).id;
+    }
+    catch (error) {
+        // An Access error can echo the request, which names the people allowed in: only its name is logged.
+        console.error(`${deps.label}: making the Access gate failed (${error instanceof Error ? error.name : 'unknown'})`);
+        return false;
+    }
+    deps.record(bgKey.stageGate(subject.id), id);
+    await deps.persist();
+    return true;
 }
 async function stageAppId(deps, subject, name, serverUuid) {
     return ensureGitApp(deps, subject, {