@wtfalch/foundry 0.1.0

package/dist/plan/diff.d.ts

@@ -0,0 +1,52 @@
+import type { DeclaredOrg, OrgId } from '../org.js';
+import type { Plan, PlanStep, UnmanagedItem } from '../plan.js';
+import type { LiveResource } from './live.js';
+/**
+ * What a {@link StepExecutor} (see `plan-apply.ts`) needs to actually make a
+ * step true, alongside the public {@link PlanStep} an operator reads.
+ *
+ * `PlanStep` (in `../plan.ts`) is deliberately thin — a description plus two
+ * gate flags — because that type is #19's shared contract with whoever reads
+ * a `Plan` back (the operator page, #17's runner). It carries nothing an
+ * executor could act on. Rather than widen that shared type for one
+ * consumer, `computePlanDetail` below produces a `PlannedStep` that pairs
+ * the public step with this private action, and `FoundryPlanApply` (in
+ * `plan-apply.ts`) is the only thing that reads the `action` half.
+ */
+export interface StepAction {
+    system: LiveResource['system'];
+    kind: string;
+    /** The resource's key in that system — see {@link LiveResource}. */
+    key: string;
+    desired: Record<string, unknown>;
+}
+export interface PlannedStep {
+    step: PlanStep;
+    action: StepAction;
+}
+export interface PlanDetail {
+    orgId: OrgId;
+    plannedSteps: PlannedStep[];
+    unmanaged: UnmanagedItem[];
+}
+/** The `Plan` (#19's public contract) a `PlanDetail` carries. */
+export declare function toPlan(detail: PlanDetail): Plan;
+/**
+ * The diff engine: #19's "a plan reads live state from Zitadel, Coolify and
+ * Cloudflare and diffs it against the declared org", built on #10's rule
+ * that anything the declared org does not name is reported unmanaged and
+ * never turned into a step.
+ *
+ * Scope for #19: the three per-org singleton resources #7 and #8 decided
+ * 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
+ * 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;

package/dist/plan/diff.js

@@ -0,0 +1,302 @@
+/** The `Plan` (#19's public contract) a `PlanDetail` carries. */
+export function toPlan(detail) {
+    return {
+        orgId: detail.orgId,
+        steps: detail.plannedSteps.map((p) => p.step),
+        unmanaged: detail.unmanaged,
+    };
+}
+function resourceKey(system, kind, key) {
+    return `${system}:${kind}:${key}`;
+}
+/**
+ * The diff engine: #19's "a plan reads live state from Zitadel, Coolify and
+ * Cloudflare and diffs it against the declared org", built on #10's rule
+ * that anything the declared org does not name is reported unmanaged and
+ * never turned into a step.
+ *
+ * Scope for #19: the three per-org singleton resources #7 and #8 decided
+ * 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
+ * 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 function computePlanDetail(org, live) {
+    const byKey = new Map(live.map((r) => [resourceKey(r.system, r.kind, r.key), r]));
+    const claimed = new Set();
+    const plannedSteps = [];
+    const issuer = planIssuer(org, byKey, claimed);
+    if (issuer)
+        plannedSteps.push(issuer);
+    const mail = planMail(org, byKey, claimed);
+    if (mail)
+        plannedSteps.push(mail);
+    const chat = planChat(org, byKey, claimed);
+    if (chat)
+        plannedSteps.push(chat);
+    const storage = planStorage(org, byKey, claimed);
+    if (storage)
+        plannedSteps.push(storage);
+    const aiBudget = planAiBudget(org, byKey, claimed);
+    if (aiBudget)
+        plannedSteps.push(aiBudget);
+    const site = planSite(org, byKey, claimed);
+    if (site)
+        plannedSteps.push(site);
+    // #10 (resolved): "foundry manages only what the declared org names";
+    // anything left unclaimed is listed, never proposed for deletion.
+    const unmanaged = live
+        .filter((r) => !claimed.has(resourceKey(r.system, r.kind, r.key)))
+        .map((r) => ({
+        description: `${r.system} ${r.kind} "${r.key}" is live but not named by the declared org`,
+    }));
+    return { orgId: org.id, plannedSteps, unmanaged };
+}
+function planIssuer(org, byKey, claimed) {
+    const key = resourceKey('zitadel', 'issuer', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const desiredUsesDomain = org.issuer.usesDomain;
+    const liveUsesDomain = live ? Boolean(live.config.usesDomain) : false;
+    if (liveUsesDomain === desiredUsesDomain)
+        return null;
+    const domain = org.domain ?? 'the org domain';
+    return {
+        action: {
+            system: 'zitadel',
+            kind: 'issuer',
+            key: org.id,
+            desired: { usesDomain: desiredUsesDomain },
+        },
+        step: {
+            description: desiredUsesDomain
+                ? `move the issuer onto ${domain}, invalidating every passkey in the org`
+                : `move the issuer off ${domain} back onto the shared issuer, invalidating every passkey in the org`,
+            // Any issuer move invalidates every passkey in the org (#7 corrections
+            // 2, #19 "Done when"). It never moves data between systems, so it is
+            // never `migrates`.
+            destroys: true,
+            migrates: false,
+        },
+    };
+}
+function planMail(org, byKey, claimed) {
+    const key = resourceKey('coolify', 'mail', org.id);
+    const live = byKey.get(key);
+    // `off` means mail is not foundry's concern here (org.ts's MailMode doc);
+    // a live resource under this key, if any, is left unmanaged rather than
+    // claimed, since the declared org names nothing for foundry to reconcile
+    // it against. Checked before claiming, or an org that turned mail off
+    // after having it would silently hide its own leftover mail resource from
+    // the unmanaged list.
+    if (org.mail.mode === 'off')
+        return null;
+    if (live)
+        claimed.add(key);
+    const desired = { mode: org.mail.mode, usesDomain: org.mail.usesDomain };
+    if (!live) {
+        return {
+            action: { system: 'coolify', kind: 'mail', key: org.id, desired },
+            step: {
+                description: `provision mail (${org.mail.mode}) for ${org.slug}`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    }
+    const liveMode = live.config.mode;
+    const liveUsesDomain = Boolean(live.config.usesDomain);
+    if (liveMode === desired.mode && liveUsesDomain === desired.usesDomain)
+        return null;
+    if (liveUsesDomain && !desired.usesDomain) {
+        // #7 corrections 1: parked, not deleted — mailboxes and messages stay —
+        // but still disruptive enough to gate like a destructive step.
+        return {
+            action: { system: 'coolify', kind: 'mail', key: org.id, desired },
+            step: {
+                description: `park ${org.slug}'s mail domain (stops receiving; mailboxes and messages are retained, not deleted — #7 corrections 1)`,
+                destroys: true,
+                migrates: false,
+            },
+        };
+    }
+    // A mode transition (#7 "Transitions") or turning a domain on is a
+    // one-time copy, never a deletion.
+    return {
+        action: { system: 'coolify', kind: 'mail', key: org.id, desired },
+        step: {
+            description: `move ${org.slug}'s mail from ${String(liveMode)} to ${desired.mode}`,
+            destroys: false,
+            migrates: true,
+        },
+    };
+}
+function planChat(org, byKey, claimed) {
+    const key = resourceKey('coolify', 'chat', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const desiredUsesDomain = org.chat.usesDomain;
+    if (!live) {
+        // Chat is provisioned at level 1 on a wtfalch `server_name` regardless
+        // of `usesDomain` (#7 "Chat").
+        return {
+            action: {
+                system: 'coolify',
+                kind: 'chat',
+                key: org.id,
+                desired: { usesDomain: desiredUsesDomain },
+            },
+            step: {
+                description: `provision chat for ${org.slug} on a wtfalch server_name`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    }
+    const liveUsesDomain = Boolean(live.config.usesDomain);
+    if (liveUsesDomain === desiredUsesDomain)
+        return null;
+    const domain = org.domain ?? 'its domain';
+    if (!liveUsesDomain && desiredUsesDomain) {
+        return {
+            action: { system: 'coolify', kind: 'chat', key: org.id, desired: { usesDomain: true } },
+            step: {
+                description: `re-key ${org.slug}'s chat onto ${domain}, copying rooms and messages so history reads continuous`,
+                destroys: true,
+                migrates: true,
+            },
+        };
+    }
+    // The reverse (usesDomain true -> false): legal in the schema, but the
+    // reverse merge is not built yet (#7 amendment 3). Still surfaced here for
+    // visibility; whoever wires a real StepExecutor (#20) must fail loudly on
+    // it rather than run it, exactly as #7 amendment 3 requires.
+    return {
+        action: { system: 'coolify', kind: 'chat', key: org.id, desired: { usesDomain: false } },
+        step: {
+            description: `reverse ${org.slug}'s chat re-key back onto its original server_name — not yet built (#7 amendment 3)`,
+            destroys: true,
+            migrates: true,
+        },
+    };
+}
+/**
+ * #27: the org's own spend limit on Files, a per-org singleton resource in
+ * the same shape as issuer/mail/chat above. Setting a limit is a config
+ * write, never destructive or migrating (#27 "Notes": "safe, idempotent and
+ * reversible"). A missing live resource reads as uncapped (`null`), the same
+ * value a freshly-declared org's `storage` starts at, so a brand new org with
+ * no limits declared produces no step.
+ */
+function planStorage(org, byKey, claimed) {
+    const key = resourceKey('files', 'storage', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const desired = { limitBytes: org.storage.limitBytes, limitMicros: org.storage.limitMicros };
+    const liveLimitBytes = live ? (live.config.limitBytes ?? null) : null;
+    const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
+    if (liveLimitBytes === desired.limitBytes && liveLimitMicros === desired.limitMicros)
+        return null;
+    return {
+        action: { system: 'files', kind: 'storage', key: org.id, desired },
+        step: {
+            description: `set ${org.slug}'s storage limit to ${desired.limitBytes ?? 'uncapped'} bytes / ${desired.limitMicros ?? 'uncapped'} micros`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * #27: the org's own spend limit on AI, a per-org singleton resource in the
+ * same shape as {@link planStorage}.
+ */
+function planAiBudget(org, byKey, claimed) {
+    const key = resourceKey('ai', 'budget', org.id);
+    const live = byKey.get(key);
+    if (live)
+        claimed.add(key);
+    const desired = { limitMicros: org.ai.limitMicros };
+    const liveLimitMicros = live ? (live.config.limitMicros ?? null) : null;
+    if (liveLimitMicros === desired.limitMicros)
+        return null;
+    return {
+        action: { system: 'ai', kind: 'budget', key: org.id, desired },
+        step: {
+            description: `set ${org.slug}'s AI budget limit to ${desired.limitMicros ?? 'uncapped'} micros`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * The org's cms site (`org.ts`'s `SiteConfig`), a per-org singleton
+ * resource modeled on {@link planMail}. Disabling a live site parks it,
+ * following mail's own park-not-delete rule (#7 corrections 1) -- a
+ * customer's site content is never something a plan deletes on its own. A
+ * `usesDomain` change (or re-enabling a previously parked site) is a plain
+ * hostname update, not a migration: unlike chat's re-key, nothing about the
+ * site's own content moves between two systems when its hostname changes
+ * between `<slug>.oikos.host` (`../slug.ts`) and the org's own `domain`.
+ */
+function planSite(org, byKey, claimed) {
+    const key = resourceKey('cms', 'site', org.id);
+    const live = byKey.get(key);
+    if (!org.site.enabled) {
+        // Nothing declared and nothing live: there is nothing to park.
+        if (!live)
+            return null;
+        claimed.add(key);
+        // Already parked: no step, or a plan would never reach empty (#14
+        // "repeat until plan returns empty") once the park step above ran.
+        if (!live.config.enabled)
+            return null;
+        return {
+            action: {
+                system: 'cms',
+                kind: 'site',
+                key: org.id,
+                desired: { enabled: false, usesDomain: org.site.usesDomain },
+            },
+            step: {
+                description: `park ${org.slug}'s cms site (stops serving; site content is retained, not deleted -- #7 corrections 1)`,
+                destroys: true,
+                migrates: false,
+            },
+        };
+    }
+    if (live)
+        claimed.add(key);
+    const desired = { enabled: true, usesDomain: org.site.usesDomain };
+    if (!live) {
+        return {
+            action: { system: 'cms', kind: 'site', key: org.id, desired },
+            step: {
+                description: `provision a cms site for ${org.slug}`,
+                destroys: false,
+                migrates: false,
+            },
+        };
+    }
+    const liveEnabled = Boolean(live.config.enabled);
+    const liveUsesDomain = Boolean(live.config.usesDomain);
+    if (liveEnabled === desired.enabled && liveUsesDomain === desired.usesDomain)
+        return null;
+    const hostname = desired.usesDomain ? (org.domain ?? 'its domain') : `${org.slug}.oikos.host`;
+    return {
+        action: { system: 'cms', kind: 'site', key: org.id, desired },
+        step: {
+            description: `move ${org.slug}'s cms site onto ${hostname}`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}

package/dist/plan/index.d.ts

@@ -0,0 +1,8 @@
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, } from './live.js';
+export { readLiveResources } from './live.js';
+export type { StepAction, PlannedStep, PlanDetail } from './diff.js';
+export { computePlanDetail, toPlan } from './diff.js';
+export type { AuditActor, AuditLog, AuthzGate, StepExecutor, FoundryPlanApplyOptions, } from './plan-apply.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan-apply.js';
+export type { ScopeResolver } from './providers-readers.js';
+export { ProvidersCloudflareReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, } from './providers-readers.js';

package/dist/plan/index.js

@@ -0,0 +1,4 @@
+export { readLiveResources } from './live.js';
+export { computePlanDetail, toPlan } from './diff.js';
+export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, } from './plan-apply.js';
+export { ProvidersCloudflareReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeScopeResolver, } from './providers-readers.js';

package/dist/plan/live.d.ts

@@ -0,0 +1,62 @@
+import type { OrgId } from '../org.js';
+/**
+ * One resource as seen live in one of foundry's six systems.
+ *
+ * `key` is unique within `(system, kind)`. Per-org singleton resources
+ * (issuer, mail, chat, storage's spend limit, AI's budget, the cms site —
+ * see `diff.ts`) are keyed by the {@link OrgId} itself; anything else foundry can see in
+ * that system's account/org is keyed however that system names it, so it can
+ * still be matched, or left
+ * {@link https://github.com/wtfalch/foundry/issues/10 unmanaged}, by
+ * `computePlanDetail`.
+ */
+export interface LiveResource {
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms';
+    kind: string;
+    key: string;
+    config: Record<string, unknown>;
+}
+/**
+ * One narrow interface per system (#19 "Done when"): a single read, scoped
+ * to one org, returning everything foundry can see there. Real
+ * implementations follow `bootstrap/coolify-api.ts`'s pattern in
+ * `wtfalch/app-template` — a token read from the environment or the secrets
+ * file, never the command line, never logged. Nothing here calls anything
+ * real; `plan-apply.test.ts` and `diff.test.ts` use fakes. Wiring real
+ * clients for `FilesReader`/`AiReader` (and every other reader here) is #20,
+ * a non-goal of #27.
+ */
+export interface ZitadelReader {
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+export interface CoolifyReader {
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+export interface CloudflareReader {
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+/** #27: reads the org's current storage spend limit as Files reports it. */
+export interface FilesReader {
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+/** #27: reads the org's current AI budget limit as AI reports it. */
+export interface AiReader {
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+/**
+ * Reads the org's current cms sites as `@wtfalch/cms` reports them -- the
+ * "standard" app form #14 decided ("our code, their CMS content").
+ */
+export interface CmsReader {
+    listResources(orgId: OrgId): Promise<LiveResource[]>;
+}
+export interface LiveReaders {
+    zitadel: ZitadelReader;
+    coolify: CoolifyReader;
+    cloudflare: CloudflareReader;
+    files: FilesReader;
+    ai: AiReader;
+    cms: CmsReader;
+}
+/** Every live resource foundry can see for `orgId`, across all six systems. */
+export declare function readLiveResources(orgId: OrgId, readers: LiveReaders): Promise<LiveResource[]>;

package/dist/plan/live.js

@@ -0,0 +1,12 @@
+/** Every live resource foundry can see for `orgId`, across all six systems. */
+export async function readLiveResources(orgId, readers) {
+    const [zitadel, coolify, cloudflare, files, ai, cms] = await Promise.all([
+        readers.zitadel.listResources(orgId),
+        readers.coolify.listResources(orgId),
+        readers.cloudflare.listResources(orgId),
+        readers.files.listResources(orgId),
+        readers.ai.listResources(orgId),
+        readers.cms.listResources(orgId),
+    ]);
+    return [...zitadel, ...coolify, ...cloudflare, ...files, ...ai, ...cms];
+}

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

@@ -0,0 +1,107 @@
+import type { PlanApply } from '../apply.js';
+import type { OrgId } from '../org.js';
+import type { Plan } from '../plan.js';
+import type { AppliedState } from '../state.js';
+import type { DeclaredOrgStore } from '../store.js';
+import { type StepAction } from './diff.js';
+import { type LiveReaders } from './live.js';
+/** Who did it, for `@wtfalch/audit`'s "who, when, the plan, the result" (#9, #19). */
+export interface AuditActor {
+    readonly id: string;
+    readonly display: string;
+}
+/**
+ * The seam onto `@wtfalch/audit`.
+ *
+ * #19 asks for `@wtfalch/audit` itself, but that package's `record`/`ledger`
+ * (see `app-template/src/lib/authz/audit.ts`) is bound to one app's Drizzle
+ * table, session model and closed `EventName`/`ActorClass` vocabulary — none
+ * of which foundry's SDK package has (it has no database of its own; #18
+ * owns the store). Adopting it here is more than a small change, so this is
+ * the interface instead, logged as a Finding on #19 rather than a half
+ * adoption. A real implementation binds `@wtfalch/audit`'s `ledger.sign` to
+ * foundry's own vocabulary and table once foundry has one.
+ */
+export interface AuditLog {
+    recordPlan(entry: {
+        actor: AuditActor;
+        orgId: OrgId;
+        plan: Plan;
+        at: Date;
+    }): Promise<void>;
+    recordApply(entry: {
+        actor: AuditActor;
+        orgId: OrgId;
+        plan: Plan;
+        outcome: 'applied' | 'refused' | 'failed';
+        reason?: string;
+        at: Date;
+    }): Promise<void>;
+}
+/**
+ * The seam onto `@wtfalch/authz`, gating `apply` only — `plan` is a read
+ * (managed-settings: "Reads are free"). Same reasoning as {@link AuditLog}
+ * for not adopting the package directly here: `@wtfalch/authz`'s
+ * `permitsRead`/`Access` are resolved from an app's own session and tenant
+ * model, which foundry's SDK package does not have.
+ */
+export interface AuthzGate {
+    canApply(actor: AuditActor, orgId: OrgId): Promise<boolean>;
+}
+/**
+ * Makes one {@link StepAction} true against a real system. No implementation
+ * ships in this package — #19's job is the seam and the refusal rules,
+ * proven against fakes; a real executor (calling Coolify/Zitadel/Cloudflare)
+ * is #20's "provision Company Factory end to end".
+ */
+export interface StepExecutor {
+    execute(action: StepAction): Promise<{
+        resourceId?: string;
+    } | undefined>;
+}
+export declare class DeclaredOrgNotFoundError extends Error {
+    constructor(orgId: OrgId);
+}
+/** #10 (resolved): "an apply is refused when its plan no longer matches reality." */
+export declare class StalePlanError extends Error {
+    constructor(orgId: OrgId);
+}
+/** #9 (resolved): "any step that destroys or migrates requires the org's name typed." */
+export declare class ConfirmationRequiredError extends Error {
+    constructor(orgId: OrgId);
+}
+export declare class NotAuthorizedError extends Error {
+    constructor(actor: AuditActor, orgId: OrgId);
+}
+export interface FoundryPlanApplyOptions {
+    store: DeclaredOrgStore;
+    readers: LiveReaders;
+    executor: StepExecutor;
+    audit: AuditLog;
+    authz: AuthzGate;
+    /** The operator running this plan/apply — every audit row's "who" (#9, #19). */
+    actor: AuditActor;
+    /** Overridable for tests; defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+/**
+ * The #19 implementation of {@link PlanApply}: computes a plan against live
+ * state, and refuses to apply one that has gone stale, one that touches a
+ * destructive or migrating step without the org's name typed, or one the
+ * actor is not authorized to run.
+ */
+export declare class FoundryPlanApply implements PlanApply {
+    private readonly store;
+    private readonly readers;
+    private readonly executor;
+    private readonly audit;
+    private readonly authz;
+    private readonly actor;
+    private readonly now;
+    constructor(options: FoundryPlanApplyOptions);
+    plan(id: OrgId): Promise<Plan>;
+    apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    private refuse;
+    private runSteps;
+    private computeFreshPlan;
+}