@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/bootstrap/bootstrap.d.ts

@@ -0,0 +1,111 @@
+import type { MigrateSql } from '../migrate.js';
+import type { PlatformLiveReaders, PlatformStepExecutor } from '../plan/index.js';
+import type { FoundryPlatformStepExecutorOptions } from '../plan/platform-providers.js';
+import type { FoundryStoreDb } from '../store/postgres.js';
+import type { BootstrapCompany, BootstrapOwner } from './declare.js';
+export interface BootstrapPlatformInput {
+    company: BootstrapCompany;
+    owner: BootstrapOwner;
+}
+/**
+ * The master keys, read from the host's held keys by the caller.
+ *
+ * #213: `coolifyUrl`, `coolifyToken` and `cloudflareApiToken` are also what
+ * `bootstrapPlatform` puts as Archon's own held keys
+ * (`platform:master:coolify-url`, `-coolify-token`, `-cloudflare-token`)
+ * before Archon's app deploys, so its onboarding can read them back.
+ * `cloudflareApiToken` needs "API Tokens Write" for that: Archon mints its
+ * own scoped child tokens from it.
+ */
+export interface RootCredentials {
+    coolifyUrl: string;
+    coolifyToken: string;
+    cloudflareApiToken: string;
+    cloudflareAccountId: string;
+    /** Headers for a Coolify panel behind Cloudflare Access. */
+    accessHeaders?: Record<string, string>;
+}
+/** What Archon's onboarding screen shows: one event per phase or round. */
+export interface BootstrapProgress {
+    phase: 'migrate' | 'declare' | 'plan' | 'apply' | 'done';
+    round?: number;
+    message: string;
+    steps?: string[];
+}
+/** Everything foundry's per-step executors take besides the two clients and `deliverSecret`. */
+export type BootstrapExecutorDeps = Omit<FoundryPlatformStepExecutorOptions, 'coolify' | 'deliverSecret'>;
+export interface BootstrapPlatformDeps {
+    /** Foundry's tables live here; the store, the audit log and the plan all use it. */
+    db: FoundryStoreDb;
+    /** The same database, for the migration runner. */
+    migrateSql: MigrateSql;
+    rootCredentials: () => Promise<RootCredentials>;
+    deliverSecret: (ref: string, secret: string) => Promise<void>;
+    /**
+     * `put` (#213) is optional, like `PlatformArchonDeps.heldKeys`'s own: a
+     * host without one still compiles, and Archon's master keys are reported
+     * blocked, not skipped, while it is missing.
+     */
+    heldKeys: {
+        resolve(ref: string): Promise<string | null>;
+        put?(ref: string, value: string): Promise<void>;
+    };
+    /** Per-step dependencies (auth, mail, files, ai, integrations, archon, sfu). A step without its own is reported blocked. */
+    executor?: BootstrapExecutorDeps;
+    onProgress?: (event: BootstrapProgress) => void;
+    /** Rounds before the run gives up. Default 20. */
+    maxRounds?: number;
+    /**
+     * Replaces the live readers and step executor foundry builds from the root
+     * credentials. It receives the redacting `deliverSecret` and `heldKeys`, so
+     * whatever it delivers or resolves is covered. For tests and hosts with
+     * their own clients.
+     */
+    runtime?: (ports: {
+        credentials: RootCredentials;
+        deliverSecret: (ref: string, secret: string) => Promise<void>;
+        heldKeys: BootstrapPlatformDeps['heldKeys'];
+    }) => {
+        readers: PlatformLiveReaders;
+        executor: PlatformStepExecutor;
+    };
+}
+export interface BootstrapResult {
+    /** Step descriptions applied across every round, in order. */
+    applied: string[];
+    /** Steps the plan reported blocked, by service name (`UnmanagedItem.key`), with the planner's message. */
+    blocked: Array<{
+        step: string;
+        message: string;
+    }>;
+    /** The one step that threw (`apply` when the failure was outside any step), or `rounds` at the cap. */
+    failed?: {
+        step: string;
+        message: string;
+    };
+    /** True only when every declared step is applied and nothing is blocked or failed. */
+    complete: boolean;
+}
+/** Replaces every collected secret in a string. Secrets are added as they appear, so later output is covered too. */
+export declare class Redactor {
+    private readonly secrets;
+    add(...values: Array<string | null | undefined>): void;
+    /** Adds every string leaf of a value (skipping functions, capped in depth) that is long enough to be a secret and not a plain URL. */
+    addDeep(value: unknown, depth?: number, seen?: Set<unknown>): void;
+    text(input: string): string;
+}
+/** Wraps the secret-carrying ports inside one step's deps so what they deliver or resolve is redacted. */
+export declare function guardStepDeps(executor: BootstrapExecutorDeps | undefined, redactor: Redactor, deliverSecret: (ref: string, secret: string) => Promise<void>, heldKeys: BootstrapPlatformDeps['heldKeys']): BootstrapExecutorDeps;
+/**
+ * The platform's first apply, run from Archon's onboarding flow: migrates
+ * foundry's tables, declares Company Included and the platform (never
+ * overwriting a row already there), then plans and applies round by round
+ * until every step is applied or reported blocked. Reads no env and no file:
+ * the database, root credentials, held keys and every per-step dependency
+ * come in through `deps`.
+ *
+ * Every root credential, every secret delivered and every held key resolved
+ * during the run is redacted from progress events, the result and any error
+ * thrown. Running it again applies nothing already applied.
+ */
+export declare function bootstrapPlatform(input: BootstrapPlatformInput, deps: BootstrapPlatformDeps): Promise<BootstrapResult>;

package/dist/bootstrap/bootstrap.js

@@ -0,0 +1,323 @@
+import { CloudflareClient } from '@wtfalch/providers/cloudflare';
+import { CoolifyClient } from '@wtfalch/providers/coolify';
+import { migrate } from '../migrate.js';
+import { FoundryPlanApply, FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, } from '../plan/index.js';
+import { createPostgresAuditLog } from '../store/audit.js';
+import { createPostgresDeclaredOrgStore, createPostgresPlatformStore } from '../store/postgres.js';
+import { COMPANY_INCLUDED_ORG_ID, declaredCompanyOrg, declaredPlatformFor, ownerIdentity, } from './declare.js';
+import { driveApply } from './drive.js';
+const REDACTED = '<redacted>';
+/** Shorter strings in `deps.executor` are settings ("main", ports), not secrets, and would mangle every message. */
+const MIN_DEEP_SECRET = 8;
+const MAX_DEEP_DEPTH = 6;
+/** A URL with no userinfo carries no secret and appears in ordinary step text. */
+const PLAIN_URL = /^https?:\/\/[^@\s]*$/;
+/** Replaces every collected secret in a string. Secrets are added as they appear, so later output is covered too. */
+export class Redactor {
+    secrets = new Set();
+    add(...values) {
+        for (const value of values)
+            if (value)
+                this.secrets.add(value);
+    }
+    /** Adds every string leaf of a value (skipping functions, capped in depth) that is long enough to be a secret and not a plain URL. */
+    addDeep(value, depth = 0, seen = new Set()) {
+        if (typeof value === 'string') {
+            if (value.length >= MIN_DEEP_SECRET && !PLAIN_URL.test(value))
+                this.secrets.add(value);
+            return;
+        }
+        if (depth >= MAX_DEEP_DEPTH || value === null || typeof value !== 'object' || seen.has(value)) {
+            return;
+        }
+        seen.add(value);
+        for (const child of Object.values(value))
+            this.addDeep(child, depth + 1, seen);
+    }
+    text(input) {
+        let out = input;
+        for (const secret of [...this.secrets].sort((a, b) => b.length - a.length)) {
+            out = out.split(secret).join(REDACTED);
+        }
+        return out;
+    }
+}
+const allowPlatformApply = {
+    async canApply() {
+        return false;
+    },
+    async canDestroy() {
+        return false;
+    },
+    async canApplyPlatform() {
+        return true;
+    },
+};
+/** `FoundryPlanApply` needs org-scoped parts this run never uses; each refuses if called. */
+const unusedOrgExecutor = {
+    async execute() {
+        throw new Error('bootstrapPlatform never applies an org');
+    },
+    async destroy() {
+        throw new Error('bootstrapPlatform never destroys an org');
+    },
+};
+const unusedOrgReader = { listResources: async () => [] };
+/** The audit log with every free-text field run through the redactor before it is stored. */
+function redactingAudit(inner, redactor) {
+    const plan = (p) => ({
+        ...p,
+        steps: p.steps.map((s) => ({ ...s, description: redactor.text(s.description) })),
+        unmanaged: p.unmanaged.map((u) => ({ ...u, description: redactor.text(u.description) })),
+    });
+    return {
+        recordPlan: (entry) => inner.recordPlan({ ...entry, plan: plan(entry.plan) }),
+        recordApply: (entry) => inner.recordApply({
+            ...entry,
+            plan: plan(entry.plan),
+            ...(entry.reason === undefined ? {} : { reason: redactor.text(entry.reason) }),
+        }),
+        recordDestroy: (entry) => inner.recordDestroy({
+            ...entry,
+            ...(entry.reason === undefined ? {} : { reason: redactor.text(entry.reason) }),
+        }),
+    };
+}
+/** Wraps the secret-carrying ports inside one step's deps so what they deliver or resolve is redacted. */
+export function guardStepDeps(executor, redactor, deliverSecret, heldKeys) {
+    const out = { ...executor };
+    const minter = executor?.ai?.managementKeyMinter;
+    if (executor?.ai && minter) {
+        out.ai = {
+            ...executor.ai,
+            managementKeyMinter: {
+                async mintManagementKey(input) {
+                    const minted = await minter.mintManagementKey(input);
+                    redactor.add(minted.secret);
+                    return minted;
+                },
+            },
+        };
+    }
+    for (const key of ['auth', 'mail', 'integrations', 'files', 'ai', 'archon']) {
+        const deps = out[key];
+        if (!deps)
+            continue;
+        const copy = { ...deps };
+        if ('deliverSecret' in copy)
+            copy.deliverSecret = deliverSecret;
+        // #201: ai's own default minter needs heldKeys too, to re-sign a mint
+        // request against its signing key when an earlier run pinned it but
+        // crashed before the management key itself was minted and delivered.
+        if (key === 'archon' || key === 'ai' || 'heldKeys' in copy)
+            copy.heldKeys = heldKeys;
+        out[key] = copy;
+    }
+    return out;
+}
+/**
+ * #213: stamps `PlatformArchonDeps.masterKeys` from the root credentials
+ * `bootstrapPlatform` already resolved, onto whatever the host gave the
+ * archon step through `deps.executor.archon` -- the values are
+ * `credentials`' own, not something the host names separately, so this is
+ * not one more thing for `guardStepDeps`'s caller to wire by hand. A run
+ * with no `archon` deps at all (the step then reported blocked, as before)
+ * is passed through unchanged.
+ */
+function archonMasterKeys(guarded, credentials) {
+    if (!guarded.archon)
+        return guarded;
+    return {
+        ...guarded,
+        archon: {
+            ...guarded.archon,
+            masterKeys: {
+                coolifyUrl: credentials.coolifyUrl,
+                coolifyToken: credentials.coolifyToken,
+                cloudflareParentToken: credentials.cloudflareApiToken,
+            },
+        },
+    };
+}
+/**
+ * The platform's first apply, run from Archon's onboarding flow: migrates
+ * foundry's tables, declares Company Included and the platform (never
+ * overwriting a row already there), then plans and applies round by round
+ * until every step is applied or reported blocked. Reads no env and no file:
+ * the database, root credentials, held keys and every per-step dependency
+ * come in through `deps`.
+ *
+ * Every root credential, every secret delivered and every held key resolved
+ * during the run is redacted from progress events, the result and any error
+ * thrown. Running it again applies nothing already applied.
+ */
+export async function bootstrapPlatform(input, deps) {
+    const redactor = new Redactor();
+    const emit = (event) => {
+        deps.onProgress?.({
+            ...event,
+            message: redactor.text(event.message),
+            ...(event.steps ? { steps: event.steps.map((s) => redactor.text(s)) } : {}),
+        });
+    };
+    try {
+        ownerIdentity(input.owner);
+        redactor.addDeep(deps.executor);
+        const credentials = await deps.rootCredentials();
+        redactor.add(credentials.coolifyToken, credentials.cloudflareApiToken, credentials.cloudflareAccountId, ...Object.values(credentials.accessHeaders ?? {}));
+        const deliverSecret = async (ref, secret) => {
+            redactor.add(secret);
+            await deps.deliverSecret(ref, secret);
+        };
+        const heldKeys = {
+            async resolve(ref) {
+                const value = await deps.heldKeys.resolve(ref);
+                redactor.add(value);
+                return value;
+            },
+            // #213: only present when the host's own heldKeys can put, so a host
+            // without one leaves Archon's master keys reported blocked rather
+            // than silently no-op'd.
+            ...(deps.heldKeys.put
+                ? {
+                    async put(ref, value) {
+                        redactor.add(value);
+                        await deps.heldKeys.put?.(ref, value);
+                    },
+                }
+                : {}),
+        };
+        const migrated = await migrate(deps.migrateSql);
+        emit({
+            phase: 'migrate',
+            message: migrated.applied.length === 0
+                ? 'foundry tables already up to date'
+                : `migrated: ${migrated.applied.join(', ')}`,
+        });
+        const orgStore = createPostgresDeclaredOrgStore(deps.db);
+        const platformStore = createPostgresPlatformStore(deps.db);
+        if (await orgStore.get(COMPANY_INCLUDED_ORG_ID)) {
+            emit({ phase: 'declare', message: 'declared org already written' });
+        }
+        else {
+            await orgStore.create(declaredCompanyOrg(input.company, input.owner));
+            emit({ phase: 'declare', message: `declared org "${input.company.name}" written` });
+        }
+        const existing = await platformStore.get();
+        if (existing) {
+            emit({ phase: 'declare', message: `declared platform already written for ${existing.apex}` });
+        }
+        else {
+            await platformStore.put(declaredPlatformFor(input.company.apex));
+            emit({
+                phase: 'declare',
+                message: `declared platform written for ${input.company.apex}`,
+            });
+        }
+        let runtime;
+        if (deps.runtime) {
+            runtime = deps.runtime({ credentials, deliverSecret, heldKeys });
+        }
+        else {
+            const coolify = new CoolifyClient(credentials.coolifyUrl, credentials.coolifyToken, {
+                accessHeaders: credentials.accessHeaders,
+            });
+            const cloudflare = new CloudflareClient(credentials.cloudflareApiToken, credentials.cloudflareAccountId);
+            runtime = {
+                readers: {
+                    cloudflare: new ProvidersPlatformCloudflareReader(cloudflare, platformStore),
+                    coolify: new ProvidersPlatformCoolifyReader(coolify, platformStore),
+                },
+                executor: new FoundryPlatformStepExecutor(cloudflare, orgStore, {
+                    coolify,
+                    deliverSecret,
+                    ...archonMasterKeys(guardStepDeps(deps.executor, redactor, deliverSecret, heldKeys), credentials),
+                }),
+            };
+        }
+        // Each step reports when it starts and ends, so a failure names one step.
+        let progress = { started: 0, completed: 0 };
+        const inner = runtime.executor;
+        const executor = {
+            execute: async (action, context) => {
+                progress.started++;
+                const result = await inner.execute(action, context);
+                progress.completed++;
+                return result;
+            },
+            ...(inner.blockedSteps
+                ? { blockedSteps: (platform, ids) => inner.blockedSteps?.(platform, ids) ?? {} }
+                : {}),
+            ...(inner.driftedSteps
+                ? { driftedSteps: (platform, ids) => inner.driftedSteps?.(platform, ids) ?? {} }
+                : {}),
+        };
+        const planApply = new FoundryPlanApply({
+            store: orgStore,
+            readers: {
+                zitadel: unusedOrgReader,
+                coolify: unusedOrgReader,
+                cloudflare: unusedOrgReader,
+                files: unusedOrgReader,
+                ai: unusedOrgReader,
+                cms: unusedOrgReader,
+            },
+            executor: unusedOrgExecutor,
+            destroyer: unusedOrgExecutor,
+            audit: redactingAudit(createPostgresAuditLog(deps.db), redactor),
+            authz: allowPlatformApply,
+            actor: { id: 'bootstrap-platform', display: 'bootstrapPlatform' },
+            platform: { store: platformStore, readers: runtime.readers, executor },
+        });
+        const driven = await driveApply({
+            plan: () => planApply.planPlatform(),
+            apply: (plan, stepProgress) => {
+                progress = stepProgress;
+                return planApply.applyPlatform(plan, 'platform');
+            },
+            maxRounds: deps.maxRounds,
+            onPlan: (round, plan) => emit({
+                phase: 'plan',
+                round,
+                message: `round ${round}: ${plan.steps.length} step(s) planned`,
+                steps: plan.steps.map((s) => s.description),
+            }),
+            onApplied: (round, plan) => emit({
+                phase: 'apply',
+                round,
+                message: `round ${round}: applied`,
+                steps: plan.steps.map((s) => s.description),
+            }),
+        });
+        const blocked = (driven.failed ? [] : (driven.lastPlan?.unmanaged ?? []))
+            .filter((item) => item.key !== undefined)
+            .map((item) => ({
+            step: item.key,
+            message: redactor.text(item.description),
+        }));
+        const result = {
+            applied: driven.applied.map((s) => redactor.text(s)),
+            blocked,
+            complete: !driven.failed && blocked.length === 0 && driven.lastPlan?.steps.length === 0,
+            ...(driven.failed
+                ? {
+                    failed: {
+                        step: redactor.text(driven.failed.step),
+                        message: redactor.text(driven.failed.message),
+                    },
+                }
+                : {}),
+        };
+        emit({
+            phase: 'done',
+            message: driven.failed
+                ? `stopped: ${result.failed?.message}`
+                : `${result.applied.length} step(s) applied, ${blocked.length} blocked`,
+        });
+        return result;
+    }
+    catch (error) {
+        const text = error instanceof Error ? error.message : String(error);
+        throw new Error(redactor.text(text));
+    }
+}

package/dist/bootstrap/declare.d.ts

@@ -0,0 +1,36 @@
+import type { DeclaredOrg, OrgId, OwnerIdentity } from '../org.js';
+import type { DeclaredPlatform } from '../platform.js';
+/** Company Included's own org id, the same literal `test/fakes.ts`'s `basePlatform()` uses for `ownerOrgId`. */
+export declare const COMPANY_INCLUDED_ORG_ID: OrgId;
+export declare const DEFAULT_GIT_REF = "main";
+/**
+ * The Stalwart image tag the platform's mail step runs. `platform.mail.gitRef`
+ * is an image tag, not a git ref, and the planner blocks a floating one
+ * (`platform-providers.ts`, `mailImageTagBlocked`), so this is a pinned release.
+ */
+export declare const DEFAULT_MAIL_IMAGE_TAG = "v0.16.24";
+export interface BootstrapCompany {
+    name: string;
+    slug: string;
+    apex: string;
+}
+export interface BootstrapOwner {
+    givenName: string;
+    familyName: string;
+    email: string;
+}
+/**
+ * The owner as `OwnerIdentity`, trimmed. Throws a plain error naming the
+ * field when one is empty or the email is not an address.
+ */
+export declare function ownerIdentity(owner: BootstrapOwner): OwnerIdentity;
+/**
+ * Company Included's declared org: the platform's owner, running no app, mail
+ * or chat of its own.
+ */
+export declare function declaredCompanyOrg(company: BootstrapCompany, owner: BootstrapOwner): DeclaredOrg;
+/**
+ * The declared platform under `apex`. A disabled service keeps an empty
+ * `gitRef`, which `validatePlatform` allows.
+ */
+export declare function declaredPlatformFor(apex: string): DeclaredPlatform;

package/dist/bootstrap/declare.js

@@ -0,0 +1,99 @@
+import { validateOwner } from '../org.js';
+import { PLATFORM_SERVICE_KEYS, defaultPlatformHostname } from '../platform.js';
+/** Company Included's own org id, the same literal `test/fakes.ts`'s `basePlatform()` uses for `ownerOrgId`. */
+export const COMPANY_INCLUDED_ORG_ID = 'org_company_included';
+export const DEFAULT_GIT_REF = 'main';
+/**
+ * The Stalwart image tag the platform's mail step runs. `platform.mail.gitRef`
+ * is an image tag, not a git ref, and the planner blocks a floating one
+ * (`platform-providers.ts`, `mailImageTagBlocked`), so this is a pinned release.
+ */
+export const DEFAULT_MAIL_IMAGE_TAG = 'v0.16.24';
+/**
+ * Every platform service except `sfu` is enabled, like the other steps: a
+ * service whose dependencies the host did not supply is reported blocked, not
+ * planned. `sfu` stays off because it needs a held SSH key and host
+ * fingerprint, a separate human step (issue 170).
+ */
+const SERVICES_ENABLED_BY_DEFAULT = new Set([
+    'auth',
+    'mail',
+    'files',
+    'ai',
+    'jobs',
+    'integrations',
+    'archon',
+]);
+/**
+ * The owner as `OwnerIdentity`, trimmed. Throws a plain error naming the
+ * field when one is empty or the email is not an address.
+ */
+export function ownerIdentity(owner) {
+    const identity = {
+        email: owner.email?.trim() ?? '',
+        givenName: owner.givenName?.trim() ?? '',
+        familyName: owner.familyName?.trim() ?? '',
+    };
+    const problem = validateOwner(identity);
+    if (problem)
+        throw new Error(`bootstrapPlatform: ${problem}`);
+    return identity;
+}
+/**
+ * Company Included's declared org: the platform's owner, running no app, mail
+ * or chat of its own.
+ */
+export function declaredCompanyOrg(company, owner) {
+    return {
+        id: COMPANY_INCLUDED_ORG_ID,
+        slug: company.slug,
+        displayName: company.name,
+        domain: null,
+        mail: {
+            mode: 'off',
+            usesDomain: false,
+            ownerMailboxAddress: null,
+            noReplyLocalPart: 'no-reply',
+        },
+        chat: { usesDomain: false },
+        calls: { enabled: false, usesDomain: false },
+        issuer: { usesDomain: false },
+        site: { enabled: false, usesDomain: false },
+        hosting: {
+            enabled: false,
+            usesDomain: false,
+            database: false,
+            tunnel: false,
+            gitBranch: DEFAULT_GIT_REF,
+            buildPack: 'nixpacks',
+            accessEmails: [],
+            issuerApps: [],
+        },
+        sso: { enabled: false },
+        guests: { enabled: false },
+        solo: { enabled: false },
+        storage: { limitBytes: null, limitMicros: null },
+        ai: { limitMicros: null },
+        buyer: { legalName: null, orgNumber: null, address: null, vatRegistered: null },
+        bespokeAppRepo: null,
+        adoptedApp: null,
+        owner: ownerIdentity(owner),
+        test: false,
+    };
+}
+/**
+ * The declared platform under `apex`. A disabled service keeps an empty
+ * `gitRef`, which `validatePlatform` allows.
+ */
+export function declaredPlatformFor(apex) {
+    const services = {};
+    for (const key of PLATFORM_SERVICE_KEYS) {
+        const enabled = SERVICES_ENABLED_BY_DEFAULT.has(key);
+        services[key] = {
+            enabled,
+            hostname: defaultPlatformHostname(key, apex),
+            gitRef: !enabled ? '' : key === 'mail' ? DEFAULT_MAIL_IMAGE_TAG : DEFAULT_GIT_REF,
+        };
+    }
+    return { ownerOrgId: COMPANY_INCLUDED_ORG_ID, apex, ...services };
+}

package/dist/bootstrap/drive.d.ts

@@ -0,0 +1,40 @@
+import type { Plan } from '../plan.js';
+export declare const DEFAULT_MAX_ROUNDS = 20;
+/** How far one round's steps got. */
+export interface StepProgress {
+    started: number;
+    completed: number;
+}
+export interface DriveApplyOptions {
+    plan: () => Promise<Plan>;
+    /**
+     * Runs one round's plan. It must keep `progress` current: `started` when a
+     * step begins, `completed` when it returns. A throw is then attributed to
+     * the step that began and did not complete.
+     */
+    apply: (plan: Plan, progress: StepProgress) => Promise<unknown>;
+    maxRounds?: number;
+    /** Called with each round's plan before it is applied. */
+    onPlan?: (round: number, plan: Plan) => void;
+    /** Called after a round's apply returned. */
+    onApplied?: (round: number, plan: Plan) => void;
+}
+export interface DriveApplyResult {
+    rounds: number;
+    /** Step descriptions applied, in the order they ran. */
+    applied: string[];
+    /** The last plan computed: empty of steps unless the loop failed or hit the cap. */
+    lastPlan: Plan | null;
+    /** `step` is the one step that threw, or `apply` when the failure was outside any step. Steps completed before it are in `applied`. */
+    failed?: {
+        step: string;
+        message: string;
+    };
+}
+/**
+ * Plans and applies round by round until a plan has no steps (every step
+ * applied, or reported blocked in `Plan.unmanaged`), an apply throws, or
+ * `maxRounds` is reached. One `applyPlatform` call runs every step of that
+ * round's plan in order; `progress` gives the per-step result when one throws.
+ */
+export declare function driveApply(options: DriveApplyOptions): Promise<DriveApplyResult>;

package/dist/bootstrap/drive.js

@@ -0,0 +1,51 @@
+export const DEFAULT_MAX_ROUNDS = 20;
+/**
+ * Plans and applies round by round until a plan has no steps (every step
+ * applied, or reported blocked in `Plan.unmanaged`), an apply throws, or
+ * `maxRounds` is reached. One `applyPlatform` call runs every step of that
+ * round's plan in order; `progress` gives the per-step result when one throws.
+ */
+export async function driveApply(options) {
+    const maxRounds = options.maxRounds ?? DEFAULT_MAX_ROUNDS;
+    const applied = [];
+    let lastPlan = null;
+    let rounds = 0;
+    while (rounds < maxRounds) {
+        const plan = await options.plan();
+        rounds++;
+        lastPlan = plan;
+        options.onPlan?.(rounds, plan);
+        if (plan.steps.length === 0)
+            return { rounds, applied, lastPlan };
+        const progress = { started: 0, completed: 0 };
+        try {
+            await options.apply(plan, progress);
+        }
+        catch (error) {
+            for (const step of plan.steps.slice(0, progress.completed))
+                applied.push(step.description);
+            const running = progress.started > progress.completed ? plan.steps[progress.completed] : null;
+            return {
+                rounds,
+                applied,
+                lastPlan,
+                failed: {
+                    step: running?.description ?? 'apply',
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            };
+        }
+        for (const step of plan.steps)
+            applied.push(step.description);
+        options.onApplied?.(rounds, plan);
+    }
+    return {
+        rounds,
+        applied,
+        lastPlan,
+        failed: {
+            step: 'rounds',
+            message: `the platform did not settle after ${maxRounds} rounds; steps still planned: ${lastPlan?.steps.map((s) => s.description).join(', ') ?? ''}`,
+        },
+    };
+}

package/dist/bootstrap/index.d.ts

@@ -0,0 +1,3 @@
+export type { BootstrapCompany, BootstrapOwner, } from './declare.js';
+export type { BootstrapExecutorDeps, BootstrapPlatformDeps, BootstrapPlatformInput, BootstrapProgress, BootstrapResult, RootCredentials, } from './bootstrap.js';
+export { bootstrapPlatform } from './bootstrap.js';

package/dist/bootstrap/index.js

@@ -0,0 +1 @@
+export { bootstrapPlatform } from './bootstrap.js';