@wtfalch/foundry 0.1.0 → 0.2.0

package/dist/apply.d.ts

@@ -24,4 +24,18 @@ export interface PlanApply {
      * fresh plan would compute no longer matches this `plan` (#9, #10).
      */
     apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    /**
+     * Deletes every resource foundry created and recorded for `id`, then the
+     * declared org itself.
+     *
+     * Implementations must refuse unless the stored `DeclaredOrg` has
+     * `test: true` (goal line: "only a test org can be deleted") and unless
+     * `confirmedOrgName` matches the org's `displayName`, the same
+     * confirmation `apply` requires for any destructive step (#9) -- required
+     * here unconditionally, since destroying an org is the most destructive
+     * step there is. A failure partway through must stop and leave the
+     * declared org in place with whatever remains recorded, so a retried
+     * `destroy` only tears down what's left.
+     */
+    destroy(id: OrgId, confirmedOrgName: string): Promise<void>;
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, DeclaredOrg, } from './org.js';
-export { validateBuyerIdentity } from './org.js';
+export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } from './org.js';
+export { validateBuyerIdentity, validateHosting, validateOwner } from './org.js';
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
 export { validateSlug, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState } from './state.js';
@@ -9,8 +9,10 @@ export type { PlanApply } from './apply.js';
 export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
 export type { FoundryStoreDb } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, } from './store/schema.js';
-export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, StepAction, PlannedStep, PlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, FoundryPlanApplyOptions, } from './plan/index.js';
-export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan/index.js';
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, StepAction, PlannedStep, PlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
+export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan/index.js';
+export type { CoolifyPort, CloudflarePort, ZitadelPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './plan/index.js';
+export { FoundryStepExecutor, NotBuiltError, MissingBespokeAppRepoError } from './plan/index.js';
 export type { RunnerDb } from './runner/db.js';
 export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
 export { createJobRunner } from './runner/runner.js';

package/dist/index.js

@@ -1,7 +1,8 @@
-export { validateBuyerIdentity } from './org.js';
+export { validateBuyerIdentity, validateHosting, validateOwner } from './org.js';
 export { validateSlug, RESERVED_SLUGS } from './slug.js';
 export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
 export { declaredOrgs, foundryAppliedState, } from './store/schema.js';
-export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan/index.js';
+export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan/index.js';
+export { FoundryStepExecutor, NotBuiltError, MissingBespokeAppRepoError } from './plan/index.js';
 export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
 export { createJobRunner } from './runner/runner.js';

package/dist/migrations/0008_hosting.sql

@@ -0,0 +1,24 @@
+-- @wtfalch/foundry: an org's own hosted app, its database, its Cloudflare
+-- tunnel and its declared ZITADEL issuer apps (#71), declared alongside
+-- everything else in `foundry_declared_orgs` (#0001). Mirrors
+-- `src/store/schema.ts`'s `declaredOrgs` table additions.
+--
+-- HostingConfig (org.ts) is the same `usesDomain`-opts-into-`domain` shape as
+-- mail/chat/calls/issuer/site (#0001's `mail_uses_domain` etc, `0007_site.sql`'s
+-- `site_uses_domain`), plus its own on/off switch: hosting_enabled turns the
+-- org's own app on at all, hosting_database and hosting_tunnel each add a
+-- Postgres database and a Cloudflare tunnel beside it (both require
+-- hosting_enabled -- org.ts's `validateHosting`), and hosting_issuer_apps
+-- carries the org's declared ZITADEL OIDC applications (`IssuerApp[]`).
+--
+-- All four booleans default false and hosting_issuer_apps defaults to an
+-- empty array -- a brand new org has no hosted app, the same "full schema
+-- exists from day one" pattern #0001, #0005 and #0007 established: a new
+-- column with a decided default, never a reshape.
+
+alter table foundry_declared_orgs
+  add column if not exists hosting_enabled     boolean not null default false,
+  add column if not exists hosting_uses_domain boolean not null default false,
+  add column if not exists hosting_database    boolean not null default false,
+  add column if not exists hosting_tunnel      boolean not null default false,
+  add column if not exists hosting_issuer_apps jsonb   not null default '[]';

package/dist/migrations/0009_hosting_git_branch_build_pack.sql

@@ -0,0 +1,14 @@
+-- @wtfalch/foundry: the org's own hosted app's git branch and Coolify build
+-- pack (#71, hosting-wiring campaign), declarable on `HostingConfig` where
+-- `executor.ts`'s `coolifyApp` previously hardcoded `'main'`/`'nixpacks'`.
+-- Mirrors `src/store/schema.ts`'s `declaredOrgs` table additions.
+--
+-- Both default to the values `coolify:app` already provisioned with, so an
+-- org that never mentions them keeps getting exactly what shipped before
+-- this migration -- the same "full schema exists from day one, new column
+-- with a decided default" pattern `0008_hosting.sql` and its predecessors
+-- established.
+
+alter table foundry_declared_orgs
+  add column if not exists hosting_git_branch text not null default 'main',
+  add column if not exists hosting_build_pack text not null default 'nixpacks';

package/dist/migrations/0010_owner.sql

@@ -0,0 +1,13 @@
+-- @wtfalch/foundry: the org's owner, invited by ZITADEL email. Declared
+-- alongside everything else in `foundry_declared_orgs`. Mirrors
+-- `src/store/schema.ts`'s `declaredOrgs` table additions.
+--
+-- OwnerIdentity (org.ts) is flattened into three nullable columns the same
+-- way BuyerIdentity's own contact fields are (`0006_buyer_identity.sql`):
+-- present only when an operator has named an owner, reassembled as one
+-- object only once all three are non-null.
+
+alter table foundry_declared_orgs
+  add column if not exists owner_email        text,
+  add column if not exists owner_given_name   text,
+  add column if not exists owner_family_name  text;

package/dist/migrations/0011_test_org.sql

@@ -0,0 +1,12 @@
+-- @wtfalch/foundry: the test/real flag that gates whether an org can be
+-- destroyed. Declared alongside everything else in
+-- `foundry_declared_orgs`. Mirrors `src/store/schema.ts`'s `declaredOrgs`
+-- table additions.
+--
+-- `is_test` defaults false -- a brand new org is presumed real, matching
+-- every other "full schema exists from day one" column this table has added
+-- (#0001, #0005, #0007, #0008, #0010): a new column with a decided default,
+-- never a reshape.
+
+alter table foundry_declared_orgs
+  add column if not exists is_test boolean not null default false;

package/dist/org.d.ts

@@ -89,6 +89,77 @@ export interface SiteConfig {
     enabled: boolean;
     usesDomain: boolean;
 }
+/**
+ * A ZITADEL OIDC application kind foundry can provision inside an org's
+ * issuer project (#71): `web` (a browser-based confidential/PKCE client),
+ * `native` (a public native-app client) or `api` (an API resource with no
+ * login flow of its own).
+ */
+export type IssuerAppKind = 'web' | 'native' | 'api';
+/**
+ * One ZITADEL OIDC application the org declares (#71), keyed within
+ * `HostingConfig.issuerApps` by its own `name` -- `validateHosting` below
+ * requires every name non-empty and unique in that list. `kind` decides the
+ * ZITADEL `appType` the planner provisions it as (`plan/diff.ts`'s
+ * `planIssuerApps`); changing `kind` for an app that already exists live is
+ * a destructive step there, since ZITADEL has no in-place app-type change.
+ */
+export interface IssuerApp {
+    name: string;
+    kind: IssuerAppKind;
+}
+/**
+ * The Coolify build strategy for the org's own hosted app -- the same union
+ * `@wtfalch/providers`' `CoolifyClient.createGithubAppApplication` accepts as
+ * `build_pack`, reused here rather than redeclared so a value this package
+ * validates is always one Coolify itself accepts.
+ */
+export type HostingBuildPack = 'dockerfile' | 'nixpacks' | 'static' | 'dockercompose';
+/**
+ * The org's own hosted app and what runs beside it (#71, part of #14's
+ * adopted/standard/bespoke map) -- distinct from the cms site (`SiteConfig`
+ * above), which is `@wtfalch/cms` content, not the org's own application
+ * code. `usesDomain` follows the same opt-in-per-service rule as mail, chat,
+ * calls, the issuer and the site (#7 amendment 1): setting `DeclaredOrg.domain`
+ * alone never moves the app onto it or starts managing its Cloudflare zone.
+ *
+ * `database` and `tunnel` are each meaningless without the app itself
+ * running, so `validateHosting` below requires `enabled` before either can
+ * be true.
+ *
+ * `gitBranch` and `buildPack` were fixed values `executor.ts` hardcoded
+ * (`'main'`/`'nixpacks'`) until this campaign's hosting-wiring work made them
+ * declarable; those two strings are their defaults now, kept here so an org
+ * that never mentions them still gets exactly what shipped before.
+ */
+export interface HostingConfig {
+    /** The org's own app runs on Coolify. */
+    enabled: boolean;
+    /** Served on `DeclaredOrg.domain` (and its Cloudflare zone managed) instead of `<slug>.oikos.host` (`../slug.ts`). */
+    usesDomain: boolean;
+    /** A Postgres database beside the app. Requires `enabled`. */
+    database: boolean;
+    /** The app is reached through a Cloudflare tunnel. Requires `enabled`. */
+    tunnel: boolean;
+    /** The branch `coolify:app` builds and deploys from. Default: `'main'`. */
+    gitBranch: string;
+    /** The Coolify build strategy `coolify:app` provisions with. Default: `'nixpacks'`. */
+    buildPack: HostingBuildPack;
+    /** The org's declared ZITADEL OIDC applications (#71). */
+    issuerApps: IssuerApp[];
+}
+/**
+ * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
+ * shape as `validateBuyerIdentity` below.
+ *
+ * - `database` and `tunnel` each require `enabled` -- neither means anything
+ *   without the app itself running.
+ * - `gitBranch` is non-empty and `buildPack` is one of `HostingBuildPack`'s
+ *   four values.
+ * - Every `issuerApps[]` entry has a non-empty `name`, unique within the
+ *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
+ */
+export declare function validateHosting(hosting: HostingConfig): string | null;
 /**
  * Per-org SSO. Decided to exist in #14 ("Also in scope") and its resolved
  * research #3 ("per-org SSO code exists unused"); nothing about its
@@ -196,6 +267,29 @@ export interface BuyerIdentity {
  *   name before its other details are typed).
  */
 export declare function validateBuyerIdentity(buyer: BuyerIdentity): string | null;
+/**
+ * The org's owner: the one person a real org is created for, invited into
+ * its ZITADEL org by email so they can set their own first credential (a
+ * passkey) without a password ever passing through foundry. `null` until an
+ * operator names one -- an org can exist declared before its owner is known.
+ *
+ * `apply`'s `zitadel:owner` step (`plan/diff.ts`'s `planOwner`) calls
+ * `ZitadelClient.inviteOrgOwner(zitadelOrgId, owner)` once the org's ZITADEL
+ * org exists, then never touches this again -- a re-run is idempotent on the
+ * recorded invited user id, not on this declared value, so editing `owner`
+ * after the invite has gone out does not send a second one.
+ */
+export interface OwnerIdentity {
+    email: string;
+    givenName: string;
+    familyName: string;
+}
+/**
+ * `null` when `owner` is valid; otherwise the reason it is not, same shape as
+ * {@link validateBuyerIdentity} and `../slug.ts`'s `validateSlug`. `owner:
+ * null` (no owner named yet) is always valid.
+ */
+export declare function validateOwner(owner: OwnerIdentity | null): string | null;
 /**
  * The form an app foundry does not own takes. Decided in #7's `#15`
  * refinement comment:
@@ -255,6 +349,8 @@ export interface DeclaredOrg {
     issuer: IssuerConfig;
     /** `enabled: false` by default -- a brand new org has no cms site. */
     site: SiteConfig;
+    /** `enabled: false`, `issuerApps: []` by default -- a brand new org has no hosted app (#71). */
+    hosting: HostingConfig;
     sso: SsoConfig;
     guests: GuestsConfig;
     solo: SoloConfig;
@@ -273,4 +369,15 @@ export interface DeclaredOrg {
     bespokeAppRepo: string | null;
     /** `null` when the org has none. */
     adoptedApp: AdoptedApp | null;
+    /** The org's owner, invited by ZITADEL email. `null` until an operator names one. See {@link OwnerIdentity}. */
+    owner: OwnerIdentity | null;
+    /**
+     * Marks this org as a test org rather than a real customer's. Purely
+     * declarative -- it changes nothing about what `apply` provisions -- but it
+     * is the one gate `FoundryPlanApply.destroy` checks: only a test org
+     * (`test: true`) can be destroyed, so deleting every resource foundry made
+     * for an org, then the org itself, can never reach a real customer's org by
+     * mistake.
+     */
+    test: boolean;
 }

package/dist/org.js

@@ -1,3 +1,49 @@
+const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
+const HOSTING_BUILD_PACKS = new Set([
+    'dockerfile',
+    'nixpacks',
+    'static',
+    'dockercompose',
+]);
+/**
+ * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
+ * shape as `validateBuyerIdentity` below.
+ *
+ * - `database` and `tunnel` each require `enabled` -- neither means anything
+ *   without the app itself running.
+ * - `gitBranch` is non-empty and `buildPack` is one of `HostingBuildPack`'s
+ *   four values.
+ * - Every `issuerApps[]` entry has a non-empty `name`, unique within the
+ *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
+ */
+export function validateHosting(hosting) {
+    if (hosting.database && !hosting.enabled) {
+        return 'hosting.database requires hosting.enabled';
+    }
+    if (hosting.tunnel && !hosting.enabled) {
+        return 'hosting.tunnel requires hosting.enabled';
+    }
+    if (!hosting.gitBranch) {
+        return 'hosting.gitBranch must be non-empty';
+    }
+    if (!HOSTING_BUILD_PACKS.has(hosting.buildPack)) {
+        return `hosting.buildPack has an unknown value '${hosting.buildPack}'`;
+    }
+    const seenNames = new Set();
+    for (const app of hosting.issuerApps) {
+        if (!app.name) {
+            return 'every issuerApps entry needs a non-empty name';
+        }
+        if (seenNames.has(app.name)) {
+            return `issuerApps name '${app.name}' is not unique`;
+        }
+        seenNames.add(app.name);
+        if (!ISSUER_APP_KINDS.has(app.kind)) {
+            return `issuerApps '${app.name}' has an unknown kind '${app.kind}'`;
+        }
+    }
+    return null;
+}
 const ORG_NUMBER_PATTERN = /^\d{9}$/;
 /**
  * `null` when `buyer` is valid; otherwise the reason it is not, for a caller
@@ -27,3 +73,22 @@ export function validateBuyerIdentity(buyer) {
     }
     return null;
 }
+/** A deliberately loose email shape check -- foundry never sends mail itself, ZITADEL does; this only catches an obviously malformed address before it reaches the invite call. */
+const OWNER_EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * `null` when `owner` is valid; otherwise the reason it is not, same shape as
+ * {@link validateBuyerIdentity} and `../slug.ts`'s `validateSlug`. `owner:
+ * null` (no owner named yet) is always valid.
+ */
+export function validateOwner(owner) {
+    if (owner === null)
+        return null;
+    if (!OWNER_EMAIL_PATTERN.test(owner.email)) {
+        return `owner email '${owner.email}' is not a valid email address`;
+    }
+    if (!owner.givenName.trim())
+        return 'owner.givenName must not be empty';
+    if (!owner.familyName.trim())
+        return 'owner.familyName must not be empty';
+    return null;
+}

package/dist/plan/diff.d.ts

@@ -41,12 +41,27 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * exist for every org — the issuer, mail, and chat (always provisioned at
  * level 1, per #7 "Chat", regardless of `usesDomain`). #27 adds two more,
  * in the same singleton shape: storage's spend limit on Files and AI's
- * budget. This task adds a sixth, in the same shape: the org's cms site
- * (`org.ts`'s `SiteConfig`). Everything else in `live` that none of these
- * six claim is unmanaged. The full field-by-field provisioning surface (SSO,
- * guests, calls, adopted/bespoke apps, the actual
+ * budget. T10 adds a sixth, in the same shape: the org's cms site
+ * (`org.ts`'s `SiteConfig`). #71 adds four more singleton resources, in the
+ * same shape — the org's own hosted app, its database, its Cloudflare
+ * tunnel and its Cloudflare zone (`org.ts`'s `HostingConfig`) — plus one
+ * list-shaped resource: `planIssuerApps` below emits one step per declared
+ * `hosting.issuerApps[]` entry rather than a single singleton, since an org
+ * can declare more than one ZITADEL app. #80 adds two more singletons,
+ * modeled on {@link planIssuer}: `planFilesOrganisation` and
+ * `planAiOrganisation`, each planned before its own system's limit step
+ * ({@link planStorage}, {@link planAiBudget}) so an org has somewhere for a
+ * limit to land, and AI use is switched on, before either limit is ever set.
+ * `planOwner` below adds one more singleton, in a different shape from the
+ * rest: the org's owner, invited by ZITADEL email, idempotent on the
+ * *recorded* resource id (`recordedIds`, sourced from
+ * `AppliedState.serviceIds`) rather than a live resource, since a human user
+ * is never something `live` can contain. Everything else in `live` that none
+ * of these twelve singletons and however many declared issuer apps claim is
+ * unmanaged. The full field-by-field provisioning surface (SSO, guests,
+ * calls, adopted/bespoke apps, the actual
  * Zitadel/Coolify/Cloudflare/Files/AI/cms shapes) is #20's "provision
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[]): PlanDetail;
+export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>): PlanDetail;