@wtfalch/foundry 0.60.0 → 0.62.0

package/dist/plan/executor.d.ts

@@ -12,6 +12,8 @@ import { type DnsPort, type EdgePlatformDns } from './edge-dns.js';
 import { type EdgePlatformRateLimits, type RateLimitPort } from './edge-ratelimits.js';
 import { type EdgePlatformTunnels, type TunnelPort } from './edge-tunnels.js';
 import { type EdgePlatformZones, type ZonePort } from './edge-zones.js';
+import type { GithubDeployKeysPort } from './github-deploy-keys.js';
+import { type KeysRegistrarPort } from './keys-registrar.js';
 import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
 import { type OwnServicesPort } from './own-services.js';
@@ -1534,7 +1536,8 @@ export interface EdgePort {
      * lowercase hostname and binds the key to it
      * (`wtfalch/edge`'s `packages/service/src/keys.ts`) -- `edgeEntryKey`
      * passes `org.domain`, which `validateEntryEdge` already requires before
-     * `uses.edge` is accepted.
+     * `uses.edge` is accepted; Boule's key for a company without a domain
+     * (`org.boule.apps`) passes `<slug>.oikos.host` (`edgeKeyDomain`).
      */
     mintKey(input: {
         organisationId: string;
@@ -1579,6 +1582,12 @@ export interface EdgePort {
     zones: EdgePlatformZones;
     /** Refuses a label any hosting entry of `organisationId` already holds. Rerun whenever the org's own label set changes. */
     setReservedLabels(organisationId: string, labels: string[]): Promise<void>;
+    /**
+     * `PUT /v1/platform/organisations/:orgId/slug` with `{ slug }`: idempotent upsert, so edge accepts the
+     * company's platform hostnames. Rejects with an `EdgeApiError` of code `conflict` (the API's `409`) when
+     * another company holds the slug.
+     */
+    setOrganisationSlug(organisationId: string, slug: string): Promise<void>;
 }
 /**
  * #173: the jobs scheduler's own admin API
@@ -1785,6 +1794,8 @@ export interface FoundryStepExecutorPorts {
     workerApps?: WorkerAppPort;
     /** ADR 0002: the keys custody Worker, for a `keysCustody` secret of a Worker app. */
     workerAppKeys?: KeysCustodyPort;
+    /** F7: the keys service's per-company registrar. Without it the plan reports Boule's registrar key blocked (the host also sets `FoundryPlanApplyOptions.keysRegistrarUrl`). */
+    keysRegistrar?: KeysRegistrarPort;
     /**
      * C3: mints the credential an org's Boule reaches Archon with (org-scoped; `orgs:request` and
      * `orgs:read` for that org). Archon implements it. Every call rotates the credential (the old secret
@@ -1823,6 +1834,11 @@ export interface FoundryStepExecutorPorts {
         resolve(ref: string): Promise<string | null | undefined>;
         put?(ref: string, value: string): Promise<void>;
     };
+    /**
+     * F12: the GitHub deploy-key client (`createGithubDeployKeys`) for an entry's `uses.repo`. Without it the
+     * `github:deploy-key` step is not planned (the plan reports it blocked) and fails if run.
+     */
+    githubDeployKeys?: GithubDeployKeysPort;
     /**
      * Read access to the declared-org store, narrowed to the one query
      * `cloudflareZone` needs for its cross-org refusal check (#131) -- see that
@@ -1950,6 +1966,15 @@ export declare const BOULE_REPO = "wtfalch/boule";
 export declare const BOULE_APP_DOCKERFILE = "/Dockerfile";
 /** Boule's own `EXPOSE 3000` (its doc comment just above) -- the port its health check (#543) probes. */
 export declare const BOULE_PORT = 3000;
+/**
+ * foundry#949: kosmos (https://github.com/wtfalch/kosmos), bootstrapped from the same `wtfalch/package-template`
+ * service shape Boule is, with its own Dockerfile at the repository root, serving on 3000 (`EXPOSE 3000`) and
+ * running its migrations through `apps/host/scripts/migrate.mjs` before it serves, the same shape Boule's
+ * `migrate-and-start.sh` follows.
+ */
+export declare const KOSMOS_REPO = "wtfalch/kosmos";
+export declare const KOSMOS_APP_DOCKERFILE = "/Dockerfile";
+export declare const KOSMOS_PORT = 3000;
 export declare const LOG_DIR = "/app/logs";
 /** The company's Coolify destination (its Docker network `co-<slug>`), recorded when its first resource is created. */
 export declare const COOLIFY_DESTINATION_SCOPE_KEY = "coolify_destination";
@@ -2046,6 +2071,25 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     ownFilesOrganisationPort(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<boolean>;
     /** Whether the host's scoped ports for this own org include a broker port: the company's own broker, which its broker entries are written to. */
     ownBrokerPort(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<boolean>;
+    /**
+     * Where the workspaces database of the broker this org's entries are written to already is: in the broker's
+     * `WORKSPACES_DATABASE_URL` (`inEnv`) or as a URL held at the org's ref (`held`). The company's own broker for an
+     * org that owns its services, the shared one otherwise. Throws when the broker is not wired or a read fails,
+     * times out, or finds a held value that is no postgres URL, so a caller never takes "unknown" for "absent".
+     */
+    private workspacesDatabaseSources;
+    /**
+     * Whether the broker this org's entries are written to has `WORKSPACES_DATABASE_URL`, or a URL is held to give it.
+     * A read that fails or times out answers `false`, so the plan does not write an entry the broker cannot start
+     * with.
+     */
+    brokerHasWorkspacesDatabase(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<boolean>;
+    /**
+     * Whether foundry may make the broker's workspaces database: it can hold the URL, and a read just showed that
+     * neither the broker nor the held keys have one. A read that fails answers `false`, never "make one": a database
+     * made over a broker whose own could not be read would replace it.
+     */
+    canProvisionWorkspacesDatabase(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<boolean>;
     /** #555: the edge-routed ports this executor was built with itself (they win over edge). */
     ownEdgePorts(): Partial<Record<EdgePortName, boolean>>;
     execute(action: StepAction, context: StepExecutionContext): Promise<{
@@ -2075,6 +2119,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * in.
      */
     private cloudflareAccess;
+    /**
+     * F11 (`plan/machine-paths.ts`): one path-scoped Access application (`<host><path>`) with foundry's bypass
+     * policy, so a machine caller is not stopped by the host's gate; or its removal. The stem of the step key
+     * (`mp-<hash>`) names it; the recorded `host/path` is kept only to word the removal.
+     */
+    private cloudflareMachineBypass;
     /**
      * `plan/diff.ts`'s `planGates`: makes, changes or deletes one declared
      * gate through edge. A create needs the platform's recorded Access provider,
@@ -2397,6 +2447,57 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * a step for it fails, which the next plan reports instead.
      */
     private coolifyBlueGreen;
+    /**
+     * `coolify:workspace` (`plan/workspace.ts`): a server entry's private workspace on the primary server. It is
+     * the blue/green stage (the stage app, its own empty database, the stage mail sink and the stage guards) at
+     * the workspace host, with the Access gate `planGates` made first. Nothing here makes a color, a balancer or
+     * a public name. The live app, when the entry is live, is only read for the names stage must not share.
+     */
+    private coolifyWorkspace;
+    /**
+     * The stage's own sign-in, for a workspace of an entry with `uses.auth`: the recorded organisation, client and
+     * issuer, its own workspaces key (made and held first, once) and what it must never hold, which is what the
+     * live app holds. A key is registered for redaction before it goes anywhere. Errors name the entry and the ref,
+     * never a value; every held-key read has a timeout.
+     */
+    private workspaceStageSignIn;
+    /**
+     * `coolify:workspace-broker-entry` (`plan/workspace-sign-in.ts`): the broker entry `<slug>-<key>-work` of a
+     * workspace with sign-in, written with the stage app's own `AUTH_APP_KEY` and the hash of its own workspaces
+     * key. It never reads or writes the live entry. Records what it wrote, never a key.
+     */
+    private coolifyWorkspaceBrokerEntry;
+    /**
+     * `coolify:workspaces-database` (`plan/broker-workspaces-database.ts`): the broker's workspaces database, made
+     * beside the broker (the platform's project and network, or the company's own for an org that owns its services)
+     * and held at `workspacesDatabaseRef(org)`. Reads the broker and the held keys again first and makes nothing when
+     * either has a URL, so a database is never made over one. Records nothing: the held URL is the record, and a
+     * database made but not held is found by name on the next apply. The database stays when the org is removed, as
+     * the held keys do.
+     */
+    private coolifyWorkspacesDatabase;
+    /**
+     * `coolify:promote`: moves a live workspace entry's app to `HostingEntry.liveCommit`. Patches `git_commit_sha`,
+     * deploys and waits for the deployment, then records `ws.<key>.livecommit`. A failure after the patch leaves the
+     * app configured for the new commit with the old container still running and no marker, so the next apply
+     * patches and deploys again.
+     */
+    private coolifyPromote;
+    /**
+     * The commit a workspace entry's live app is made from: the newest finished deployment of its workspace's stage
+     * app, else the commit recorded when the workspace was last applied. Recorded as `ws.<key>.commit`. Throws,
+     * before any app is made, when there is none.
+     */
+    private workspaceCommit;
+    /**
+     * The Coolify GitHub source an app of `repo` is created through: the company's own (`coolify:github-source`,
+     * recorded by that step) when `repo` is under the company's GitHub account, else the platform's.
+     */
+    private githubAppUuidFor;
+    /** The company's Coolify GitHub source (`plan/github-source.ts`): made from the platform GitHub App's held keys and the company's installation id. */
+    private coolifyGithubSource;
+    /** True when no Coolify GitHub source has this uuid. A failed read counts as not gone. */
+    private githubSourceGone;
     /**
      * Stage's guards (`plan/stage-guards.ts`): the probe port the host supplied, and the Access gate over the stage
      * host. The gate is offered only when everything it needs is in hand (a domain, the platform's Access provider,
@@ -2449,6 +2550,26 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private orgPostgresServer;
     /** `coolify:org-postgres-databases` (#444): a database and its roles for each home that has none. */
     private orgPostgresDatabases;
+    /** F4 (#925): Boule's app and the calls on its env that the apps database steps make. */
+    private appsBoule;
+    /**
+     * F4 (#925) `coolify:org-apps-admin`: with `org.boule.apps` on, the `<slug>_apps_admin` role on the
+     * company's Postgres server (`plan/org-apps-admin.ts`); its URL is held and written to Boule's env as
+     * `APPS_DATABASE_ADMIN_URL`, then Boule restarts. Apps off: the retire form (no login, env row gone,
+     * nothing dropped).
+     */
+    private orgAppsAdmin;
+    /**
+     * F4 (#925) `cloudflare:apps-db-route`: the tunnel route Hyperdrive reaches the company's Postgres server
+     * by, and the `APPS_DATABASE_*` env on Boule (`plan/apps-db-route.ts`). Retire takes both away; the
+     * databases stay.
+     */
+    private appsDbRoute;
+    /**
+     * FZ `cloudflare:apps-zones`: the company slug and the zone ids Boule's managed backend names edge routes
+     * by (`plan/apps-zones.ts`). Retire takes the rows away again.
+     */
+    private appsZones;
     /**
      * `coolify:org-postgres-migrate` (#444): one home's data from its old Coolify database to the
      * company's server. Refuses before any port call unless the staging confirmation is recorded.
@@ -2569,6 +2690,11 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * broker would drop.
      */
     private coolifyBrokerEntry;
+    /**
+     * What the broker entry needs beyond its want when it declares workspaces: the hash of the held key (the key
+     * itself is registered for redaction and goes no further) and the operator's held database connection string.
+     */
+    private workspacesInputs;
     /**
      * #161: the org's Boule broker entry, `<slug>-boule`, written the way a
      * hosting entry's is: with the `AUTH_APP_KEY` `coolifyBoule` put in the
@@ -3028,16 +3154,18 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private coolifyChatRekey;
     /**
      * `plan/diff.ts`'s `planCallsService`: the org's own calls service --
-     * `wtfalch/calls`'s `packages/service`, wired to the calls Matrix stack
-     * {@link coolifyCalls} provisions and the shared LiveKit SFU (#122/#127).
-     * Static config checks run first, before any Coolify call (#128's own
-     * carried-over PR 344 review fix, restated in #145's own issue body): the
-     * calls Matrix stack must already be recorded, its MAS app must already
-     * carry its client id/secret, and the shared SFU's LiveKit credentials must
-     * already be resolvable -- none of the three is minted or guessed here.
-     * Park stops the app only, the same park-not-delete rule
-     * {@link coolifyCalls}/{@link coolifyApp} already follow (#7 corrections
-     * 1); its own database is never touched from that branch.
+     * `wtfalch/calls`'s `packages/service`, wired to the shared LiveKit SFU
+     * (#122/#127). #430: calls run transit-only (calls#93's
+     * `CALLS_ENCRYPTION=transit`), so this no longer waits on or wires a
+     * per-org Matrix stack at all -- an org whose stack is already live from
+     * before this keeps running it, unused, until a human removes it
+     * separately. Static config checks run first, before any Coolify call
+     * (#128's own carried-over PR 344 review fix, restated in #145's own
+     * issue body): the shared SFU's LiveKit credentials must already be
+     * resolvable -- not minted or guessed here. Park stops the app only, the
+     * same park-not-delete rule {@link coolifyCalls}/{@link coolifyApp}
+     * already follow (#7 corrections 1); its own database is never touched
+     * from that branch.
      */
     private coolifyCallsService;
     /**
@@ -3070,14 +3198,6 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * env and mints nothing.
      */
     private callsTokenEnvs;
-    /**
-     * Reads back the calls Matrix stack's MAS client id/secret from the MAS
-     * app's own envs ({@link CALLS_SECRET_ENV_KEYS}) -- never mints: minting
-     * either is {@link ensureCallsMatrixSecrets}'s own job, and a missing value
-     * here means that stack has not finished provisioning yet, not something
-     * this step can fix on its own.
-     */
-    private readCallsMasClientCredentials;
     /**
      * `null` once the calls service app already has a `CALLS_BINDING_SECRET` --
      * never rotated, the same rule {@link ensureAuthCookieSecret} follows for
@@ -3210,6 +3330,25 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * shape {@link coolifyAgora}'s own doc comment explains.
      */
     private coolifyBoule;
+    /**
+     * `plan/diff.ts`'s `planKosmos`: provisions the org's own kosmos
+     * (https://github.com/wtfalch/kosmos) as one more Coolify application, from
+     * that repo's root Dockerfile ({@link KOSMOS_REPO}), with a database of its
+     * own, and pushes its sign-in env. The same shape as {@link coolifyBoule},
+     * trimmed: kosmos is opt-in (`kosmosOn(org)` guards every caller, so this is
+     * never reached while it is off), has no mail, no owner seeding and no
+     * Archon credential.
+     *
+     * The sign-in env comes from `plan/kosmos.ts`'s `desiredKosmosEnv`, the same
+     * function the plan compares the live app against; it never writes a
+     * partial set. The database is `<slug>-kosmos-db`, split the same way
+     * Boule's is: the superuser URL as `DATABASE_URL_OWNER` and a `<dbName>_rt`
+     * role's URL as `DATABASE_URL`, both through `pushDatabaseUrl`.
+     *
+     * #504 (same reason {@link coolifyBoule}'s own comment gives): a brand new
+     * app is never restarted, but it is deployed once ({@link KOSMOS_DEPLOYED_SCOPE_KEY}).
+     */
+    private coolifyKosmos;
     /**
      * C3: the Archon credential of an org's Boule. Archon's mint rotates on every call, so it is called only
      * when none was pushed or the recorded push time (no secret) is 335 days old. Otherwise the held value is
@@ -3223,6 +3362,40 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * leaves one live token. `null` while the customers organisation is not recorded yet.
      */
     private ensureCustomersDirectoryCredential;
+    /** The held keys with a timeout on every call: a hung store stops the step with a plain line. */
+    private timedHeldKeys;
+    /** T3: the company's registrar key, held at `foundry:registrar:<org id>`; either step may make it. */
+    private registrarKey;
+    /**
+     * T3, customers off: takes away the registrar env foundry gave Boule. The registrar step removes the record
+     * at the broker and forgets the key. Returns true when Boule's env changed.
+     */
+    private dropRegistrarEnv;
+    /**
+     * T3: the company's record in the broker's `AUTH_REGISTRARS` (`plan/broker-registrar.ts`): its key (made
+     * and held first if the Boule step has not), its sign-in organisation, customers organisations and login
+     * host. With customers off it takes the record away, then forgets the key. The applied marker is recorded
+     * last and never holds the key; every error is redacted of it.
+     */
+    private brokerRegistrar;
+    private customerGrantsCredential;
+    /**
+     * F13, app side: an entry with `uses.customerGrants` gets `CUSTOMER_GRANTS_CREDENTIAL` (made and held first,
+     * once). An entry that had one and no longer declares the flag loses the env and the held value; each part is
+     * repeated safely, so a run that died halfway is finished by the next.
+     */
+    private customerGrantsAppEnv;
+    /** Forgets one entry's held credential and clears its marker. Held first, marker last, so a failed forget is repeated. */
+    private forgetCustomerGrantsCredential;
+    /** F13: the held credentials of entries that no longer declare the flag, forgotten after Boule stopped listing them. */
+    private forgetDroppedCustomerGrants;
+    /**
+     * F13, Boule side: the `CUSTOMER_GRANTS` value for the flagged entries (each credential made and held if it
+     * is not yet), or `value: null`. With no flagged entry left and a value foundry wrote, the env row is
+     * removed (`removed`). A flagged entry that cannot be listed yet changes nothing. Never a hand-set value
+     * it did not write.
+     */
+    private customerGrantsForBoule;
     /** `put`, tried up to {@link BOULE_CREDENTIAL_ATTEMPTS} times; true once one attempt succeeds. The cause is dropped. */
     private holdWithRetry;
     /**
@@ -3298,6 +3471,11 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * admin token goes to `jobs:org:<slug>:adminToken` and nowhere else.
      */
     private ownJobs;
+    /**
+     * `plan/own-diff.ts`'s `planOwnJobsRoute`: the org's scheduler on `jobs.<domain>`, through the company's own
+     * edge-routed DNS and tunnel ports, dialling the address `coolify:own-jobs` recorded.
+     */
+    private ownJobsRoute;
     /**
      * `plan/own-diff.ts`'s `planOwnFiles`: the org's own files host in the
      * org's own project, trusting the company's issuer `https://auth.<domain>`.
@@ -3350,6 +3528,21 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `livekit:org:<slug>:keys` and the app's env, nowhere else.
      */
     private ownSfu;
+    /**
+     * `plan/entry-jobs.ts`'s `planEntryJobs`: registers one entry as its own project in the platform's jobs
+     * scheduler, holds the credentials the scheduler shows once, then writes `JOBS_SCHEDULER_URL`,
+     * `JOBS_SIGNING_SECRET` and `JOBS_SYNC_KEY` to the entry's env and restarts the app.
+     *
+     * The project's id is recorded as undelivered and persisted before the credentials are held, and cleared
+     * only once both are, so a failure in between never registers a second project: `planEntryJobs` blocks
+     * on it. Credentials already held are never registered again, which is also how a failed env write is
+     * retried. Errors name the project and the refs, never a credential.
+     */
+    private jobsProject;
+    /** `plan/entry-audit.ts`: makes the platform signer if none exists and registers one entry's ledger for sealing. */
+    private auditLedger;
+    /** F12, `plan/entry-repo-key.ts`: makes or removes one entry's deploy key. See `entry-repo-key-apply.ts`. */
+    private githubDeployKey;
     private jobsRegistration;
     /** The blue/green database route (`plan/remote-database.ts`). */
     private remoteDatabaseRoute;
@@ -3367,6 +3560,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * halfway is planned again.
      */
     private publishOikosEntryRecords;
+    /**
+     * The entry names a company has in the platform's `companyincluded.app` zone: its apps' `hostedName`
+     * addresses. Written the same way as {@link publishOikosEntryRecords}. Which company may hold a name is
+     * the host's check (Archon), so the step owns any single-label name under the zone.
+     */
+    private publishAppsEntryRecords;
+    private publishPlatformZoneEntryRecords;
     /**
      * #236: when this tunnel's DNS was last published under a domain that
      * differs from the one `org` now declares, deletes every CNAME in the
@@ -3743,6 +3943,18 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * never leads to a second mint -- `planEntryEdgeKeys` blocks instead.
      */
     private edgeEntryKey;
+    /**
+     * F7 (#928): the company's signed-records registrar key (`plan/keys-registrar.ts`). Mint: a leftover
+     * undelivered key is revoked first; the new key's id is recorded and persisted before it is written to
+     * Boule's env (3 tries, then the error names the id only and the next apply revokes and mints again).
+     * `url` rewrites the address only. Retire revokes and takes both env rows away. Never holds the key.
+     */
+    private keysRegistrar;
+    /**
+     * F3: `plan/entry-edge-key.ts`'s `planEdgeSlug` -- records the org's slug in edge. A slug another company
+     * holds (edge's `409`) is a plain line naming the clash, not the raw provider error.
+     */
+    private edgeSlug;
     /**
      * F7 (#317): `plan/entry-edge-key.ts`'s `planEdgeReservedLabels` --
      * tells the edge service every label this org's own entries already