@wtfalch/foundry 0.10.0 → 0.11.0

package/dist/apply.d.ts

@@ -11,6 +11,13 @@ import type { AppliedState } from './state.js';
  * `@wtfalch/audit` records every plan and apply — who, when, the plan, the
  * result.
  */
+/** What {@link PlanApply.restore} put back: resource keys and env names, never a value. */
+export interface AdoptionRestored {
+    restored: string[];
+    envDeleted: string[];
+    /** Connector rows whose TUNNEL_TOKEN was left because it is not the one foundry wrote. */
+    tokenLeft?: string[];
+}
 export interface PlanApply {
     /** Reads live state from Zitadel, Coolify and Cloudflare and diffs it
      * against the declared org (#19 "Done when"). */
@@ -38,4 +45,13 @@ export interface PlanApply {
      * `destroy` only tears down what's left.
      */
     destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
+    /**
+     * Puts an adopted app back as the snapshot recorded it (#311): the settings
+     * it had, its old env values, and none of the env names foundry added. Marks
+     * each adoption `restored`. Refused unless `confirmedOrgName` matches the
+     * org's `displayName`, once the snapshot is `confirmed` (the first
+     * successful apply after the adopting one), and, before any write, when the
+     * snapshot's vault entry is missing.
+     */
+    restore(id: OrgId, confirmedOrgName: string): Promise<AdoptionRestored>;
 }

package/dist/index.d.ts

@@ -8,9 +8,10 @@ export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState } from './state.js';
 export type { PlanStep, UnmanagedItem, Plan } from './plan.js';
-export type { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from './store.js';
+export type { Adoption, AdoptionKind, AdoptionState, AdoptionStore, DeclaredOrgStore, PlatformStore, RequestedChangeStore, } from './store.js';
+export type { AdoptionVault } from './plan/adoption-vault.js';
 export type { PlanApply } from './apply.js';
-export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
+export { createPostgresAdoptionStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';

package/dist/index.js

@@ -2,7 +2,7 @@ export { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, appEntry, validateBuyerIdentity, vali
 export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
 export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
-export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
+export { createPostgresAdoptionStore, createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
 export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';

package/dist/migrations/0031_adoptions.sql

@@ -0,0 +1,37 @@
+-- @wtfalch/foundry: what foundry recorded before it first changed a live
+-- resource it took over in place (#311), and the org's declared live
+-- database. Mirrors `src/store/schema.ts`'s `foundryAdoptions` and
+-- `declaredOrgs.hostingAdopt`.
+--
+-- `settings` holds non-secret settings only. The secret part of the snapshot
+-- (env values) lives in the host's vault under `vault_ref`; no env value, URL
+-- or secret is ever written here. `kind` lists every kind the later slices add
+-- (tunnel, connector, access) so none of them needs to change this check.
+-- `state` moves adopted -> confirmed or restored or released. A row goes with
+-- its org (`on delete cascade`), so destroying a test org needs no extra step.
+--
+-- `hosting_adopt` is `HostingConfig.adopt`, null when the org adopts nothing.
+-- An entry's own `adopt` lives inside `hosting_entries` and needs no column.
+--
+-- Safe to run twice: nothing is dropped or rewritten.
+
+create table if not exists foundry_adoptions (
+  org_id        text not null,
+  resource_key  text not null,
+  kind          text not null,
+  taken_at      timestamptz not null,
+  settings      jsonb not null default '{}'::jsonb,
+  vault_ref     text,
+  state         text not null default 'adopted',
+
+  constraint foundry_adoptions_pkey primary key (org_id, resource_key),
+  constraint foundry_adoptions_org_fkey
+    foreign key (org_id) references foundry_declared_orgs (id) on delete cascade,
+  constraint foundry_adoptions_kind_check
+    check (kind in ('app', 'database', 'tunnel', 'connector', 'access')),
+  constraint foundry_adoptions_state_check
+    check (state in ('adopted', 'confirmed', 'restored', 'released'))
+);
+
+alter table foundry_declared_orgs
+  add column if not exists hosting_adopt jsonb;

package/dist/org.d.ts

@@ -208,6 +208,15 @@ export interface HostingConfig {
     issuerApps: IssuerApp[];
     /** One entry per app the org runs. */
     entries: HostingEntry[];
+    /** Live resources foundry takes over in place instead of creating. */
+    adopt?: {
+        /** The Coolify uuid of the org's live database, taken over as `<slug>-db`. */
+        database?: string;
+        /** The id of the org's live Cloudflare tunnel: its routes are merged, never overwritten (#312). Requires `tunnel`. */
+        tunnel?: string;
+        /** The Coolify uuid of the live `cloudflared` app that dials into `tunnel` (#312). Requires `tunnel`. */
+        connectorApp?: string;
+    };
 }
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
@@ -257,6 +266,10 @@ export interface HostingEntry {
      * this map.
      */
     env: Record<string, EnvValue>;
+    /** Takes over the live Coolify app with this uuid instead of creating one. */
+    adopt?: {
+        app: string;
+    };
     /** What the entry signs in through. Absent means it uses nothing. */
     uses?: HostingEntryUses;
 }
@@ -304,6 +317,12 @@ export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
  * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
  *   unique, and at most one entry has a `database`, because the one
  *   `<slug>_rt` runtime role cannot serve two apps.
+ * - An adopted uuid (`entries[].adopt.app`, `adopt.database`) is non-empty
+ *   and only lowercase letters and digits (it goes into a URL path), and no two
+ *   entries adopt the same app. `adopt.database` needs an entry with `database`.
+ * - `adopt.tunnel` is a Cloudflare tunnel id (a UUID), `adopt.connectorApp` a
+ *   Coolify uuid that no entry or database adopts. `connectorApp` needs
+ *   `tunnel`, and both need `hosting.tunnel` (#312).
  */
 export declare function validateHosting(hosting: HostingConfig, names?: {
     domain: string | null;

package/dist/org.js

@@ -13,6 +13,9 @@ export const APP_ENV_SOURCES = new Set([
     'aiOrganisationId',
     'mailDomain',
 ]);
+const ADOPT_UUID = /^[a-z0-9]+$/;
+/** A Cloudflare tunnel id: a lowercase UUID with hyphens (#312). */
+const TUNNEL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
 const HOSTING_BUILD_PACKS = new Set([
     'dockerfile',
@@ -31,6 +34,12 @@ const HOSTING_BUILD_PACKS = new Set([
  * - Every `entries[]` entry follows {@link validateHostingEntry}; keys are
  *   unique, and at most one entry has a `database`, because the one
  *   `<slug>_rt` runtime role cannot serve two apps.
+ * - An adopted uuid (`entries[].adopt.app`, `adopt.database`) is non-empty
+ *   and only lowercase letters and digits (it goes into a URL path), and no two
+ *   entries adopt the same app. `adopt.database` needs an entry with `database`.
+ * - `adopt.tunnel` is a Cloudflare tunnel id (a UUID), `adopt.connectorApp` a
+ *   Coolify uuid that no entry or database adopts. `connectorApp` needs
+ *   `tunnel`, and both need `hosting.tunnel` (#312).
  */
 export function validateHosting(hosting, names) {
     if (hosting.tunnel && !hosting.enabled) {
@@ -60,7 +69,27 @@ export function validateHosting(hosting, names) {
     if (hosting.enabled && !appEntry(hosting)) {
         return `hosting.enabled requires an entry keyed '${APP_ENTRY_KEY}'`;
     }
+    if (hosting.adopt?.database !== undefined && !hosting.adopt.database) {
+        return 'hosting.adopt.database needs a non-empty uuid';
+    }
+    if (hosting.adopt?.database && !ADOPT_UUID.test(hosting.adopt.database)) {
+        return 'hosting.adopt.database must be lowercase letters and digits only';
+    }
+    const { tunnel: adoptedTunnel, connectorApp } = hosting.adopt ?? {};
+    if (adoptedTunnel !== undefined && !TUNNEL_ID.test(adoptedTunnel)) {
+        return 'hosting.adopt.tunnel must be a Cloudflare tunnel id (a lowercase UUID with hyphens)';
+    }
+    if (connectorApp !== undefined && !ADOPT_UUID.test(connectorApp)) {
+        return 'hosting.adopt.connectorApp must be a non-empty uuid of lowercase letters and digits only';
+    }
+    if ((connectorApp === undefined) !== (adoptedTunnel === undefined)) {
+        return 'hosting.adopt.tunnel and hosting.adopt.connectorApp must be declared together';
+    }
+    if ((adoptedTunnel !== undefined || connectorApp !== undefined) && !hosting.tunnel) {
+        return 'hosting.adopt.tunnel and hosting.adopt.connectorApp require hosting.tunnel';
+    }
     const seenKeys = new Set();
+    const seenAdopted = new Set();
     for (const entry of hosting.entries) {
         if (seenKeys.has(entry.key)) {
             return `hosting.entries key '${entry.key}' is not unique`;
@@ -69,10 +98,33 @@ export function validateHosting(hosting, names) {
         const invalid = validateHostingEntry(entry, hosting.enabled);
         if (invalid)
             return invalid;
+        if (entry.adopt) {
+            if (!entry.adopt.app)
+                return `hosting entry '${entry.key}' adopt.app needs a non-empty uuid`;
+            if (!ADOPT_UUID.test(entry.adopt.app)) {
+                return `hosting entry '${entry.key}' adopt.app must be lowercase letters and digits only`;
+            }
+            if (seenAdopted.has(entry.adopt.app)) {
+                return `hosting entry '${entry.key}' adopts an app another entry already adopts`;
+            }
+            seenAdopted.add(entry.adopt.app);
+            if (entry.adopt.app === hosting.adopt?.database) {
+                return `hosting entry '${entry.key}' adopts the same uuid as hosting.adopt.database`;
+            }
+            if (entry.database && !hosting.adopt?.database) {
+                return `hosting entry '${entry.key}' adopts its app and sets database, so hosting.adopt.database must name the live database`;
+            }
+        }
         const invalidAuth = validateEntryAuth(entry, hosting, names?.domain);
         if (invalidAuth)
             return invalidAuth;
     }
+    if (hosting.adopt?.database && !hosting.entries.some((entry) => entry.database)) {
+        return 'hosting.adopt.database is set, so an entry must set database';
+    }
+    if (connectorApp && (seenAdopted.has(connectorApp) || connectorApp === hosting.adopt?.database)) {
+        return 'hosting.adopt.connectorApp is the uuid of an adopted app or database';
+    }
     const invalidNames = validateEntryHostnames(hosting, names);
     if (invalidNames)
         return invalidNames;

package/dist/plan/adopt.d.ts

@@ -0,0 +1,112 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { Adoption } from '../store.js';
+/**
+ * Adoption (#311): foundry takes over a hand-made Coolify app or database
+ * where it is. Nothing in this file holds an env value: an env var is named,
+ * never quoted, in a detail line, an error or a blocked item (rule 6).
+ */
+interface AdoptedBase {
+    /** The `foundry_adoptions.resource_key`, and the `coolify:adopt` step's key. */
+    resourceKey: string;
+    uuid: string;
+}
+/**
+ * One app (with the entry that adopts it) or database an org declares by uuid,
+ * or (#312) its Cloudflare tunnel (`uuid` is the tunnel id) or the Coolify app
+ * that runs `cloudflared` for it.
+ */
+export type AdoptedResource = (AdoptedBase & {
+    kind: 'database';
+}) | (AdoptedBase & {
+    kind: 'app';
+    entry: HostingEntry;
+}) | (AdoptedBase & {
+    kind: 'tunnel';
+}) | (AdoptedBase & {
+    kind: 'connector';
+});
+/** The `foundry_adoptions.resource_key` of the org's adopted tunnel: also its `serviceIds` key (#312). */
+export declare const adoptedTunnelKey: (org: DeclaredOrg) => string;
+/** The `foundry_adoptions.resource_key` of the org's adopted connector app (#312). */
+export declare const adoptedConnectorKey: (org: DeclaredOrg) => string;
+/** Every resource the org adopts, the database first, then the apps, the tunnel and its connector. */
+export declare function adoptedResources(org: DeclaredOrg): AdoptedResource[];
+/**
+ * Every uuid the org declares as adopted, whether or not hosting is enabled
+ * now: a uuid in this set is never stopped or deleted by foundry (#311).
+ */
+export declare function declaredAdoptUuids(org: DeclaredOrg): Set<string>;
+/**
+ * A snapshot is ACTIVE when its row is `adopted` or `confirmed` and the uuid
+ * it recorded is the uuid the org declares now (#311). Only then may foundry
+ * write to the live resource.
+ */
+export declare function isActiveSnapshot(row: Adoption | null | undefined, uuid: string): boolean;
+/**
+ * A row in `adopted`, `confirmed` or `restored` protects its key: foundry never
+ * manages, stops or deletes that resource as its own. Only `released` lets go (#311).
+ */
+export declare function protectsKey(row: Adoption | null | undefined): boolean;
+/** Where the secret part of a snapshot lives in the `AdoptionVault`. */
+export declare function adoptionVaultRef(org: DeclaredOrg, resource: AdoptedResource): string;
+export type LiveApp = Record<string, unknown>;
+export declare function snapshotAppSettings(live: LiveApp): Record<string, unknown>;
+export declare const bareName: (name: string) => string;
+export declare const liveNames: (live: LiveApp) => string[];
+/**
+ * What an adopted entry changes on its live app: only a setting it declares
+ * that differs from live. The entry cannot tell a declared `branch`,
+ * `buildPack` or `autoDeploy` from its default, so those stay as they are; a
+ * `null` folder or port and an empty name list declare nothing. Never
+ * `custom_network_aliases`.
+ */
+export declare function adoptedAppPatch(entry: HostingEntry, names: readonly string[], live: LiveApp): Record<string, unknown>;
+/** One line per setting the patch changes, old value beside new. */
+export declare function adoptedPatchDetails(patch: Record<string, unknown>, live: LiveApp): string[];
+/**
+ * The PATCH body that puts an app's snapshot settings back. A field is sent
+ * only when the entry's declaration would have changed it from the snapshot
+ * (`adoptedAppPatch`), so a setting foundry never touched, or a person edited
+ * later, stays. With no entry, a field is sent when `live` differs from the
+ * snapshot. Coolify reads `fqdn` but takes `domains`. A field the snapshot had
+ * as null is cleared the way the plain app path clears it: a folder back to
+ * `/`, domains to the empty list. A port is never cleared, as on that path.
+ */
+export declare function restoreAppPatch(entry: HostingEntry | undefined, names: readonly string[], settings: Record<string, unknown>, live: LiveApp): Record<string, unknown>;
+/** One route of a tunnel's ingress list. Other fields (`originRequest`, `path`) ride along untouched. */
+export interface IngressRoute {
+    hostname?: string;
+    service: string;
+    [field: string]: unknown;
+}
+/** A hostname as compared: lower case, no trailing dot (DNS names ignore both). */
+export declare const normalizeHostname: (hostname: string) => string;
+/**
+ * What the merge leaves alone: every live route that is not for a declared
+ * name and not foundry's own route for a name it dropped. Whatever its shape:
+ * a hostname, only a `path`, or neither.
+ */
+export declare function foreignRoutes(live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>): IngressRoute[];
+/** The declared names whose live routes the merge replaces: there are some, and they are not already foundry's one route. */
+export declare function replacedNames(live: readonly IngressRoute[], declared: readonly string[], service: string): string[];
+/** The names foundry removes from `live`: written, no longer declared, still its own route. */
+export declare const removedNames: (live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>) => string[];
+/**
+ * The ingress list an adopted tunnel gets (#312): the declared exact names,
+ * then every foreign live route in its live order and unchanged, with the
+ * snapshot's routes for a name foundry dropped put back among them, then the
+ * declared wildcards, then the live catch-all as it is. Only a live list that
+ * does not end in a catch-all gets `http_status:404`.
+ */
+export declare function mergeIngress(live: readonly IngressRoute[], declared: readonly string[], service: string, written: ReadonlySet<string>, snapshot: readonly IngressRoute[]): IngressRoute[];
+/**
+ * The ingress list restore writes (#312): the live list without foundry's own
+ * route for a name it wrote (`written` accumulates for the life of the
+ * snapshot), plus the snapshot's routes for that name. A name with no live
+ * route that is exactly foundry's is left alone, as is a route a person added
+ * or edited, and the live catch-all. The `http_status:404` foundry appended is
+ * removed only while it is still last and the snapshot had no catch-all; an
+ * empty snapshot keeps the live catch-all, or gets one.
+ */
+export declare function restoreIngress(live: readonly IngressRoute[], snapshot: readonly IngressRoute[], service: string, written: ReadonlySet<string>): IngressRoute[];
+export {};

package/dist/plan/adopt.js

@@ -0,0 +1,252 @@
+import { appStepKey } from './platform-diff.js';
+/** The `foundry_adoptions.resource_key` of the org's adopted tunnel: also its `serviceIds` key (#312). */
+export const adoptedTunnelKey = (org) => `cloudflare:tunnel:${org.id}`;
+/** The `foundry_adoptions.resource_key` of the org's adopted connector app (#312). */
+export const adoptedConnectorKey = (org) => `cloudflare:connector:${org.id}`;
+/** Every resource the org adopts, the database first, then the apps, the tunnel and its connector. */
+export function adoptedResources(org) {
+    if (!org.hosting.enabled)
+        return [];
+    const database = org.hosting.adopt?.database;
+    const resources = [];
+    if (database) {
+        resources.push({ resourceKey: `coolify:database:${org.id}`, kind: 'database', uuid: database });
+    }
+    for (const entry of org.hosting.entries) {
+        if (!entry.adopt)
+            continue;
+        resources.push({
+            resourceKey: `coolify:app:${appStepKey(org, entry.key)}`,
+            kind: 'app',
+            uuid: entry.adopt.app,
+            entry,
+        });
+    }
+    const { tunnel, connectorApp } = org.hosting.adopt ?? {};
+    if (tunnel)
+        resources.push({ resourceKey: adoptedTunnelKey(org), kind: 'tunnel', uuid: tunnel });
+    if (connectorApp) {
+        resources.push({
+            resourceKey: adoptedConnectorKey(org),
+            kind: 'connector',
+            uuid: connectorApp,
+        });
+    }
+    return resources;
+}
+/**
+ * Every uuid the org declares as adopted, whether or not hosting is enabled
+ * now: a uuid in this set is never stopped or deleted by foundry (#311).
+ */
+export function declaredAdoptUuids(org) {
+    const uuids = new Set();
+    if (org.hosting.adopt?.database)
+        uuids.add(org.hosting.adopt.database);
+    if (org.hosting.adopt?.tunnel)
+        uuids.add(org.hosting.adopt.tunnel);
+    if (org.hosting.adopt?.connectorApp)
+        uuids.add(org.hosting.adopt.connectorApp);
+    for (const entry of org.hosting.entries)
+        if (entry.adopt)
+            uuids.add(entry.adopt.app);
+    return uuids;
+}
+/**
+ * A snapshot is ACTIVE when its row is `adopted` or `confirmed` and the uuid
+ * it recorded is the uuid the org declares now (#311). Only then may foundry
+ * write to the live resource.
+ */
+export function isActiveSnapshot(row, uuid) {
+    return (row !== null &&
+        row !== undefined &&
+        (row.state === 'adopted' || row.state === 'confirmed') &&
+        row.settings.uuid === uuid);
+}
+/**
+ * A row in `adopted`, `confirmed` or `restored` protects its key: foundry never
+ * manages, stops or deletes that resource as its own. Only `released` lets go (#311).
+ */
+export function protectsKey(row) {
+    return row?.state === 'adopted' || row?.state === 'confirmed' || row?.state === 'restored';
+}
+/** Where the secret part of a snapshot lives in the `AdoptionVault`. */
+export function adoptionVaultRef(org, resource) {
+    return `foundry:adopt:${org.id}:${resource.kind === 'app' ? `app:${resource.entry.key}` : resource.kind}`;
+}
+/** Coolify's field names for the non-secret settings an app snapshot keeps. */
+const APP_SETTING_FIELDS = [
+    'fqdn',
+    'git_branch',
+    'base_directory',
+    'publish_directory',
+    'build_pack',
+    'ports_exposes',
+    'health_check_enabled',
+    'health_check_path',
+    'health_check_port',
+    'health_check_method',
+    'health_check_return_code',
+    'health_check_scheme',
+    'health_check_interval',
+    'health_check_timeout',
+    'health_check_retries',
+    'health_check_start_period',
+    'custom_network_aliases',
+    'is_auto_deploy_enabled',
+    'limits_memory',
+    'limits_memory_swap',
+    'limits_memory_swappiness',
+    'limits_memory_reservation',
+    'limits_cpus',
+    'limits_cpuset',
+    'limits_cpu_shares',
+];
+export function snapshotAppSettings(live) {
+    return Object.fromEntries(APP_SETTING_FIELDS.map((field) => [field, live[field] ?? null]));
+}
+export const bareName = (name) => name.trim().replace(/^https?:\/\//, '');
+export const liveNames = (live) => typeof live.fqdn === 'string' ? live.fqdn.split(',').filter(Boolean).map(bareName) : [];
+/**
+ * What an adopted entry changes on its live app: only a setting it declares
+ * that differs from live. The entry cannot tell a declared `branch`,
+ * `buildPack` or `autoDeploy` from its default, so those stay as they are; a
+ * `null` folder or port and an empty name list declare nothing. Never
+ * `custom_network_aliases`.
+ */
+export function adoptedAppPatch(entry, names, live) {
+    const patch = {};
+    const folderField = entry.buildPack === 'static' ? 'publish_directory' : 'base_directory';
+    if (entry.folder !== null && (live[folderField] ?? '/') !== `/${entry.folder}`) {
+        patch[folderField] = `/${entry.folder}`;
+    }
+    if (entry.port !== null &&
+        entry.buildPack !== 'static' &&
+        `${live.ports_exposes}` !== `${entry.port}`) {
+        patch.ports_exposes = String(entry.port);
+    }
+    if (names.length > 0 && [...names].sort().join() !== liveNames(live).sort().join()) {
+        patch.domains = names.join(',');
+    }
+    return patch;
+}
+/** One line per setting the patch changes, old value beside new. */
+export function adoptedPatchDetails(patch, live) {
+    return Object.entries(patch).map(([field, value]) => {
+        const old = field === 'domains' ? live.fqdn : live[field];
+        return `${field}: ${old ?? 'unset'} -> ${value}`;
+    });
+}
+/**
+ * The PATCH body that puts an app's snapshot settings back. A field is sent
+ * only when the entry's declaration would have changed it from the snapshot
+ * (`adoptedAppPatch`), so a setting foundry never touched, or a person edited
+ * later, stays. With no entry, a field is sent when `live` differs from the
+ * snapshot. Coolify reads `fqdn` but takes `domains`. A field the snapshot had
+ * as null is cleared the way the plain app path clears it: a folder back to
+ * `/`, domains to the empty list. A port is never cleared, as on that path.
+ */
+export function restoreAppPatch(entry, names, settings, live) {
+    const isStatic = (entry?.buildPack ?? settings.build_pack) === 'static';
+    const folderField = isStatic ? 'publish_directory' : 'base_directory';
+    const changed = new Set(Object.keys(entry ? adoptedAppPatch(entry, names, settings) : {}));
+    if (!entry) {
+        if ((live[folderField] ?? '/') !== (settings[folderField] ?? '/'))
+            changed.add(folderField);
+        if (`${live.ports_exposes}` !== `${settings.ports_exposes}`)
+            changed.add('ports_exposes');
+        if (liveNames(settings).sort().join() !== liveNames(live).sort().join())
+            changed.add('domains');
+    }
+    const patch = {};
+    if (changed.has(folderField))
+        patch[folderField] = settings[folderField] ?? '/';
+    if (changed.has('domains'))
+        patch.domains = settings.fqdn ?? '';
+    if (!isStatic && settings.ports_exposes != null && changed.has('ports_exposes')) {
+        patch.ports_exposes = settings.ports_exposes;
+    }
+    return patch;
+}
+const isWildcard = (route) => route.hostname?.startsWith('*') ?? false;
+const isCatchAll = (route) => route !== undefined && route.hostname === undefined && route.path === undefined;
+/** A hostname as compared: lower case, no trailing dot (DNS names ignore both). */
+export const normalizeHostname = (hostname) => hostname.toLowerCase().replace(/\.$/, '');
+const sameName = (a, b) => a !== undefined && normalizeHostname(a) === normalizeHostname(b);
+const hasName = (names, hostname) => hostname !== undefined && [...names].some((name) => sameName(hostname, name));
+/** The route foundry writes for a name: nothing but the hostname and the service. */
+const isFoundryRoute = (route, service) => route.service === service && Object.keys(route).length === 2;
+/** Puts `back` before the first wildcard or hostname-less route of `rest`, so a person's order stays. */
+function putBack(rest, back) {
+    const at = rest.findIndex((route) => route.hostname === undefined || isWildcard(route));
+    return at < 0 ? [...rest, ...back] : [...rest.slice(0, at), ...back, ...rest.slice(at)];
+}
+/** A live route foundry wrote for a name it dropped: written, no longer declared, exactly foundry's own. */
+const isDroppedRoute = (route, declared, service, written) => hasName(written, route.hostname) &&
+    !hasName(declared, route.hostname) &&
+    isFoundryRoute(route, service);
+/**
+ * What the merge leaves alone: every live route that is not for a declared
+ * name and not foundry's own route for a name it dropped. Whatever its shape:
+ * a hostname, only a `path`, or neither.
+ */
+export function foreignRoutes(live, declared, service, written) {
+    return live.filter((route) => !hasName(declared, route.hostname) && !isDroppedRoute(route, declared, service, written));
+}
+/** The declared names whose live routes the merge replaces: there are some, and they are not already foundry's one route. */
+export function replacedNames(live, declared, service) {
+    return declared.filter((hostname) => {
+        const same = live.filter((route) => sameName(route.hostname, hostname));
+        const [only] = same;
+        return only !== undefined && !(same.length === 1 && isFoundryRoute(only, service));
+    });
+}
+/** The names foundry removes from `live`: written, no longer declared, still its own route. */
+export const removedNames = (live, declared, service, written) => [
+    ...new Set(live
+        .filter((route) => isDroppedRoute(route, declared, service, written))
+        .map((route) => route.hostname)),
+];
+/**
+ * The ingress list an adopted tunnel gets (#312): the declared exact names,
+ * then every foreign live route in its live order and unchanged, with the
+ * snapshot's routes for a name foundry dropped put back among them, then the
+ * declared wildcards, then the live catch-all as it is. Only a live list that
+ * does not end in a catch-all gets `http_status:404`.
+ */
+export function mergeIngress(live, declared, service, written, snapshot) {
+    const dropped = removedNames(live, declared, service, written);
+    const tail = live.at(-1);
+    const foreign = foreignRoutes(live, declared, service, written);
+    const catchAll = isCatchAll(tail) ? tail : { service: 'http_status:404' };
+    const middle = isCatchAll(tail) ? foreign.slice(0, -1) : foreign;
+    const back = snapshot.filter((route) => hasName(dropped, route.hostname));
+    const route = (hostname) => ({ hostname, service });
+    return [
+        ...declared.filter((hostname) => !hostname.startsWith('*')).map(route),
+        ...putBack(middle, back),
+        ...declared.filter((hostname) => hostname.startsWith('*')).map(route),
+        catchAll,
+    ];
+}
+/**
+ * The ingress list restore writes (#312): the live list without foundry's own
+ * route for a name it wrote (`written` accumulates for the life of the
+ * snapshot), plus the snapshot's routes for that name. A name with no live
+ * route that is exactly foundry's is left alone, as is a route a person added
+ * or edited, and the live catch-all. The `http_status:404` foundry appended is
+ * removed only while it is still last and the snapshot had no catch-all; an
+ * empty snapshot keeps the live catch-all, or gets one.
+ */
+export function restoreIngress(live, snapshot, service, written) {
+    const isOurs = (route) => hasName(written, route.hostname) && isFoundryRoute(route, service);
+    const swapped = (route) => hasName(live.filter(isOurs).map((r) => r.hostname), route.hostname);
+    const appended = snapshot.length > 0 &&
+        !isCatchAll(snapshot.at(-1)) &&
+        isCatchAll(live.at(-1)) &&
+        live.at(-1)?.service === 'http_status:404';
+    const rest = live.filter((route, index) => !isOurs(route) && !(appended && index === live.length - 1));
+    const restored = putBack(rest, snapshot.filter(swapped));
+    return snapshot.length === 0 && !isCatchAll(restored.at(-1))
+        ? [...restored, { service: 'http_status:404' }]
+        : restored;
+}

package/dist/plan/adoption-vault.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Where an adoption keeps the secret part of its snapshot (#311): the live
+ * app's env values. The row in `foundry_adoptions` holds only the ref. Same
+ * shape as the `heldKeys` port (`../bootstrap/bootstrap.ts`).
+ */
+export interface AdoptionVault {
+    put(ref: string, value: string): Promise<void>;
+    resolve(ref: string): Promise<string | null>;
+}

package/dist/plan/adoption-vault.js

@@ -0,0 +1 @@
+export {};

package/dist/plan/broker-entries.d.ts

@@ -20,7 +20,7 @@ export declare function brokerEntryAppliedScopeKey(entryKey: string): string;
 /** The foreign entries the last write found invalid, as a JSON array of names. */
 export declare function brokerEntryWarningsScopeKey(entryKey: string): string;
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
-export declare function entryAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
+export declare function entryAuthEnv(org: DeclaredOrg, entry: Pick<HostingEntry, 'key' | 'uses'>, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
 /** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
 export declare function entryAuthEnvAppliedScopeKey(entryKey: string): string;
 /** What a broker entry must say, without its key. */
@@ -74,9 +74,13 @@ export declare class PlatformBrokerPort implements BrokerPort {
     });
     appId(): Promise<string>;
     listEnvs(): Promise<{
+        uuid?: string;
         key: string;
         value: string;
         is_preview: boolean;
+        is_buildtime?: boolean;
+        is_literal?: boolean;
+        is_multiline?: boolean;
     }[]>;
     setAuthApps(raw: string): Promise<void>;
     deploy(): Promise<void>;

package/dist/plan/cloudflared-connector.d.ts

@@ -29,12 +29,20 @@ export interface EnsureCloudflaredConnectorInput {
     tunnelId: string;
     /** Fixed name, found before created -- so a second apply reuses this app rather than making a second one. */
     appName: string;
-    projectUuid: string;
-    environment: {
+    /** Needed to find the app by name or create it; an `adopted` connector needs neither. */
+    projectUuid?: string;
+    environment?: {
         id: number;
         name: string;
         uuid: string;
     };
+    /**
+     * #312: `recordedConnectorAppId` is a live app foundry adopted. It is never
+     * looked up by name or created; one that cannot be found is an error.
+     */
+    adopted?: boolean;
+    /** #312: called with the token just before `TUNNEL_TOKEN` is rewritten, so a later restore knows foundry wrote it. */
+    beforeTokenWrite?: (token: string) => Promise<void>;
     /** Called only when the app must be created -- never on the found-by-name or found-by-id paths. */
     resolveServer: () => Promise<{
         uuid: string;