@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/plan/platform-org-ports.d.ts

@@ -0,0 +1,50 @@
+import type { PlatformStore } from '../store.js';
+import type { AiOrganisationPort, FilesOrganisationPort, JobsSchedulerPort } from './executor.js';
+import type { HeldKeyResolver } from './platform-org.js';
+/**
+ * #177: what `platform-org.ts`'s readiness could not see between a plan and
+ * its apply. The planner blocks these first; this is the executor's guard for
+ * a key or address that went away in between. The message names the service
+ * and the ref, never a value.
+ */
+export declare class PlatformOrgBlockedError extends Error {
+    constructor(service: string, what: string);
+}
+/**
+ * The seam onto the files and AI SDKs, which this package does not depend on.
+ * Foundry decides the address and the key; the host only says how to speak the
+ * service's protocol with them.
+ */
+export interface PlatformOrgClientFactories {
+    files(input: {
+        baseUrl: string;
+        issuer: string;
+        keyId: string;
+        /** The Ed25519 management private key, PKCS#8 PEM. */
+        privateKeyPem: string;
+    }): FilesOrganisationPort;
+    ai(input: {
+        baseUrl: string;
+        managementKey: string;
+    }): AiOrganisationPort;
+}
+/**
+ * #177: the org steps' files, AI and jobs ports, built from the platform's
+ * recorded addresses and `heldKeys.resolve(<ref>)` instead of being built by
+ * the host. `executor.ts`'s `FoundryStepExecutorPorts.platformOrg` takes one;
+ * a port set directly there still wins, for tests.
+ */
+export declare class PlatformOrgPorts {
+    private readonly options;
+    constructor(options: {
+        store: Pick<PlatformStore, 'get' | 'getServiceIds'>;
+        heldKeys: HeldKeyResolver;
+        clients: PlatformOrgClientFactories;
+        fetch?: typeof fetch;
+    });
+    files(): Promise<FilesOrganisationPort>;
+    ai(): Promise<AiOrganisationPort>;
+    jobs(): Promise<JobsSchedulerPort>;
+    private recorded;
+    private held;
+}

package/dist/plan/platform-org-ports.js

@@ -0,0 +1,70 @@
+import { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';
+import { PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, } from './platform-diff.js';
+import { FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+/**
+ * #177: what `platform-org.ts`'s readiness could not see between a plan and
+ * its apply. The planner blocks these first; this is the executor's guard for
+ * a key or address that went away in between. The message names the service
+ * and the ref, never a value.
+ */
+export class PlatformOrgBlockedError extends Error {
+    constructor(service, what) {
+        super(`${service} is blocked: ${what}`);
+        this.name = 'PlatformOrgBlockedError';
+    }
+}
+/**
+ * #177: the org steps' files, AI and jobs ports, built from the platform's
+ * recorded addresses and `heldKeys.resolve(<ref>)` instead of being built by
+ * the host. `executor.ts`'s `FoundryStepExecutorPorts.platformOrg` takes one;
+ * a port set directly there still wins, for tests.
+ */
+export class PlatformOrgPorts {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async files() {
+        const baseUrl = await this.recorded('files', PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY);
+        const privateKeyPem = await this.held('files', FILES_MANAGEMENT_KEY_REF);
+        return this.options.clients.files({
+            baseUrl,
+            issuer: FILES_MANAGEMENT_ISSUER,
+            keyId: FILES_MANAGEMENT_KEY_ID,
+            privateKeyPem,
+        });
+    }
+    async ai() {
+        const baseUrl = await this.recorded('ai', PLATFORM_AI_INTERNAL_URL_SCOPE_KEY);
+        const managementKey = await this.held('ai', PLATFORM_AI_MANAGEMENT_KEY_REF);
+        return this.options.clients.ai({ baseUrl, managementKey });
+    }
+    async jobs() {
+        const platform = await this.options.store.get();
+        if (!platform?.jobs.enabled) {
+            throw new PlatformOrgBlockedError('jobs', 'the platform does not declare a jobs scheduler');
+        }
+        const token = await this.held('jobs', JOBS_ADMIN_TOKEN_REF);
+        return new HttpJobsSchedulerClient(`https://${platform.jobs.hostname}`, token, this.options.fetch);
+    }
+    async recorded(service, scopeKey) {
+        const value = (await this.options.store.getServiceIds())[scopeKey];
+        if (!value) {
+            throw new PlatformOrgBlockedError(service, `the platform has not recorded its ${scopeKey} address yet`);
+        }
+        return value;
+    }
+    async held(service, ref) {
+        let value;
+        try {
+            value = await this.options.heldKeys.resolve(ref);
+        }
+        catch {
+            // The resolver's error could carry provider detail; report the ref only.
+        }
+        if (!value) {
+            throw new PlatformOrgBlockedError(service, `the platform key ${ref} is not held yet`);
+        }
+        return value;
+    }
+}

package/dist/plan/platform-org.d.ts

@@ -0,0 +1,120 @@
+import type { DeclaredPlatform } from '../platform.js';
+import type { AgoraHostValues } from './agora.js';
+/**
+ * https://github.com/wtfalch/foundry/issues/177: what an org step needs to
+ * know about the platform it runs on -- whether each shared service it
+ * depends on is enabled *and* applied (not just declared), and the one
+ * address `coolify:mail`'s own step used to read as a literal
+ * (`executor.ts`'s old `MAIL_APEX`/`MAIL_HOST` constants). Built by
+ * {@link orgPlatformReadinessFrom} from the very `DeclaredPlatform` + applied
+ * service ids `planPlatform` (`platform-diff.ts`) already reasons over -- the
+ * same "declared vs applied" distinction every platform step already makes
+ * for itself (CLAUDE.md's "Blocked, not failing": a step this package cannot
+ * yet make true is reported blocked, never planned to fail).
+ *
+ * `diff.ts`'s `computePlanDetail` takes this as one optional argument rather
+ * than five, so a host wiring a platform in later touches one call site, not
+ * every org step (`platform-diff.ts`'s own `PlanPlatformOptions` doc comment
+ * names the same "positional arguments that shifted on every merge" problem
+ * this avoids).
+ */
+export interface OrgPlatformReadiness {
+    /**
+     * `null` until the platform's own mail server (#169) is enabled and
+     * applied; the address `coolify:mail` then writes into its step instead of
+     * a literal, and `org.mail.mode !== 'off'` with this `null` is what makes
+     * that org's mail step blocked rather than planned.
+     */
+    mailHost: {
+        apex: string;
+        mailHost: string;
+    } | null;
+    /** The files host (#171). Files is always on for every org (#80), so `false` always blocks rather than only mattering when a flag is set. */
+    filesReady: boolean;
+    /** The AI host (#172), the same always-on shape as {@link filesReady}. */
+    aiReady: boolean;
+    /**
+     * The shared calls SFU (#170) an org's own calls Matrix stack depends on.
+     * Declared is enough here: unlike the others, `platform-diff.ts`'s
+     * `planSfu` never diffs the SFU against a live resource either (its own
+     * doc comment: "there is no cheap way to read the SFU VM's own state over
+     * SSH during planning"), so "applied" has no separate signal to check.
+     */
+    callsReady: boolean;
+    /** The platform's own sign-in (#168), which every org's own ZITADEL org lives inside. */
+    authReady: boolean;
+    /** The jobs scheduler (#173) is enabled, applied, and its admin token is held. */
+    jobsReady: boolean;
+    /**
+     * The ref of a platform key an applied service needs that is not held yet,
+     * `null` when it is held or when the service is not applied. A ref only,
+     * never a value. {@link orgPlatformReadinessFrom} only checks the refs it is
+     * given; `FoundryPlanApply` adds the ref of every service the host supplies
+     * its own port for, so those read as held.
+     */
+    missingKeys: {
+        files: string | null;
+        ai: string | null;
+        jobs: string | null;
+    };
+    /**
+     * True when the host wired no held-keys reader, so no key could be checked.
+     * A missing key is then reported as "no reader given" instead of "not held".
+     */
+    noKeyReader?: boolean;
+}
+/**
+ * What an org's plan reads when no platform is declared: nothing is ready, so
+ * every org step that depends on a platform service is blocked (#177). A host
+ * with no platform cannot have applied any shared service, and reading "no
+ * platform" as "all ready" planned steps that then failed against nothing.
+ * Tests that need a ready platform pass an explicit fixture.
+ */
+export declare const DEFAULT_ORG_PLATFORM_READINESS: OrgPlatformReadiness;
+/** The held-key refs an org step needs from the platform, one per service. */
+export declare const ORG_PLATFORM_KEY_REFS: {
+    readonly files: "files:platform:managementKey";
+    readonly ai: "ai:platform:managementKey";
+    readonly jobs: "jobs:scheduler:adminToken";
+};
+/** The one method of Archon's held keys this package reads. A value is returned to the caller and never logged, recorded or put in a plan. */
+export interface HeldKeyResolver {
+    resolve(ref: string): Promise<string | null | undefined>;
+}
+/**
+ * Which of {@link ORG_PLATFORM_KEY_REFS} `heldKeys` can resolve right now. A
+ * resolver that throws counts as "not held": the plan blocks, and the error
+ * (which could carry provider detail) goes nowhere.
+ */
+export declare function heldPlatformKeyRefs(heldKeys: HeldKeyResolver): Promise<Set<string>>;
+/**
+ * `FoundryPlanApply.computeFreshPlan`'s own precedent for turning a
+ * `PlatformStore`'s `get()`/`getServiceIds()` into what an org's plan needs.
+ * Unlike `agora.ts`'s `readAgoraHost`, there is no port to be absent here and
+ * nothing to throw: the platform is either declared (a caller checked that
+ * already) or this is never called.
+ */
+export declare function orgPlatformReadinessFrom(platform: DeclaredPlatform, platformRecordedIds: Readonly<Record<string, string>>, 
+/**
+ * The refs `heldKeys` resolves ({@link heldPlatformKeyRefs}), plus the ref
+ * of any service the host supplies its own port for. `undefined` skips the
+ * key check; `FoundryPlanApply` never passes it, because an absent
+ * `heldKeys` with no host port must block, not pass.
+ */
+heldRefs?: ReadonlySet<string>, 
+/** True when the host wired no held-keys reader ({@link OrgPlatformReadiness.noKeyReader}). */
+noKeyReader?: boolean): OrgPlatformReadiness;
+/**
+ * #177: {@link AgoraHostValues} derived from the same platform state, rather
+ * than requiring a bespoke host-supplied `AgoraHostPort` for values the
+ * platform already knows -- the `issuer`/`mailUpstream`/`filesUpstream`
+ * addresses `agora.ts`'s own doc comment named this issue as the source of.
+ * `mailProjectId`/`messagingProjectId` still have no live source (chat has no
+ * admin API yet, https://github.com/wtfalch/chat/issues/40, and mail's own
+ * OIDC directory does not surface a project id), so a platform-derived Agora
+ * stays blocked on those two until something records them -- this only stops
+ * pretending the other three are unavailable once the platform actually
+ * supplies them. `plan-apply.ts`'s `FoundryPlanApply` calls this only when no
+ * host-supplied `agora` port overrides it.
+ */
+export declare function agoraHostValuesFromPlatform(platform: DeclaredPlatform, platformRecordedIds: Readonly<Record<string, string>>): AgoraHostValues;

package/dist/plan/platform-org.js

@@ -0,0 +1,115 @@
+import { JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AUTH_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, platformMailMxHost, } from './platform-diff.js';
+import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+/**
+ * What an org's plan reads when no platform is declared: nothing is ready, so
+ * every org step that depends on a platform service is blocked (#177). A host
+ * with no platform cannot have applied any shared service, and reading "no
+ * platform" as "all ready" planned steps that then failed against nothing.
+ * Tests that need a ready platform pass an explicit fixture.
+ */
+export const DEFAULT_ORG_PLATFORM_READINESS = {
+    mailHost: null,
+    filesReady: false,
+    aiReady: false,
+    callsReady: false,
+    authReady: false,
+    jobsReady: false,
+    missingKeys: { files: null, ai: null, jobs: null },
+};
+/** The held-key refs an org step needs from the platform, one per service. */
+export const ORG_PLATFORM_KEY_REFS = {
+    files: FILES_MANAGEMENT_KEY_REF,
+    ai: PLATFORM_AI_MANAGEMENT_KEY_REF,
+    jobs: JOBS_ADMIN_TOKEN_REF,
+};
+/**
+ * Which of {@link ORG_PLATFORM_KEY_REFS} `heldKeys` can resolve right now. A
+ * resolver that throws counts as "not held": the plan blocks, and the error
+ * (which could carry provider detail) goes nowhere.
+ */
+export async function heldPlatformKeyRefs(heldKeys) {
+    const held = new Set();
+    for (const ref of Object.values(ORG_PLATFORM_KEY_REFS)) {
+        try {
+            if (await heldKeys.resolve(ref))
+                held.add(ref);
+        }
+        catch {
+            // not held
+        }
+    }
+    return held;
+}
+/** `AppliedState.serviceIds`' own `system:kind:key` shape, restated for the platform's own recorded ids (`platform-diff.ts`'s `resourceKey`, private there). */
+function coolifyAppApplied(platformRecordedIds, key) {
+    return Boolean(platformRecordedIds[`coolify:app:${key}`]);
+}
+/**
+ * `FoundryPlanApply.computeFreshPlan`'s own precedent for turning a
+ * `PlatformStore`'s `get()`/`getServiceIds()` into what an org's plan needs.
+ * Unlike `agora.ts`'s `readAgoraHost`, there is no port to be absent here and
+ * nothing to throw: the platform is either declared (a caller checked that
+ * already) or this is never called.
+ */
+export function orgPlatformReadinessFrom(platform, platformRecordedIds, 
+/**
+ * The refs `heldKeys` resolves ({@link heldPlatformKeyRefs}), plus the ref
+ * of any service the host supplies its own port for. `undefined` skips the
+ * key check; `FoundryPlanApply` never passes it, because an absent
+ * `heldKeys` with no host port must block, not pass.
+ */
+heldRefs, 
+/** True when the host wired no held-keys reader ({@link OrgPlatformReadiness.noKeyReader}). */
+noKeyReader = false) {
+    const mailApplied = platform.mail.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_MAIL_KEY);
+    const filesApplied = platform.files.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_FILES_KEY);
+    const aiApplied = platform.ai.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_AI_KEY);
+    const jobsApplied = platform.jobs.enabled && Boolean(platformRecordedIds[`coolify:jobs:${JOBS_SCHEDULER_KEY}`]);
+    const missing = (applied, ref) => applied && heldRefs !== undefined && !heldRefs.has(ref) ? ref : null;
+    const missingKeys = {
+        files: missing(filesApplied, ORG_PLATFORM_KEY_REFS.files),
+        ai: missing(aiApplied, ORG_PLATFORM_KEY_REFS.ai),
+        jobs: missing(jobsApplied, ORG_PLATFORM_KEY_REFS.jobs),
+    };
+    return {
+        mailHost: mailApplied
+            ? { apex: platform.apex, mailHost: platformMailMxHost(platform.apex) }
+            : null,
+        filesReady: filesApplied && missingKeys.files === null,
+        aiReady: aiApplied && missingKeys.ai === null,
+        callsReady: platform.sfu.enabled,
+        authReady: platform.auth.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_AUTH_KEY),
+        jobsReady: jobsApplied && missingKeys.jobs === null,
+        missingKeys,
+        ...(noKeyReader ? { noKeyReader } : {}),
+    };
+}
+/**
+ * #177: {@link AgoraHostValues} derived from the same platform state, rather
+ * than requiring a bespoke host-supplied `AgoraHostPort` for values the
+ * platform already knows -- the `issuer`/`mailUpstream`/`filesUpstream`
+ * addresses `agora.ts`'s own doc comment named this issue as the source of.
+ * `mailProjectId`/`messagingProjectId` still have no live source (chat has no
+ * admin API yet, https://github.com/wtfalch/chat/issues/40, and mail's own
+ * OIDC directory does not surface a project id), so a platform-derived Agora
+ * stays blocked on those two until something records them -- this only stops
+ * pretending the other three are unavailable once the platform actually
+ * supplies them. `plan-apply.ts`'s `FoundryPlanApply` calls this only when no
+ * host-supplied `agora` port overrides it.
+ */
+export function agoraHostValuesFromPlatform(platform, platformRecordedIds) {
+    const authReady = platform.auth.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_AUTH_KEY);
+    const mailReady = platform.mail.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_MAIL_KEY);
+    const filesReady = platform.files.enabled && coolifyAppApplied(platformRecordedIds, PLATFORM_FILES_KEY);
+    return {
+        issuer: authReady ? `https://${platform.auth.hostname}` : null,
+        mailProjectId: null,
+        messagingProjectId: null,
+        mailUpstream: mailReady
+            ? (platformRecordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY] ?? null)
+            : null,
+        filesUpstream: filesReady
+            ? (platformRecordedIds[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY] ?? null)
+            : null,
+    };
+}