@wtfalch/foundry 0.59.0 → 0.61.0

package/dist/apps/cloudflare.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The Cloudflare calls `deployWorkerApp` and `removeWorkerApp` make in a company's own account:
+ * the methods of `@wtfalch/providers/cloudflare`'s `CloudflareClient` they use, repeated
+ * structurally, so `new CloudflareClient(token, accountId)` from providers 0.15.0 is passed
+ * straight in and a test passes a fake. Every id here is one the account itself holds.
+ *
+ * Every list call returns every page (providers 0.15.0 walks `result_info`).
+ *
+ * A failed call throws an error that carries the HTTP `status` (providers' `CloudflareApiError`);
+ * foundry reads only the status, never the message, so nothing the API echoes reaches a result.
+ */
+export interface AppsCloudflare {
+    /** The zone of the account whose name is the longest suffix of `domain`, or `undefined`. */
+    findZoneByApex(domain: string): Promise<{
+        id: string;
+        name: string;
+        status: string;
+    } | undefined>;
+    listDnsRecords(zoneId: string, opts?: {
+        type?: string;
+        name?: string;
+    }): Promise<{
+        id: string;
+        type: string;
+        content: string;
+        name: string;
+    }[]>;
+    createDnsRecord(zoneId: string, record: {
+        type: string;
+        name: string;
+        content: string;
+        proxied?: boolean;
+    }): Promise<{
+        id: string;
+    }>;
+    deleteDnsRecord(zoneId: string, recordId: string): Promise<void>;
+    listWorkerScripts(): Promise<{
+        id: string;
+        migrationTag?: string;
+    }[]>;
+    uploadWorkerModule(name: string, upload: {
+        module: Uint8Array;
+        mainModule?: string;
+        metadata: Record<string, unknown>;
+    }): Promise<void>;
+    /** A no-op when the script is gone. Removes its secrets and Durable Object namespaces. */
+    deleteWorkerScript(name: string): Promise<void>;
+    listWorkerSecrets(name: string): Promise<{
+        name: string;
+        type: string;
+    }[]>;
+    putWorkerSecret(name: string, secretName: string, text: string): Promise<void>;
+    deleteWorkerSecret(name: string, secretName: string): Promise<void>;
+    /** The account's `<name>.workers.dev` name, or `undefined` when it has none. */
+    getWorkersSubdomain(): Promise<string | undefined>;
+    setWorkerScriptSubdomain(name: string, enabled: boolean): Promise<void>;
+    listWorkerRoutes(zoneId: string): Promise<{
+        id: string;
+        pattern: string;
+        script?: string;
+    }[]>;
+    createWorkerRoute(zoneId: string, route: {
+        pattern: string;
+        script: string;
+    }): Promise<{
+        id: string;
+    }>;
+    deleteWorkerRoute(zoneId: string, routeId: string): Promise<void>;
+    listDurableObjectNamespaces(): Promise<{
+        id: string;
+        className: string;
+        script: string;
+    }[]>;
+    listContainerApplications(): Promise<{
+        id: string;
+        name: string;
+        image: string;
+        instanceType: string;
+        maxInstances: number;
+        namespaceId: string;
+    }[]>;
+    createContainerApplication(input: {
+        name: string;
+        image: string;
+        instanceType: string;
+        maxInstances: number;
+        namespaceId: string;
+    }): Promise<{
+        id: string;
+    }>;
+    updateContainerApplication(id: string, input: {
+        maxInstances: number;
+    }): Promise<void>;
+    rolloutContainerApplication(id: string, input: {
+        image: string;
+        instanceType: string;
+        description?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    getContainerRollout(applicationId: string, rolloutId: string): Promise<{
+        status: string;
+    }>;
+    deleteContainerApplication(id: string): Promise<void>;
+    listHyperdriveConfigs(): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    createHyperdriveConfig(name: string, origin: HyperdriveConnection): Promise<{
+        id: string;
+    }>;
+    updateHyperdriveConfig(id: string, name: string, origin: HyperdriveConnection): Promise<{
+        id: string;
+    }>;
+    deleteHyperdriveConfig(id: string): Promise<void>;
+    listAccessApps(): Promise<{
+        id: string;
+        name: string;
+        domain: string;
+        type: string;
+    }[]>;
+    createAccessApp(app: {
+        name: string;
+        domain: string;
+        type: string;
+        session_duration?: string;
+    }): Promise<{
+        id: string;
+    }>;
+    deleteAccessApp(appId: string): Promise<void>;
+    listAccessPolicies(appId: string): Promise<{
+        id: string;
+        name: string;
+        decision: string;
+        include: unknown[];
+    }[]>;
+    createAccessPolicy(appId: string, policy: {
+        name: string;
+        decision: string;
+        include: unknown[];
+        precedence?: number;
+    }): Promise<{
+        id: string;
+    }>;
+    updateAccessPolicy(appId: string, policyId: string, policy: {
+        name: string;
+        decision: string;
+        include: unknown[];
+        precedence?: number;
+    }): Promise<{
+        id: string;
+    }>;
+    /** A no-op when the policy is gone. */
+    deleteAccessPolicy(appId: string, policyId: string): Promise<void>;
+}
+/** A Postgres origin for Hyperdrive, as providers sends it. */
+export interface HyperdriveConnection {
+    host: string;
+    port: number;
+    database: string;
+    user: string;
+    password: string;
+    scheme?: 'postgres' | 'postgresql';
+}
+/**
+ * The permissions the company's API token needs, for Boule's Connections page. Names as
+ * Cloudflare's token page shows them.
+ */
+export declare const APPS_CLOUDFLARE_TOKEN_PERMISSIONS: readonly {
+    scope: 'Account' | 'Zone';
+    name: string;
+    why: string;
+}[];

package/dist/apps/cloudflare.js

@@ -0,0 +1,17 @@
+/**
+ * The permissions the company's API token needs, for Boule's Connections page. Names as
+ * Cloudflare's token page shows them.
+ */
+export const APPS_CLOUDFLARE_TOKEN_PERMISSIONS = [
+    { scope: 'Account', name: 'Workers Scripts: Edit', why: 'upload the app and its secrets' },
+    { scope: 'Account', name: 'Containers: Edit', why: 'run the app’s containers' },
+    { scope: 'Account', name: 'Hyperdrive: Edit', why: 'connect the app to its database' },
+    {
+        scope: 'Account',
+        name: 'Access: Apps and Policies: Edit',
+        why: 'keep the workspace for the people you choose',
+    },
+    { scope: 'Zone', name: 'Zone: Read', why: 'find the domain the app is served on' },
+    { scope: 'Zone', name: 'DNS: Edit', why: 'point the address at the app' },
+    { scope: 'Zone', name: 'Workers Routes: Edit', why: 'send the address to the app' },
+];

package/dist/apps/deploy.d.ts

@@ -0,0 +1,116 @@
+import { type HostingEntry } from '../org.js';
+import type { AppsCloudflare } from './cloudflare.js';
+/**
+ * One Worker app in a company's own Cloudflare account (campaign 2026-10-20, FM3). Boule calls
+ * this in-process with the company's own token; there is no org plan and no recorded state: every
+ * run reads the account and makes it match, so a rerun converges and a run that failed halfway is
+ * finished by the next one. The script is `<key>` (live) or `<key>-work` (workspace).
+ *
+ * Order, so the app is never reachable before it can serve and a workspace is never reachable
+ * without its gate: checks that need no call -> the address (zone, or the account's workers.dev
+ * name) and what already sits on it -> the build (fetched, sha256 checked) -> the gate (Access) ->
+ * the database link (Hyperdrive) -> secrets of a script already there -> upload -> on a company
+ * zone, workers.dev off at once -> secrets of a new script -> containers -> the address (DNS
+ * record and route, or the workers.dev switch on).
+ *
+ * A failure returns `{ ok: false, step, message }` in plain words. No message holds the token, a
+ * secret value, the database address or anything Cloudflare answered. A failure after which the
+ * app may be reachable without its gate also carries `reachableWithoutGate: true`, so a caller
+ * acts on the field and never on the words.
+ */
+export type AppCopy = 'live' | 'workspace';
+export interface DeployWorkerAppInput {
+    /** The company's own, from Boule's Cloudflare connection. */
+    account: {
+        accountId: string;
+        token: string;
+    };
+    /**
+     * `host` is the full hostname. A workspace on companyincluded.app is served on the account's
+     * workers.dev name. `repo` is the app's own GitHub repository (`owner/name`): the build must be
+     * a file of one of its releases.
+     */
+    app: {
+        key: string;
+        host: string;
+        copy: AppCopy;
+        repo: string;
+    };
+    /** The company's GitHub token (Boule's GitHub connection), for a private repository's release files. */
+    github?: {
+        token: string;
+    } | null;
+    /** From `applyModules` and the build's `build.json`: `workerApp` must hold a build. */
+    entry: HostingEntry;
+    /** Postgres for Hyperdrive, one per copy. */
+    database?: {
+        url: string;
+    } | null;
+    /** `AUTH_*` and `MCP_*` env (and `KEYS_URL`), from Boule's sign-in port. Plain vars, never secrets. */
+    signIn?: Record<string, string> | null;
+    /** Secret values Boule holds, by name. */
+    secrets: Record<string, string>;
+    /** Who may open the copy, and the paths machines call without signing in. Required for a workspace. */
+    gate?: {
+        emails: string[];
+        machinePaths: string[];
+    } | null;
+}
+export interface RemoveWorkerAppInput {
+    account: {
+        accountId: string;
+        token: string;
+    };
+    app: {
+        key: string;
+        host: string;
+        copy: AppCopy;
+    };
+}
+export interface AppsDeps {
+    /** Builds the client for the company's account: `({ accountId, token }) => new CloudflareClient(token, accountId)`. */
+    cloudflare: (account: {
+        accountId: string;
+        token: string;
+    }) => AppsCloudflare;
+    /** Used to fetch the build (from GitHub) when `fetchArtifact` is not given. */
+    fetch?: typeof fetch;
+    /** Fetches the built module instead of foundry. Its address is checked first and its sha256 after. */
+    fetchArtifact?: (url: string) => Promise<Uint8Array>;
+    /** Test hooks. */
+    timeoutMs?: number;
+    rolloutPollMs?: number;
+    rolloutTimeoutMs?: number;
+}
+export type AppsResult = {
+    ok: true;
+    steps: string[];
+    url: string;
+} | AppsFailure;
+/**
+ * `reachableWithoutGate` is set only when the code is uploaded but its workers.dev address would
+ * not turn off: the caller should run `removeWorkerApp` at once, then deploy again.
+ */
+export type AppsFailure = {
+    ok: false;
+    step: string;
+    message: string;
+    steps: string[];
+    reachableWithoutGate?: true;
+};
+/** The paths an MCP client reaches without signing in at Access: the MCP endpoint and the OAuth discovery documents. */
+export declare function mcpMachinePaths(mcpPath: string): string[];
+export declare const appScriptName: (key: string, copy: AppCopy) => string;
+export declare const appHyperdriveName: (script: string) => string;
+/**
+ * Deploys one Worker app copy into the company's own account and returns what it did, or the step
+ * that stopped it in plain words. Never throws.
+ */
+export declare function deployWorkerApp(input: DeployWorkerAppInput, deps: AppsDeps): Promise<AppsResult>;
+/**
+ * Removes one copy: its workers.dev address first, then its route and DNS record, its containers,
+ * the script with its secrets, its database link, and its Access apps last, so the gate stays
+ * until nothing is left behind it. A piece already gone is skipped, so a rerun converges. Never
+ * throws.
+ */
+export declare function removeWorkerApp(input: RemoveWorkerAppInput, deps: AppsDeps): Promise<AppsResult>;