@every-app/sdk 0.1.14 → 0.3.0-rc.1

package/dist/cloudflare/worker.js

@@ -0,0 +1,738 @@
+import { createHash, createHmac } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parseEnv } from "node:util";
+import { DEV_ISSUER, DEV_PUBLIC_KEY_PEM } from "../dev/keypair.js";
+import { sentinelDeployTarget } from "./sentinel.js";
+/** The names of the manifest's `secrets`, whichever form each took. */
+function manifestSecretNames(manifest) {
+    return (manifest.secrets ?? []).map((entry) => typeof entry === "string" ? entry : entry.name);
+}
+/** The ids of the manifest's `providers`, whichever form each took. */
+function manifestProviderIds(manifest) {
+    return (manifest.providers ?? []).map((entry) => typeof entry === "string" ? entry : entry.id);
+}
+/**
+ * The gateway secrets holding the keys of the AI providers and capabilities
+ * an app may ask for, with the settings a provider needs besides its key
+ * (Workers AI's account). With no gateway in development, the SDK reaches
+ * them with the developer's own values under the same names. A copy of the
+ * tables in ../internal, which the Worker loads: the Vite plugin hides
+ * whatever cloudflare.config.ts imports from the Worker. A test keeps them
+ * in step.
+ */
+const DEV_GATEWAY_KEYS = {
+    providers: {
+        openai: ["OPENAI_API_KEY"],
+        openrouter: ["OPENROUTER_API_KEY"],
+        "workers-ai": ["WORKERS_AI_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"],
+    },
+    capabilities: {
+        dataforseo: ["DATAFORSEO_API_KEY"],
+        context: ["CONTEXT_API_KEY"],
+        // The sender, and the developer's own Email Sending account: set all
+        // but the name and sendEmail() really sends; otherwise it prints.
+        // Resend's key and EMAIL_PROVIDER pick the provider integrationStatus()
+        // names, as the gateway would.
+        // TODO(integration): the last two added by the email-providers lane
+        // (this file is outside its ownership list).
+        email: [
+            "EMAIL_FROM",
+            "EMAIL_FROM_NAME",
+            "EMAIL_REST_API_TOKEN",
+            "CLOUDFLARE_ACCOUNT_ID",
+            "RESEND_API_KEY",
+            "EMAIL_PROVIDER",
+        ],
+        // The organization's members: nothing to set; listMembers() answers
+        // from the dev identity.
+        members: [],
+        // OAuth clients: the id, the secret, and the instance a provider with
+        // no fixed host is on.
+        linkedin: ["LINKEDIN_CLIENT_ID", "LINKEDIN_CLIENT_SECRET"],
+        facebook: ["FACEBOOK_APP_ID", "FACEBOOK_APP_SECRET"],
+        instagram: ["INSTAGRAM_APP_ID", "INSTAGRAM_APP_SECRET"],
+        threads: ["THREADS_APP_ID", "THREADS_APP_SECRET"],
+        youtube: ["YOUTUBE_CLIENT_ID", "YOUTUBE_CLIENT_SECRET"],
+        tiktok: ["TIKTOK_CLIENT_ID", "TIKTOK_CLIENT_SECRET"],
+        "tiktok-business": [
+            "TIKTOK_BUSINESS_CLIENT_ID",
+            "TIKTOK_BUSINESS_CLIENT_SECRET",
+        ],
+        reddit: ["REDDIT_CLIENT_ID", "REDDIT_CLIENT_SECRET"],
+        pinterest: ["PINTEREST_CLIENT_ID", "PINTEREST_CLIENT_SECRET"],
+        discord: ["DISCORD_CLIENT_ID", "DISCORD_CLIENT_SECRET"],
+        slack: ["SLACK_CLIENT_ID", "SLACK_CLIENT_SECRET"],
+        mastodon: ["MASTODON_CLIENT_ID", "MASTODON_CLIENT_SECRET", "MASTODON_URL"],
+        kick: ["KICK_CLIENT_ID", "KICK_CLIENT_SECRET"],
+        twitch: ["TWITCH_CLIENT_ID", "TWITCH_CLIENT_SECRET"],
+        tumblr: ["TUMBLR_CLIENT_ID", "TUMBLR_CLIENT_SECRET"],
+        dribbble: ["DRIBBBLE_CLIENT_ID", "DRIBBBLE_CLIENT_SECRET"],
+        "google-workspace": [
+            "GOOGLE_WORKSPACE_CLIENT_ID",
+            "GOOGLE_WORKSPACE_CLIENT_SECRET",
+        ],
+        "microsoft-365": ["MICROSOFT_365_CLIENT_ID", "MICROSOFT_365_CLIENT_SECRET"],
+    },
+};
+/**
+ * Observability every Every App Worker ships with: logs (with invocation
+ * logs), sampled traces and Workers Issues, with query strings redacted so
+ * tokens and invitation ids in URLs stay out of logs.
+ */
+export const EVERYAPP_OBSERVABILITY = Object.freeze({
+    enabled: true,
+    headSamplingRate: 1,
+    redactQueryString: true,
+    logs: Object.freeze({
+        enabled: true,
+        invocationLogs: true,
+        persist: true,
+        headSamplingRate: 1,
+    }),
+    traces: Object.freeze({
+        enabled: true,
+        persist: true,
+        headSamplingRate: 0.1,
+    }),
+    issues: Object.freeze({ enabled: true }),
+});
+const DEFAULT_COMPATIBILITY_DATE = "2026-06-01";
+/** Set by `everyapp deploy` around the production build it installs. */
+const BUILD_ENV = "EVERYAPP_BUILD";
+/** Names the deploy sets itself (as `everyapp secret set` refuses). */
+const RESERVED_SECRET_NAME = /^(GATEWAY_URL|CF_VERSION_METADATA|EVERYAPP_\w*|EVERY_APP_\w*|APP__\w*)$/i;
+const GATEWAY_WORKER_NAME = "every-app-gateway";
+const GATEWAY_ENTRYPOINT = "AppGateway";
+/**
+ * The manifest's `capabilities` as the SDK's local-dev twin of the gateway
+ * reads them: with no gateway to hold an OAuth client's calls to the scope
+ * sets the app declares, `integrationFetch()` holds them to these.
+ */
+function devCapabilities(manifest) {
+    return { type: "text", value: JSON.stringify(manifest.capabilities ?? {}) };
+}
+/**
+ * The binding the dev Worker gets the specs of providers registered on a
+ * gateway in (`DEV_PROVIDERS_ENV` in ../internal/devProviders.ts; a copy,
+ * kept in step by a test, for the reason {@link DEV_GATEWAY_KEYS} is one).
+ */
+const DEV_PROVIDERS_ENV = "EVERYAPP_DEV_PROVIDERS";
+/**
+ * The specs `everyapp provider add` (in an app directory) and `everyapp
+ * provider show <id> --save` wrote under the app, in name order; none
+ * without the directory. integrationFetch()'s dev fallback reaches a
+ * provider outside the catalog from them, with the developer's own key.
+ */
+function devProviderFiles(root) {
+    const dir = path.join(root ?? process.cwd(), ".everyapp", "providers");
+    let names;
+    try {
+        names = fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith(".json"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    return names.map((name) => {
+        const text = fs.readFileSync(path.join(dir, name), "utf8");
+        let spec;
+        try {
+            spec = JSON.parse(text);
+        }
+        catch {
+            spec = text;
+        }
+        return { file: `.everyapp/providers/${name}`, spec };
+    });
+}
+/** EVERYAPP_DEV_PROVIDERS, when the app has any spec files. */
+function addDevProviders(env, root) {
+    const files = devProviderFiles(root);
+    if (files.length === 0)
+        return;
+    env[DEV_PROVIDERS_ENV] = { type: "text", value: JSON.stringify(files) };
+}
+/**
+ * The Gateway settings the spec files name for the capabilities the
+ * manifest lists outside {@link DEV_GATEWAY_KEYS} (a registered provider's
+ * key, a Basic username held as a setting, its host setting), read
+ * loosely: the SDK parses the spec when the app calls the provider.
+ */
+function devProviderKeys(manifest, root) {
+    const listed = Object.keys(manifest.capabilities ?? {}).filter((id) => !Object.hasOwn(DEV_GATEWAY_KEYS.capabilities, id));
+    if (listed.length === 0)
+        return [];
+    const record = (value) => value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+    const names = [];
+    for (const { file, spec } of devProviderFiles(root)) {
+        const fields = record(spec);
+        const id = typeof fields?.["id"] === "string"
+            ? fields["id"]
+            : file
+                .split("/")
+                .at(-1)
+                .replace(/\.json$/, "");
+        if (!fields || !listed.includes(id))
+            continue;
+        const auth = record(fields["auth"]);
+        for (const name of [
+            auth?.["secret"],
+            record(auth?.["user"])?.["secret"],
+            fields["hostSetting"],
+        ]) {
+            if (typeof name === "string" && /^[A-Z][A-Z0-9_]*$/.test(name)) {
+                names.push(name);
+            }
+        }
+    }
+    return names;
+}
+/** Cloudflare's limit on a Workflow's name. */
+const MAX_WORKFLOW_NAME_LENGTH = 64;
+/** Cloudflare's limit on a Worker's name. */
+const MAX_WORKER_NAME_LENGTH = 63;
+/**
+ * Where a developer puts a local Postgres URL for a Hyperdrive binding
+ * (`.dev.vars` or `.env`), the variable wrangler reads for the same.
+ */
+const LOCAL_HYPERDRIVE_PREFIX = "CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_";
+/**
+ * Build the Worker definition for an Every App app from its manifest.
+ *
+ * - `development` (cf dev) and no mode (cf API commands, `cf workers types`):
+ *   EVERYAPP_DEV is on, the identity keys and issuer are the well-known dev
+ *   ones (`@every-app/sdk/dev`) as plain text, so nothing needs writing to
+ *   `.dev.vars`, and each D1 database gets a fixed local id (see
+ *   {@link localD1Id}) that `cf d1 … --local` can address.
+ * - `production`: tenant-neutral. Everything install-specific (the Worker
+ *   name, organization, gateway URL, identity keys, resource names and ids)
+ *   is a placeholder from {@link sentinelDeployTarget}, which the installer
+ *   rewrites (`everyapp deploy`, or a hosted gateway's deployer), so every
+ *   build of an app is the same. Only with EVERYAPP_BUILD=1, which
+ *   `everyapp deploy` sets: a bare `cf deploy` would upload the
+ *   placeholders.
+ */
+export function everyAppWorker(options) {
+    const { manifest } = options;
+    const { deploy, name } = appWorkerName(options, "everyAppWorker");
+    const env = {
+        EVERYAPP_APP_ID: { type: "text", value: manifest.id },
+        CF_VERSION_METADATA: { type: "version-metadata" },
+    };
+    if (deploy) {
+        // The gateway mints every identity for the Worker's name (`aud`).
+        env["EVERYAPP_AUDIENCE"] = { type: "text", value: name };
+        env["EVERYAPP_IDENTITY_PUBLIC_KEYS"] = {
+            type: "text",
+            value: JSON.stringify(deploy.identityPublicKeys),
+        };
+        env["EVERYAPP_IDENTITY_ISSUER"] = {
+            type: "text",
+            value: deploy.gatewayUrl,
+        };
+        env["EVERY_APP_GATEWAY"] = gatewayBinding(deploy, manifest.id, name);
+        // Sent by the deploy pipeline through `cf deploy --secrets-file`.
+        env["GATEWAY_URL"] = { type: "secret" };
+        env["EVERY_APP_ORG_ID"] = { type: "secret" };
+    }
+    else {
+        env["EVERYAPP_DEV"] = { type: "text", value: "1" };
+        env["EVERYAPP_DEV_CAPABILITIES"] = devCapabilities(manifest);
+        env["EVERYAPP_IDENTITY_PUBLIC_KEYS"] = {
+            type: "text",
+            value: JSON.stringify([DEV_PUBLIC_KEY_PEM]),
+        };
+        env["EVERYAPP_IDENTITY_ISSUER"] = { type: "text", value: DEV_ISSUER };
+        addDevProviders(env, options.root);
+    }
+    Object.assign(env, storageBindings(manifest, name, deploy));
+    addDatabaseBindings(env, options, name, undefined, deploy);
+    // The app binds every class, a helper Worker's in that Worker, and
+    // exports only its own.
+    const { bindings, exports } = classBindings(manifest, name, undefined, env);
+    Object.assign(env, bindings);
+    for (const helper of manifest.workers ?? []) {
+        if (!helper.binding)
+            continue;
+        if (env[helper.binding]) {
+            throw new Error(`workers: ${helper.name}'s binding ${helper.binding} reuses a binding name the Worker already has.`);
+        }
+        env[helper.binding] = {
+            type: "worker",
+            worker: helperWorkerName(name, helper.name),
+        };
+    }
+    addSecrets(env, options, deploy);
+    const triggers = cronTriggers(options.crons);
+    const compatibilityDate = manifest.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE;
+    // cf types a Durable Object namespace with its class only when the binding
+    // names the defining Worker by a definition whose module it can read, so
+    // the classes this Worker defines name it that way; cf resolves the
+    // reference to the Worker's name. A path entrypoint gives cf no module.
+    const { entrypoint } = options;
+    if (typeof entrypoint === "object") {
+        const self = {
+            name,
+            compatibilityDate,
+            entrypoint,
+        };
+        for (const durableObject of manifest.resources?.durableObjects ?? []) {
+            if (durableObject.worker !== undefined)
+                continue;
+            env[durableObject.name] = {
+                type: "durable-object",
+                worker: self,
+                exportName: durableObject.className,
+            };
+        }
+    }
+    return {
+        name,
+        entrypoint,
+        compatibilityDate,
+        compatibilityFlags: compatibilityFlags(options.compatibilityFlags),
+        workersDev: false,
+        previewUrls: false,
+        ...(triggers.length ? { triggers } : {}),
+        ...runtimeSettings(manifest, manifest.limits, deploy),
+        observability: observability(),
+        env: env,
+        exports: exports,
+    };
+}
+/**
+ * Build the definition of one of the app's helper Workers (the manifest's
+ * `workers`), e.g. one that runs a memory-hungry job away from the app's
+ * Worker. It is named `<app worker>--<worker>`, is private like the app, and
+ * binds the app's D1 databases, KV namespaces and R2 buckets, the classes it defines, and
+ * the gateway (with the app's identity, for capabilities). Only the app's
+ * Worker reaches it. Pass it to the Vite plugin:
+ *
+ *   cloudflare({
+ *     auxiliaryWorkers: [
+ *       { config: everyAppAuxiliaryWorker({ manifest, worker: "audit", entrypoint: "./src/audit.ts", ctx: { mode } }) },
+ *     ],
+ *   })
+ */
+export function everyAppAuxiliaryWorker(options) {
+    const { manifest, worker } = options;
+    const helper = manifest.workers?.find((entry) => entry.name === worker);
+    if (!helper) {
+        throw new Error(`everyapp.config.ts declares no helper Worker "${worker}" in workers.`);
+    }
+    const { deploy, name: appWorker } = appWorkerName(options, "everyAppAuxiliaryWorker");
+    const name = helperWorkerName(appWorker, worker);
+    const env = {
+        EVERYAPP_APP_ID: { type: "text", value: manifest.id },
+        ...storageBindings(manifest, appWorker, deploy),
+    };
+    if (deploy) {
+        // The app's identity: the gateway treats its helper Workers as the app.
+        env["EVERY_APP_GATEWAY"] = gatewayBinding(deploy, manifest.id, appWorker);
+        // Sent by the deploy pipeline through `cf deploy --secrets-file`, like
+        // the app's Worker: a helper's gateway calls name the organization too.
+        env["GATEWAY_URL"] = { type: "secret" };
+        env["EVERY_APP_ORG_ID"] = { type: "secret" };
+    }
+    else {
+        env["EVERYAPP_DEV"] = { type: "text", value: "1" };
+        env["EVERYAPP_DEV_CAPABILITIES"] = devCapabilities(manifest);
+        addDevProviders(env, options.root);
+    }
+    addDatabaseBindings(env, options, appWorker, worker, deploy);
+    const { bindings, exports } = classBindings(manifest, appWorker, worker, env);
+    Object.assign(env, bindings);
+    addSecrets(env, options, deploy);
+    const triggers = cronTriggers(options.crons);
+    return {
+        name,
+        entrypoint: options.entrypoint,
+        compatibilityDate: manifest.compatibilityDate ?? DEFAULT_COMPATIBILITY_DATE,
+        compatibilityFlags: compatibilityFlags(options.compatibilityFlags),
+        workersDev: false,
+        previewUrls: false,
+        ...(triggers.length ? { triggers } : {}),
+        ...runtimeSettings(manifest, helper.limits, deploy),
+        observability: observability(),
+        env,
+        exports,
+    };
+}
+/**
+ * A helper Worker's name: `<app worker>--<name>`, within Cloudflare's
+ * limit. New app ids can't contain `--`, so it is never another app's
+ * Worker name.
+ */
+export function helperWorkerName(appWorker, helper) {
+    const name = `${appWorker}--${helper}`;
+    if (name.length > MAX_WORKER_NAME_LENGTH) {
+        throw new Error(`Helper Worker ${name} is longer than Cloudflare's ${MAX_WORKER_NAME_LENGTH} characters; shorten its name in everyapp.config.ts.`);
+    }
+    return name;
+}
+/** The placeholder target (in production) and the app Worker's name. */
+function appWorkerName(options, builder) {
+    const { manifest, ctx } = options;
+    assertAppId(manifest.id);
+    let deploy;
+    if (ctx.mode === "production") {
+        if (process.env[BUILD_ENV] !== "1") {
+            throw new Error(`Every App Workers are built for production only by \`everyapp deploy\` (\`pnpm run deploy\`), which sets ${BUILD_ENV}=1 and installs the build: ` +
+                "a bare `cf build` or `cf deploy` would ship a Worker whose name, identity keys, gateway binding and resources are placeholders. " +
+                "For a local build, run Vite in development mode (`vite build --mode development`).");
+        }
+        deploy = sentinelDeployTarget(manifest);
+    }
+    else if (ctx.mode !== undefined && ctx.mode !== "development") {
+        throw new Error(`${builder}() builds in the "development" or "production" mode, not "${ctx.mode}".`);
+    }
+    const name = deploy?.workerName ?? workerNameFor(manifest.id);
+    if (name === GATEWAY_WORKER_NAME) {
+        throw new Error(`App id "${manifest.id}" is reserved: its Worker would be the gateway's own (${GATEWAY_WORKER_NAME}).`);
+    }
+    return { deploy, name };
+}
+function gatewayBinding(deploy, appId, appWorker) {
+    return {
+        type: "worker",
+        worker: GATEWAY_WORKER_NAME,
+        exportName: GATEWAY_ENTRYPOINT,
+        props: {
+            organizationId: deploy.organizationId,
+            appId,
+            workerName: appWorker,
+        },
+    };
+}
+/**
+ * The app's D1 databases, KV namespaces and R2 buckets, which all its
+ * Workers share.
+ */
+function storageBindings(manifest, appWorker, deploy) {
+    const env = {};
+    for (const binding of manifest.resources?.d1 ?? []) {
+        if (deploy) {
+            const d1 = provisioned(deploy.resources.d1, binding);
+            env[binding] = { type: "d1", name: d1.name, id: d1.id };
+        }
+        else {
+            env[binding] = {
+                type: "d1",
+                name: resourceNameFor(appWorker, binding),
+                id: localD1Id(appWorker, binding),
+            };
+        }
+    }
+    for (const binding of manifest.resources?.kv ?? []) {
+        if (deploy) {
+            env[binding] = {
+                type: "kv",
+                id: provisioned(deploy.resources.kv, binding).id,
+            };
+        }
+        else if (manifest.workers?.length) {
+            // The Vite plugin's own default for the app's Worker, named so that
+            // its helpers share the namespace in dev, as deployed ones do.
+            env[binding] = { type: "kv", id: `${binding}-${appWorker}` };
+        }
+        else {
+            env[binding] = { type: "kv" };
+        }
+    }
+    // Deployed, the names the gateway assigns at registration (placeholders
+    // until installed); in dev its rule, so a local bucket is named like a
+    // deployed one.
+    for (const binding of manifest.resources?.r2 ?? []) {
+        if (env[binding]) {
+            throw new Error(`r2: ${binding} reuses a binding name the Worker already has.`);
+        }
+        if (deploy) {
+            env[binding] = {
+                type: "r2",
+                name: provisioned(deploy.resources.r2, binding).name,
+            };
+        }
+        else {
+            env[binding] = { type: "r2", name: bucketNameFor(appWorker, binding) };
+        }
+    }
+    return env;
+}
+/**
+ * DATABASE_PROVIDER and the Hyperdrive configs one of the app's Workers
+ * binds: each config every Worker shares, and those a helper (`forWorker`)
+ * alone takes. Deployed, each is the config the deploy provisioned; in
+ * development, a local Postgres URL set as
+ * CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<binding>, or nothing.
+ */
+function addDatabaseBindings(env, options, appWorker, forWorker, deploy) {
+    const { manifest } = options;
+    if (manifest.database) {
+        env["DATABASE_PROVIDER"] = {
+            type: "text",
+            value: manifest.database.provider,
+        };
+    }
+    const configs = (manifest.resources?.hyperdrive ?? []).filter((config) => config.worker === undefined || config.worker === forWorker);
+    if (configs.length === 0)
+        return;
+    const local = deploy
+        ? {}
+        : localEnv(options.root ?? process.cwd(), options.ctx.mode ?? "development");
+    for (const config of configs) {
+        if (env[config.name]) {
+            throw new Error(`hyperdrive: ${config.name} reuses a binding name the Worker already has.`);
+        }
+        if (deploy) {
+            env[config.name] = {
+                type: "hyperdrive",
+                id: provisioned(deploy.resources.hyperdrive, config.name).id,
+            };
+            continue;
+        }
+        const connectionString = local[`${LOCAL_HYPERDRIVE_PREFIX}${config.name}`];
+        if (connectionString) {
+            env[config.name] = {
+                type: "hyperdrive",
+                id: localD1Id(appWorker, config.name),
+                dev: { connectionString },
+            };
+        }
+    }
+}
+/**
+ * The placement and limits of one of the app's Workers: deployed, it runs
+ * near the database's region; its CPU limit is the manifest's.
+ */
+function runtimeSettings(manifest, limits, deploy) {
+    const region = manifest.database?.region;
+    return {
+        ...(deploy && region ? { placement: { region } } : {}),
+        ...(limits?.cpuMs !== undefined ? { limits: { cpuMs: limits.cpuMs } } : {}),
+    };
+}
+/**
+ * Durable Object and Workflow bindings, and the classes to export, for one
+ * of the app's Workers: the app's own (`forWorker` undefined) binds every
+ * class, each in the Worker that defines it, and a helper Worker binds only
+ * its own. Each Worker exports the classes it defines. Workflow names are
+ * account-wide, so all of them are named after the app's Worker.
+ */
+function classBindings(manifest, appWorker, forWorker, 
+/** The bindings the Worker already has, which no class may reuse. */
+taken) {
+    const bindings = {};
+    const exports = {};
+    const definedHere = (resource) => resource.worker === forWorker;
+    const definingWorker = (resource) => resource.worker ? helperWorkerName(appWorker, resource.worker) : appWorker;
+    for (const durableObject of manifest.resources?.durableObjects ?? []) {
+        if (forWorker !== undefined && !definedHere(durableObject))
+            continue;
+        bindings[durableObject.name] = {
+            type: "durable-object",
+            worker: definingWorker(durableObject),
+            exportName: durableObject.className,
+        };
+        if (definedHere(durableObject)) {
+            exports[durableObject.className] = {
+                type: "durable-object",
+                storage: "sqlite",
+            };
+        }
+    }
+    // The defining Worker exports each Workflow, and every Worker that binds
+    // one can start it and look up its instances.
+    for (const workflow of manifest.resources?.workflows ?? []) {
+        if (forWorker !== undefined && !definedHere(workflow))
+            continue;
+        if (taken[workflow.name] ||
+            bindings[workflow.name] ||
+            exports[workflow.className]) {
+            throw new Error(`workflows: ${workflow.name} (${workflow.className}) reuses a binding or class name the Worker already has.`);
+        }
+        const workflowName = workflowNameFor(appWorker, workflow.name);
+        if (workflowName.length > MAX_WORKFLOW_NAME_LENGTH) {
+            throw new Error(`workflows: ${workflow.name} would be the Workflow "${workflowName}", longer than Cloudflare's ${MAX_WORKFLOW_NAME_LENGTH} characters; shorten the binding name.`);
+        }
+        bindings[workflow.name] = {
+            type: "workflow",
+            name: workflowName,
+            worker: definingWorker(workflow),
+            exportName: workflow.className,
+        };
+        if (definedHere(workflow)) {
+            exports[workflow.className] = { type: "workflow", name: workflowName };
+        }
+    }
+    return { bindings, exports };
+}
+/**
+ * Check the names of the manifest's `secrets`, and in dev declare the ones
+ * set locally, with the developer's own keys for the manifest's providers
+ * and capabilities.
+ */
+function addSecrets(env, options, deploy) {
+    const secrets = manifestSecretNames(options.manifest);
+    for (const secret of secrets) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(secret)) {
+            throw new Error(`secrets: "${secret}" isn't a valid binding name.`);
+        }
+        if (env[secret] || RESERVED_SECRET_NAME.test(secret)) {
+            throw new Error(`secrets: ${secret} is a name the deploy sets or a binding it builds.`);
+        }
+    }
+    if (!deploy) {
+        // With `.dev.vars` setting it, EVERYAPP_EMAIL_SENDERS stands in for the
+        // senders a gateway holds for an installation (`everyapp email set`).
+        const names = new Set([
+            ...secrets,
+            ...devGatewayKeys(options.manifest),
+            ...devProviderKeys(options.manifest, options.root),
+            ...(options.manifest.capabilities?.["email"]
+                ? ["EVERYAPP_EMAIL_SENDERS"]
+                : []),
+        ]);
+        for (const secret of locallySetSecrets(options.root ?? process.cwd(), options.ctx.mode ?? "development", [...names].filter((name) => !env[name]))) {
+            env[secret] = { type: "secret" };
+        }
+    }
+}
+/** The {@link DEV_GATEWAY_KEYS} of the manifest's providers and capabilities. */
+function devGatewayKeys(manifest) {
+    const keysOf = (table, id) => (Object.hasOwn(table, id) ? table[id] : []);
+    return [
+        ...manifestProviderIds(manifest).flatMap((provider) => keysOf(DEV_GATEWAY_KEYS.providers, provider)),
+        ...Object.keys(manifest.capabilities ?? {}).flatMap((id) => keysOf(DEV_GATEWAY_KEYS.capabilities, id)),
+    ];
+}
+/** `nodejs_compat`, then the app's own flags, each once. */
+function compatibilityFlags(flags) {
+    return [...new Set(["nodejs_compat", ...(flags ?? [])])];
+}
+function cronTriggers(crons) {
+    return (crons ?? []).map((schedule) => {
+        if (!/^\S+( \S+){4}$/.test(schedule)) {
+            throw new Error(`crons: "${schedule}" isn't a five-field cron schedule, e.g. "0 6 * * *".`);
+        }
+        return { type: "scheduled", schedule };
+    });
+}
+function observability() {
+    return {
+        ...EVERYAPP_OBSERVABILITY,
+        logs: { ...EVERYAPP_OBSERVABILITY.logs },
+        traces: { ...EVERYAPP_OBSERVABILITY.traces },
+        issues: { ...EVERYAPP_OBSERVABILITY.issues },
+    };
+}
+/**
+ * The Workflow a binding defines, named after the app's Worker:
+ * `every-acme-seo` and `RANK_CHECK` → `every-acme-seo--rank-check`.
+ * Workflow names are unique in the account, and new app ids can't contain
+ * `--`, so one app's Workflow is never named like another app's.
+ */
+export function workflowNameFor(workerName, binding) {
+    return `${workerName}--${binding.toLowerCase().replaceAll("_", "-")}`;
+}
+/**
+ * The local D1 database id for a binding: a 32-hex string, because
+ * `cf d1 … --local` rejects names. The everyapp CLI computes the same id to
+ * apply local migrations to the database `cf dev` serves.
+ */
+export function localD1Id(workerName, binding) {
+    return createHash("sha256")
+        .update(`${workerName}:${binding}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/** Where `cf dev` keeps D1 databases, under the app's state directory. */
+const LOCAL_D1_OBJECT = "miniflare-D1DatabaseObject";
+/**
+ * The sqlite file `cf dev` (and `cf d1 … --local`) keeps the local D1
+ * database `databaseId` in, under the app at `root`, for tools such as
+ * drizzle-kit studio: `.cloudflare/state/v3/d1/miniflare-D1DatabaseObject/
+ * <hash>.sqlite`. The database is a Durable Object named after its id, and
+ * the file after that object's id. `databaseId` is the {@link localD1Id}.
+ */
+export function localD1Path(root, databaseId) {
+    return path.join(root, ".cloudflare", "state", "v3", "d1", LOCAL_D1_OBJECT, `${durableObjectIdFromName(LOCAL_D1_OBJECT, databaseId)}.sqlite`);
+}
+/** The id workerd's `idFromName(name)` gives in the namespace `uniqueKey`. */
+function durableObjectIdFromName(uniqueKey, name) {
+    const key = createHash("sha256").update(uniqueKey).digest();
+    const nameHmac = createHmac("sha256", key)
+        .update(name)
+        .digest()
+        .subarray(0, 16);
+    const hmac = createHmac("sha256", key)
+        .update(nameHmac)
+        .digest()
+        .subarray(0, 16);
+    return Buffer.concat([nameHmac, hmac]).toString("hex");
+}
+/**
+ * The `secrets` set for local dev, read the way the Vite plugin reads them:
+ * `.dev.vars[.<mode>]` alone when present, otherwise `.env` files and the
+ * process environment.
+ */
+function locallySetSecrets(root, mode, names) {
+    if (names.length === 0)
+        return [];
+    const values = localEnv(root, mode);
+    return names.filter((name) => values[name]);
+}
+/** The values local dev sees, read as the Vite plugin reads them. */
+function localEnv(root, mode) {
+    const read = (name) => {
+        const file = path.join(root, name);
+        return fs.existsSync(file) ? parseEnv(fs.readFileSync(file, "utf8")) : {};
+    };
+    const devVars = [`.dev.vars.${mode}`, ".dev.vars"].find((name) => fs.existsSync(path.join(root, name)));
+    return devVars
+        ? read(devVars)
+        : {
+            ...read(".env"),
+            ...read(".env.local"),
+            ...read(`.env.${mode}`),
+            ...read(`.env.${mode}.local`),
+            ...process.env,
+        };
+}
+/** The dev Worker name, e.g. "todo" -> "every-todo". */
+function workerNameFor(appId) {
+    return appId.startsWith("every-") ? appId : `every-${appId}`;
+}
+/**
+ * Copies of the gateway's naming rules (@every-app/perimeter/manifest's
+ * resourceNameFor and bucketNameFor): `DB` and `KV` (`R2` for a bucket) take
+ * the Worker's name, any other binding `<worker>--<binding>`.
+ */
+function resourceNameFor(workerName, binding) {
+    return binding === "DB" || binding === "KV"
+        ? workerName
+        : suffixedName(workerName, binding);
+}
+function bucketNameFor(workerName, binding) {
+    return binding === "R2" ? workerName : suffixedName(workerName, binding);
+}
+function suffixedName(workerName, binding) {
+    return `${workerName}--${binding.toLowerCase().replaceAll("_", "-")}`;
+}
+function assertAppId(id) {
+    if (typeof id !== "string" || !/^[a-z]([a-z0-9-]*[a-z0-9])?$/.test(id)) {
+        throw new Error(`everyapp.config.ts id must be kebab-case (lowercase letters, digits, hyphens); got ${JSON.stringify(id)}.`);
+    }
+}
+/** The target's resource for a manifest binding, which it always has. */
+function provisioned(resources, binding) {
+    const resource = resources?.[binding];
+    if (resource === undefined) {
+        throw new Error(`The build has no placeholder for binding "${binding}".`);
+    }
+    return resource;
+}