@wtfalch/foundry 0.1.0 → 0.2.0

package/dist/plan/executor.d.ts

@@ -0,0 +1,474 @@
+import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
+import type { StepAction } from './diff.js';
+import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
+/**
+ * The real {@link StepExecutor} (#20 "provision Company Factory end to
+ * end"): makes each {@link StepAction} `diff.ts` plans true against a real
+ * Coolify, Cloudflare and ZITADEL, plus per-org organisations, spend limits
+ * and (for AI) offers on Files and AI (#80). Scope and design are exactly
+ * what `.claude/decisions-2026-09-24-executor.md`'s "Executor decisions"
+ * section settled, referenced by name at each dispatch branch below.
+ *
+ * Built entirely from narrow ports (interfaces), never a concrete
+ * `@wtfalch/providers` client: this package holds no credential and never
+ * will (executor decisions: "the executor is constructed with narrow ports
+ * ... a host [archon] supplies real clients. How the host gets provider
+ * tokens from the keys Worker is the host's job, not this campaign's").
+ * Every port method here is named and shaped to match a real method on
+ * `@wtfalch/providers`' `CoolifyClient`/`CloudflareClient`/`ZitadelClient`
+ * (checked against `providers` `origin/main`, 2026-09-24), or on
+ * `@wtfalch/files`'/`@wtfalch/ai`'s own SDK clients (#80, checked against
+ * each repo's own `main`, 2026-09-25), so a real client satisfies the port
+ * structurally, with no adapter needed — see each port's own doc comment for
+ * the one real method it does not yet have.
+ */
+/**
+ * The Coolify calls this executor makes, shaped to match
+ * `@wtfalch/providers/coolify`'s `CoolifyClient` method-for-method — a real
+ * `CoolifyClient` instance satisfies this port with no adapter.
+ *
+ * There is no single `findOrCreateProject`/stop/start on `CoolifyClient`
+ * today (unlike ZITADEL's `findOrCreateOrg`/`findOrCreateProject`, which
+ * already exist): `findProjectByName` + `createProject` compose into
+ * "find or create" inside this executor instead of the port, and `raw` —
+ * `CoolifyClient`'s own documented escape hatch for "use — or add — a typed
+ * method instead" — carries the stop/start calls Coolify's REST API has
+ * (`POST /applications/{uuid}/stop`, `POST /databases/{uuid}/stop`) that
+ * `CoolifyClient` has not wrapped yet. Logged as a Decision in this
+ * campaign's report rather than inventing port methods (`findOrCreateProject`,
+ * `stop`, `start`) no real client could structurally satisfy.
+ */
+export interface CoolifyPort {
+    findProjectByName(name: string): Promise<{
+        uuid: string;
+        name: string;
+    } | null>;
+    createProject(name: string, description?: string): Promise<{
+        uuid: string;
+    }>;
+    findOrCreateEnvironment(projectUuid: string, name: string): Promise<{
+        environment: {
+            id: number;
+            uuid: string;
+            name: string;
+        };
+        created: boolean;
+    }>;
+    listServers(): Promise<Array<{
+        uuid: string;
+        is_usable: boolean;
+        is_reachable: boolean;
+    }>>;
+    requireGithubApp(preferredUuid?: string): Promise<{
+        uuid: string;
+        name: string;
+    }>;
+    findApplicationByName(name: string, scope?: {
+        environmentIds: number[];
+    }): Promise<{
+        uuid: string;
+    } | null>;
+    createGithubAppApplication(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        github_app_uuid: string;
+        git_repository: string;
+        git_branch: string;
+        build_pack: HostingBuildPack;
+        name?: string;
+        domains?: string;
+    }): Promise<{
+        uuid: string;
+    }>;
+    createPostgresDatabase(input: {
+        project_uuid: string;
+        server_uuid: string;
+        environment_name: string;
+        environment_uuid: string;
+        name: string;
+        postgres_db: string;
+        postgres_user: string;
+    }): Promise<{
+        uuid: string;
+        internal_db_url: string;
+    }>;
+    /**
+     * Coolify's own record of a database, re-read here (rather than trusted
+     * from `createPostgresDatabase`'s return value) so the app's env is wired
+     * from the database's live state whether this run just created it or found
+     * it already there (`coolifyApp`/`coolifyDatabase` below, hosting-wiring
+     * campaign). `internal_db_url` is `postgres://user:password@host/db` — a
+     * live credential, present in the raw Coolify API response and reachable
+     * only from inside the Coolify Docker network (`@wtfalch/providers`'
+     * `CoolifyClient.createPostgresDatabase` doc comment).
+     */
+    getDatabase(uuid: string): Promise<{
+        uuid: string;
+        internal_db_url?: string;
+    }>;
+    /**
+     * Every database Coolify holds. `coolifyDatabase` finds its own by name and
+     * environment, so a crash between create and persist does not make a second
+     * one on the next apply. Only `uuid`, `name` and `environment_id` are read;
+     * the raw response also carries `internal_db_url`, which is never used here.
+     */
+    listDatabases(): Promise<Array<{
+        uuid: string;
+        name: string;
+        environment_id?: number;
+    }>>;
+    /**
+     * Upsert environment variables on an application in one call — used here to
+     * push the database's `internal_db_url` in as the app's `DATABASE_URL`
+     * (hosting-wiring campaign). The value is a live credential: it must reach
+     * this call and nothing else — never a step's return value, `serviceIds`
+     * (hence the store), an audit record, a log or a thrown error. See
+     * `coolifyApp`'s `pushDatabaseUrl`.
+     */
+    bulkUpsertEnvs(applicationUuid: string, envs: Array<{
+        key: string;
+        value: string;
+        buildTime?: boolean;
+        literal?: boolean;
+        multiline?: boolean;
+    }>): Promise<unknown>;
+    /** Escape hatch (`CoolifyClient.raw`) — used for stop/start, which have no typed method yet. */
+    raw(method: string, path: string, body?: unknown): Promise<unknown>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's own app. */
+    deleteApplication(uuid: string): Promise<unknown>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's own database. */
+    deleteDatabase(uuid: string): Promise<unknown>;
+}
+/**
+ * The Cloudflare calls this executor makes, shaped to match
+ * `@wtfalch/providers/cloudflare`'s `CloudflareClient` method-for-method.
+ */
+export interface CloudflarePort {
+    findZoneByApex(domain: string): Promise<{
+        id: string;
+        name: string;
+    } | undefined>;
+    createZone(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    findTunnelByName(name: string): Promise<{
+        id: string;
+        name: string;
+    } | undefined>;
+    createTunnel(name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+    putTunnelConfig(tunnelId: string, config: unknown): Promise<unknown>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's own Cloudflare tunnel. */
+    deleteTunnel(tunnelId: string): Promise<void>;
+    /**
+     * `FoundryPlanApply.destroy`'s teardown of any DNS record foundry created
+     * for the org. Nothing in this executor creates or records one yet (Finding,
+     * this campaign's report: no `cloudflare:dns` resource kind exists in
+     * `diff.ts`/`executor.ts` today), so `destroy` has no dispatch target for
+     * it either -- this port method exists ready for whichever step starts
+     * creating one.
+     */
+    deleteDnsRecord(zoneId: string, recordId: string): Promise<void>;
+}
+/**
+ * The ZITADEL calls this executor makes. `findOrCreateOrg`/`findOrCreateProject`
+ * already exist on `@wtfalch/providers/zitadel`'s `ZitadelClient` (returning
+ * `{org|project, created}`, not the bare `{id}` this campaign's brief
+ * sketched — matched to the real shape here, logged as a Decision).
+ * `createOidcApp`/`createApiApp`/`deleteApp` do not exist yet — "being added
+ * to providers in parallel" (task brief) — so this port states the shapes
+ * they need to land with; a `ZitadelClient` that gains exactly these three
+ * methods satisfies this port with no adapter.
+ */
+export interface ZitadelPort {
+    findOrCreateOrg(name: string): Promise<{
+        org: {
+            id: string;
+            name: string;
+        };
+        created: boolean;
+    }>;
+    findOrCreateProject(orgId: string, name: string): Promise<{
+        project: {
+            id: string;
+            name: string;
+        };
+        created: boolean;
+    }>;
+    createOidcApp(orgId: string, projectId: string, input: {
+        name: string;
+        appType: 'web' | 'native';
+        redirectUris: string[];
+        postLogoutRedirectUris: string[];
+    }): Promise<{
+        appId: string;
+        clientId: string;
+    }>;
+    /**
+     * Returns `clientSecret` alongside `appId`/`clientId` — ZITADEL mints it
+     * once, on creation, and never shows it again (`providers`' `ZitadelClient.
+     * createApiApp`, commit 1d0fec2). The executor hands it straight to
+     * {@link FoundryStepExecutorPorts.deliverSecret} and never returns, stores
+     * or logs it itself (see that port's doc comment).
+     */
+    createApiApp(orgId: string, projectId: string, input: {
+        name: string;
+    }): Promise<{
+        appId: string;
+        clientId: string;
+        clientSecret: string;
+    }>;
+    deleteApp(orgId: string, projectId: string, appId: string): Promise<void>;
+    /**
+     * The org-owner flow (goal line): find-or-create the human user by email in
+     * the org, then have ZITADEL email them an invite to set up a passkey.
+     * Idempotent on the user; the invite itself is not (a re-run always sends a
+     * fresh code) — `plan/diff.ts`'s `planOwner` is what makes a *re-run of
+     * foundry's own apply* idempotent, by planning nothing once the returned
+     * `userId` is recorded. Returns only ids, matching `createApiApp`'s own
+     * rule for anything invite/credential-shaped: the email itself is a
+     * parameter here, never part of the return value.
+     */
+    inviteOrgOwner(orgId: string, owner: {
+        givenName: string;
+        familyName: string;
+        email: string;
+    }): Promise<{
+        userId: string;
+        created: boolean;
+    }>;
+    /** Lets anyone sign up to the org (plan gap A9). Idempotent. */
+    allowSelfRegistration(orgId: string): Promise<{
+        changed: boolean;
+    }>;
+    /** Grants another ZITADEL org access to a project (plan gap A9). Idempotent. */
+    findOrCreateProjectGrant(orgId: string, projectId: string, grantedOrgId: string): Promise<{
+        created: boolean;
+    }>;
+    /** `FoundryPlanApply.destroy`'s teardown of the org's ZITADEL project, once every app inside it is gone. */
+    deleteProject(orgId: string, projectId: string): Promise<void>;
+    /** `FoundryPlanApply.destroy`'s last step: removes the whole ZITADEL org and everything foundry made inside it. */
+    deleteOrg(orgId: string): Promise<void>;
+}
+/**
+ * One org's spend limit on Files, matching `files/packages/sdk/src/client.ts:154-166`'s
+ * `setQuota`/`setBudget` (the caller's own organisation, resolved from its
+ * signed request — no organisation id parameter, hence a factory per org
+ * rather than one flat port).
+ */
+export interface FilesOrgLimits {
+    setQuota(limitBytes: string | null): Promise<unknown>;
+    setBudget(limitMicros: string | null): Promise<unknown>;
+}
+/**
+ * One org's budget on AI, matching `ai/packages/sdk/src/client.ts:94-101`'s
+ * `updateBudget` (`UpdateBudget` from `ai/packages/sdk/src/types.ts:134-137`).
+ */
+export interface AiOrgLimits {
+    updateBudget(input: {
+        keyId: string | null;
+        limitMicros: string;
+    }): Promise<unknown>;
+}
+/**
+ * Provisions one org's organisation on Files (#80), matching
+ * `files/packages/sdk/src/client.ts:136-145`'s
+ * `createFilesManagementClient().provisionOrganisation`
+ * (`ProvisionOrganisationInput`/`ProvisionOrganisationResult`,
+ * `files/packages/sdk/src/types.ts:146-156`). Flat, not a factory, like
+ * {@link ZitadelPort}: `organisationId` is an explicit call argument here,
+ * unlike {@link FilesOrgLimits}'s tenant-scoped calls, which resolve the
+ * caller's own organisation from its signed request instead.
+ *
+ * Finding (this campaign's report): unlike {@link AiOrganisationPort}'s bearer
+ * credential, `createFilesManagementClient`'s whole transport is "a signed
+ * human proof or an issued management key" (`files/packages/sdk/src/
+ * client.ts:117-119`) — concretely an Ed25519-signed `x-wtfalch-management`
+ * request (`files/apps/host/src/lib/authz/service-assertion.ts`'s
+ * `signManagementRequest`/`AssertionTrust`). A host can construct this without
+ * any human session: it only needs the Ed25519 private key (`SigningIdentity`)
+ * an operator's `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` pins — the same
+ * signer {@link FilesOrgLimits} needs for `setQuota`/`setBudget`, since the
+ * `organisation` field inside the signed claim selects the org per call, so
+ * one shared keypair signs for every org rather than needing a secret per
+ * org.
+ */
+export interface FilesOrganisationPort {
+    provisionOrganisation(input: {
+        organisationId: string;
+        ceilingBytes: string | null;
+        ceilingMicros: string | null;
+        shareHost?: string | null;
+    }): Promise<{
+        organisationId: string;
+        ceilingBytes: string | null;
+        ceilingMicros: string | null;
+        usedBytes: string;
+        reservedBytes: string;
+        spentMicros: string;
+        suspended: boolean;
+        shareHost: string | null;
+        created: boolean;
+    }>;
+}
+/**
+ * Provisions one org's organisation on AI and switches its AI use on (#80),
+ * matching `ai/packages/sdk/src/client.ts:98-108`'s `provisionOrganisation`/
+ * `setOrganisationOffers` (`ProvisionOrganisation`/`ProvisionOrganisationResult`,
+ * `SetOrganisationOffers`/`OrganisationOffersView`,
+ * `ai/packages/sdk/src/types.ts:121-143`). Flat, not a factory, for the same
+ * reason as {@link FilesOrganisationPort}.
+ *
+ * Finding (this campaign's report): AI's machine credential is a plain bearer
+ * key — archon's own `AI_MANAGEMENT_KEY`, minted by
+ * `ai/apps/host/scripts/authz/bootstrap-archon.ts`'s `keys:issue-archon` with
+ * `ARCHON_AI_PERMISSIONS` (`ai.organisations:provision`,
+ * `ai.organisations:offer`, `ai.budgets:update`, among others) copied onto
+ * it — used directly with `createAiClient`, unlike Files' signed-assertion
+ * transport above.
+ */
+export interface AiOrganisationPort {
+    provisionOrganisation(input: {
+        organisationId: string;
+        limitMicros: string | null;
+    }): Promise<{
+        organisationId: string;
+        limitMicros: string | null;
+        created: boolean;
+    }>;
+    setOrganisationOffers(organisationId: string, offers: string[]): Promise<{
+        organisationId: string;
+        offers: string[];
+    }>;
+}
+export interface FoundryStepExecutorPorts {
+    coolify: CoolifyPort;
+    cloudflare: CloudflarePort;
+    zitadel: ZitadelPort;
+    /** A factory, not a flat client: Files/AI are org-scoped credentials the host resolves per org. */
+    filesLimitsFor: (orgId: OrgId) => FilesOrgLimits;
+    aiLimitsFor: (orgId: OrgId) => AiOrgLimits;
+    /** Flat, not a factory: `organisationId` is an explicit argument on both ports (see each port's own doc comment). */
+    filesOrganisation: FilesOrganisationPort;
+    aiOrganisation: AiOrganisationPort;
+    /**
+     * Hands a just-minted, one-time secret (today: an API app's
+     * `clientSecret`) to the host, immediately after the provider returns it
+     * and before the step that created it returns. This package "holds no
+     * credential and never will" (this file's own top doc comment), so a
+     * secret is never a step's return value, never goes into `serviceIds` (the
+     * store, hence the DB), and is never logged or interpolated into a thrown
+     * error -- this is its one way out of the executor. `ref` names what the
+     * secret belongs to (e.g. `zitadel:app:<org.slug>:<key>`); routing it
+     * anywhere durable (a keys Worker, a secret store) is the host's job, the
+     * same division `executor.ts`'s top comment draws for provider tokens
+     * themselves.
+     */
+    deliverSecret(ref: string, secret: string): Promise<void>;
+}
+/**
+ * Thrown by name for a step this executor deliberately does not implement:
+ * mail and chat (no admin API exists yet in either service) and the cms
+ * site (same), plus moving the issuer onto or off the org's domain (built,
+ * but not in v1 — domain verification and passkey invalidation need their
+ * own design). Never carries a token, secret or key (task brief: "errors
+ * carry the step and the provider's status only").
+ */
+export declare class NotBuiltError extends Error {
+    constructor(step: string, detail: string);
+}
+/** `coolify:app` needs source code to build from; `DeclaredOrg.bespokeAppRepo` is the only source this executor knows (#71, #20). */
+export declare class MissingBespokeAppRepoError extends Error {
+    constructor(slug: string);
+}
+export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer {
+    private readonly ports;
+    constructor(ports: FoundryStepExecutorPorts);
+    execute(action: StepAction, context: StepExecutionContext): Promise<{
+        resourceId?: string;
+    } | undefined>;
+    private zitadelIssuer;
+    /**
+     * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
+     * org by email. Never logs, returns or throws the email itself -- only the
+     * invited user id, handed back as `resourceId` so `runSteps` records it
+     * under `zitadel:owner:<orgId>`, which is exactly what makes the next
+     * `plan()` call idempotent (`planOwner` plans nothing once that key is
+     * recorded).
+     */
+    private zitadelOwner;
+    /**
+     * `plan/diff.ts`'s `planCustomers` (plan gap A9): the org's customers sign
+     * in through a second ZITADEL org, `<slug> customers`, with
+     * self-registration on and a grant to the org's app project. Staff stay in
+     * the org's own invite-only ZITADEL org. The space keeps the name apart from
+     * every issuer org, which is named by a slug and a slug has no spaces. Every call here is idempotent, so
+     * a re-run after a crash finishes the job.
+     */
+    private zitadelCustomers;
+    private zitadelApp;
+    private ensureZitadelProject;
+    private ensureCoolifyProject;
+    private resolveServer;
+    private coolifyApp;
+    private coolifyDatabase;
+    /**
+     * Pushes the database's connection string into the app's environment as
+     * `DATABASE_URL` -- never also as `DATABASE_URL_OWNER` (Decision, this
+     * campaign's report). Archon's own boot script
+     * (`archon/scripts/migrate-and-start.sh`) treats a bare `DATABASE_URL` with
+     * no `DATABASE_URL_OWNER` as "before the split": it migrates and serves as
+     * the one role it has, which is exactly what a database Coolify just
+     * created (one superuser role, no separate runtime role yet) is. Setting
+     * both to the *same* superuser URL would instead take the split branch --
+     * `db-role-guard.sh` then refuses to boot, since `DATABASE_URL_OWNER` being
+     * set means it expects `DATABASE_URL` to connect as a distinct,
+     * non-superuser runtime role (`<database>_rt`), which nothing here creates.
+     * Minting that role's own password and URL is a provisioning step of its
+     * own, not built here (Finding, this campaign's report).
+     *
+     * The connection string is a live credential
+     * (`postgres://user:password@host/db`): it is read from
+     * `CoolifyPort.getDatabase` and handed straight to `bulkUpsertEnvs` and
+     * nowhere else in this class -- never returned, never recorded in
+     * `serviceIds` (hence never in the store or an audit record), never logged,
+     * never interpolated into a thrown error.
+     */
+    private pushDatabaseUrl;
+    private cloudflareTunnel;
+    private cloudflareZone;
+    /**
+     * #80: provisions the org's own organisation on Files, before
+     * {@link filesStorage} can set its spend limit. `provisionOrganisation` is
+     * safely repeatable on its own (`FilesOrganisationPort`'s doc comment), so
+     * this is called every time regardless of whether it already ran --
+     * idempotent by find-or-create, not by checking `recordedIds` first.
+     */
+    private filesOrganisation;
+    private filesStorage;
+    /**
+     * #80: provisions the org's own organisation on AI and switches its AI use
+     * on, before {@link aiBudget} can set its own spend limit. Both
+     * `provisionOrganisation` and `setOrganisationOffers` are safely repeatable
+     * on their own (`AiOrganisationPort`'s doc comment), so both are called
+     * every time regardless of whether they already ran.
+     */
+    private aiOrganisation;
+    private aiBudget;
+    /**
+     * {@link StepDestroyer.destroy}: deletes the one resource
+     * `FoundryPlanApply.destroy` names. A provider 404 (already gone) counts as
+     * deleted -- `isNotFoundError` below -- since a destroy retried after a
+     * partial failure must find an already-deleted resource a no-op, not a new
+     * error.
+     */
+    destroy(target: DestroyTarget, context: {
+        readonly org: DeclaredOrg;
+        readonly recordedIds: Readonly<Record<string, string>>;
+    }): Promise<void>;
+}