@hearthlog/tooling 0.0.0-stage → 0.1.0

package/src/tenants/tenant-copy-plan.ts

@@ -0,0 +1,119 @@
+/**
+ * What a tenant copy moves between buckets, as pure data.
+ *
+ * A copy gives the new tenant new app and log IDs, and private object keys
+ * embed them: invoice files are `<prefix>/<appId>/<logId>/…` and Gallery
+ * files `v1/<appId>/…`. Gallery publications are keyed by their own ID, but
+ * their `owner.json` names the app and log. The generated-invoice cache
+ * (`v1/<appId>/<logId>/invoices/…`) is not copied: it rebuilds on demand.
+ * Calendar feeds are not copied: the new tenant creates its own.
+ *
+ * A **move** (the split of a shared tenant onto its own stack) keeps the app
+ * and log IDs, so every key stays exactly as it is: `identity: true` copies
+ * each prefix to the same name in the destination bucket, per app rather than
+ * per log, and publication owner records are already correct and left alone.
+ */
+
+export interface TenantCopyMapping {
+    sourceAppId: string;
+    targetAppId: string;
+    /** Source log ID to target log ID, for every copied log. Empty for an identity move. */
+    logs: Readonly<Record<string, string>>;
+    /** The destination keeps the app and log IDs, so keys are copied unchanged. */
+    identity?: true;
+}
+
+/** The mapping of a move that keeps every identity. */
+export function identityMapping(appId: string): TenantCopyMapping {
+    return { sourceAppId: appId, targetAppId: appId, logs: {}, identity: true };
+}
+
+export type BucketPair = "invoice-pdfs" | "gallery-files" | "gallery-public";
+
+export interface CopyJob {
+    pair: BucketPair;
+    fromPrefix: string;
+    toPrefix: string;
+    /** Rewrite `owner.json` objects under this prefix to the target app and log. */
+    rewriteOwner?: boolean;
+}
+
+const INVOICE_FILE_PREFIXES = ["received/v1", "received-isdoc/v1", "issued/v1", "issued-isdoc/v1"] as const;
+
+const ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function requireId(value: string, label: string): void {
+    if (!ID.test(value)) throw new Error(`${label} is not a UUID: ${value}`);
+}
+
+export function validateMapping(mapping: TenantCopyMapping): void {
+    requireId(mapping.sourceAppId, "source app");
+    requireId(mapping.targetAppId, "target app");
+    if (mapping.identity) {
+        if (mapping.sourceAppId !== mapping.targetAppId) throw new Error("an identity move keeps the app: source and target must be the same id");
+        if (Object.keys(mapping.logs).length) throw new Error("an identity move names no logs: every log keeps its id");
+        return;
+    }
+    if (mapping.sourceAppId === mapping.targetAppId) throw new Error("source and target apps are the same");
+    for (const [source, target] of Object.entries(mapping.logs)) {
+        requireId(source, "source log");
+        requireId(target, "target log");
+    }
+}
+
+/** Every prefix to copy, given the publications the source app owns. */
+export function planFileCopies(mapping: TenantCopyMapping, ownedPublications: readonly string[]): CopyJob[] {
+    validateMapping(mapping);
+    const jobs: CopyJob[] = [];
+    if (mapping.identity) {
+        for (const prefix of INVOICE_FILE_PREFIXES) {
+            const key = `${prefix}/${mapping.sourceAppId}/`;
+            jobs.push({ pair: "invoice-pdfs", fromPrefix: key, toPrefix: key });
+        }
+        jobs.push({ pair: "gallery-files", fromPrefix: `v1/${mapping.sourceAppId}/`, toPrefix: `v1/${mapping.sourceAppId}/` });
+        for (const publication of ownedPublications) {
+            requireId(publication, "publication");
+            const control = `v1/publications/${publication}/`;
+            jobs.push({ pair: "gallery-files", fromPrefix: control, toPrefix: control });
+            jobs.push({ pair: "gallery-public", fromPrefix: `v1/galleries/${publication}/`, toPrefix: `v1/galleries/${publication}/` });
+        }
+        return jobs;
+    }
+    for (const prefix of INVOICE_FILE_PREFIXES) {
+        for (const [sourceLog, targetLog] of Object.entries(mapping.logs)) {
+            jobs.push({
+                pair: "invoice-pdfs",
+                fromPrefix: `${prefix}/${mapping.sourceAppId}/${sourceLog}/`,
+                toPrefix: `${prefix}/${mapping.targetAppId}/${targetLog}/`,
+            });
+        }
+    }
+    jobs.push({ pair: "gallery-files", fromPrefix: `v1/${mapping.sourceAppId}/`, toPrefix: `v1/${mapping.targetAppId}/` });
+    for (const publication of ownedPublications) {
+        requireId(publication, "publication");
+        jobs.push({
+            pair: "gallery-files",
+            fromPrefix: `v1/publications/${publication}/`,
+            toPrefix: `v1/publications/${publication}/`,
+            rewriteOwner: true,
+        });
+        jobs.push({ pair: "gallery-public", fromPrefix: `v1/galleries/${publication}/`, toPrefix: `v1/galleries/${publication}/` });
+    }
+    return jobs;
+}
+
+export function isOwnerRecord(key: string): boolean {
+    return /^v1\/publications\/[^/]+\/owner\.json$/.test(key);
+}
+
+/** The owner record for the target tenant; throws for a log the copy left out. */
+export function rewriteOwner(record: unknown, mapping: TenantCopyMapping): { appId: string; logId: string } {
+    const owner = record as { appId?: unknown; logId?: unknown } | null;
+    if (!owner || typeof owner.appId !== "string" || typeof owner.logId !== "string") {
+        throw new Error("publication owner record is malformed");
+    }
+    if (owner.appId !== mapping.sourceAppId) throw new Error("publication belongs to another app");
+    const logId = mapping.logs[owner.logId];
+    if (!logId) throw new Error(`publication belongs to log ${owner.logId}, which was not copied`);
+    return { appId: mapping.targetAppId, logId };
+}

package/src/tenants/tenant-schema.ts

@@ -0,0 +1,171 @@
+#!/usr/bin/env npx tsx
+/**
+ * JSON Schema for tenants.json, so editors validate and complete it.
+ *
+ * Feature ids, AI capabilities and integration kinds come from the code, so
+ * the schema is generated rather than hand-written. `tenant-config.ts` stays
+ * the authoritative validator; the schema only mirrors its shape for IDEs.
+ *
+ * Usage: pnpm generate:tenant-schema [--check]
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { FEATURES } from "@hearthlog/contracts/features/registry";
+import { AI_CAPABILITIES } from "@hearthlog/contracts/ai/capabilities";
+import { INTEGRATION_ID_PATTERN, INTEGRATION_KINDS } from "@hearthlog/contracts/integrations/kinds";
+import { DEVELOPER_PATH, REPOSITORY_ROOT } from "./tenant-config.js";
+
+export const TENANT_SCHEMA_FILE = join(REPOSITORY_ROOT, "tenants.schema.json");
+
+const nonEmptyString = { type: "string", minLength: 1 };
+const httpsOrigin = { type: "string", pattern: "^https://[^/?#@]+/?$" };
+const hours = { type: "string", pattern: "^[1-9][0-9]*h$", description: "Whole hours between 1h and 720h." };
+
+export function buildTenantSchema(): Record<string, unknown> {
+    const featureIds = FEATURES.map((feature) => feature.id);
+    const homePaths = [...new Set(["/", DEVELOPER_PATH, ...FEATURES.flatMap((feature) => feature.page ? [feature.page.path] : [])])];
+    const shared = {
+        features: {
+            type: "array",
+            items: { enum: featureIds },
+            minItems: 1,
+            uniqueItems: true,
+        },
+        home: { enum: homePaths, description: "Start path; must belong to an enabled feature." },
+        title: nonEmptyString,
+        developerNavVisible: { type: "boolean" },
+        entitiesNavVisible: { type: "boolean" },
+    };
+    return {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        title: "Hearthlog tenants",
+        description: "Generated by packages/tooling/src/tenants/tenant-schema.ts; do not edit by hand.",
+        type: "object",
+        additionalProperties: false,
+        required: ["infrastructure"],
+        properties: {
+            $schema: { type: "string" },
+            infrastructure: {
+                type: "object",
+                additionalProperties: false,
+                required: [
+                    "ledgerWorker",
+                    "invoicePdfsBucket",
+                    "calendarFeedsBucket",
+                    "calendarPublicWorker",
+                    "calendarPublicOrigin",
+                    "galleryFilesBucket",
+                    "galleryPublicBucket",
+                    "galleryPublicWorker",
+                    "galleryPublicOrigin",
+                    "workersDevDomain",
+                    "ledgerAdminEmail",
+                    "accessTeamDomain",
+                ],
+                properties: {
+                    ledgerWorker: nonEmptyString,
+                    invoicePdfsBucket: nonEmptyString,
+                    calendarFeedsBucket: nonEmptyString,
+                    calendarPublicWorker: nonEmptyString,
+                    calendarPublicOrigin: httpsOrigin,
+                    galleryFilesBucket: nonEmptyString,
+                    galleryPublicBucket: nonEmptyString,
+                    galleryPublicWorker: nonEmptyString,
+                    galleryPublicOrigin: httpsOrigin,
+                    workersDevDomain: { type: "string", pattern: "^[a-z0-9][a-z0-9-]*\\.workers\\.dev$", description: "The account's workers.dev subdomain." },
+                    invoiceRendererOrigin: httpsOrigin,
+                    kalApiOrigin: httpsOrigin,
+                    ledgerAdminEmail: { type: "string", format: "email" },
+                    accessTeamDomain: httpsOrigin,
+                    accessSessionDuration: hours,
+                    accessGlobalSessionDuration: hours,
+                    accountId: { type: "string", pattern: "^[0-9a-f]{32}$", description: "The Cloudflare account that holds the shared stack." },
+                    gallerySweeper: { type: "string", description: "The shared-stack site that sweeps the public Gallery bucket; the first by id when unset." },
+                },
+            },
+            defaults: {
+                type: "object",
+                additionalProperties: false,
+                properties: shared,
+            },
+            sites: {
+                type: "array",
+                items: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["id", "authorizedEmails"],
+                    properties: {
+                        id: {
+                            type: "string",
+                            pattern: "^[a-z0-9][a-z0-9-]*$",
+                            description: "Becomes the wrangler env, the Worker name and the workers.dev hostname.",
+                        },
+                        ledgerAppName: nonEmptyString,
+                        admin: { type: "boolean" },
+                        authorizedEmails: {
+                            type: "array",
+                            items: { type: "string", format: "email" },
+                            minItems: 1,
+                            uniqueItems: true,
+                        },
+                        ...shared,
+                        ai: {
+                            type: "array",
+                            items: { enum: [...AI_CAPABILITIES] },
+                            uniqueItems: true,
+                        },
+                        integrations: {
+                            type: "array",
+                            items: {
+                                type: "object",
+                                additionalProperties: false,
+                                required: ["id", "kind", "logId"],
+                                properties: {
+                                    id: { type: "string", pattern: INTEGRATION_ID_PATTERN.source },
+                                    kind: { enum: [...INTEGRATION_KINDS] },
+                                    logId: { type: "string", format: "uuid" },
+                                    clientId: { type: "string", description: "Access service-token client id; inactive until set." },
+                                },
+                            },
+                        },
+                        dynamicEntities: { type: "boolean" },
+                        theme: {
+                            type: "object",
+                            additionalProperties: false,
+                            properties: {
+                                accent: { type: "string", pattern: "^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" },
+                            },
+                        },
+                        hostname: { type: "string", format: "uri" },
+                    },
+                },
+            },
+        },
+    };
+}
+
+export function renderTenantSchema(): string {
+    return `${JSON.stringify(buildTenantSchema(), null, 2)}\n`;
+}
+
+/** Whether tenants.schema.json matches the code it is generated from. */
+export async function isTenantSchemaCurrent(): Promise<boolean> {
+    const current = await readFile(TENANT_SCHEMA_FILE, "utf8").catch(() => "");
+    return current === renderTenantSchema();
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    if (process.argv.includes("--check")) {
+        if (!(await isTenantSchemaCurrent())) {
+            console.error("tenants.schema.json is stale; run pnpm generate:tenant-schema");
+            process.exit(1);
+        }
+        console.log("tenants.schema.json is current.");
+    } else {
+        await writeFile(TENANT_SCHEMA_FILE, renderTenantSchema());
+        console.log("Generated tenants.schema.json");
+    }
+}

package/src/tenants/tenant-wrangler.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared wrangler invocation for one tenant's frontend Worker.
+ *
+ * Every site's wrangler config is generated from tenants.json on demand (`.generated/sites/<id>/wrangler.jsonc`).
+ */
+
+import { spawnSync } from "node:child_process";
+
+import { loadTenantConfig, REPOSITORY_ROOT, TenantConfigError } from "./tenant-config.js";
+import {
+    generateTenantWranglerConfigs,
+    resolveFrontendWranglerTarget,
+} from "./wrangler-config.js";
+
+export async function runTenantWrangler(
+    siteId: string,
+    args: string[],
+): Promise<void> {
+    await generateTenantWranglerConfigs(siteId);
+    const { sites } = await loadTenantConfig();
+    if (!sites.some((site) => site.id === siteId)) {
+        throw new TenantConfigError(
+            `Unknown site id "${siteId}" (known: ${sites.map((site) => site.id).join(", ")})`,
+        );
+    }
+
+    const target = await resolveFrontendWranglerTarget(siteId);
+    const tail = target.envKey === null ? [] : ["--env", target.envKey];
+    const result = spawnSync(
+        "pnpm",
+        ["exec", "wrangler", ...args, "--config", target.config, ...tail],
+        { cwd: REPOSITORY_ROOT, stdio: "inherit" },
+    );
+    if (result.status !== 0) {
+        process.exit(result.status ?? 1);
+    }
+}

package/src/tenants/wrangler-base.ts

@@ -0,0 +1,50 @@
+/**
+ * What every site's frontend Worker config shares. `wrangler-config.ts` adds the site: its identity, variables, and
+ * the bindings its modules declare. The compatibility date is the Workers runtime the gateway code is tested against,
+ * so a tenant moves it by upgrading `@hearthlog/tooling`.
+ */
+
+export interface WranglerBase {
+    compatibility_date: string;
+    compatibility_flags: string[];
+    assets: {
+        binding: string;
+        not_found_handling: string;
+        /** The core's API paths; a site's modules add theirs (see `siteWorkerFirst`). `/api/ledger` stays first. */
+        run_worker_first: string[];
+    };
+    observability: { enabled: boolean };
+    placement: { mode: string };
+    images: { binding: string };
+    ai: { binding: string };
+    /** Service ingest is limited per Access client id; the namespace id only has to be unique in the account. */
+    ratelimits: Array<{ name: string; namespace_id: string; simple: { limit: number; period: number } }>;
+    /** The daily sweep of the public Gallery copies, for the site that owns the bucket. */
+    triggers: { crons: string[] };
+}
+
+export const WRANGLER_BASE: WranglerBase = {
+    compatibility_date: "2026-07-21",
+    compatibility_flags: ["assets_navigation_has_no_effect"],
+    assets: {
+        binding: "ASSETS",
+        not_found_handling: "none",
+        run_worker_first: [
+            "/api/ledger",
+            "/api/ledger/*",
+            "/api/session",
+            "/api/ai/v1",
+            "/api/ai/v1/*",
+            "/api/calendar-feeds/v1",
+            "/api/calendar-feeds/v1/*",
+            "/api/integrations/v1",
+            "/api/integrations/v1/*",
+        ],
+    },
+    observability: { enabled: true },
+    placement: { mode: "smart" },
+    images: { binding: "IMAGES" },
+    ai: { binding: "AI" },
+    ratelimits: [{ name: "INTEGRATIONS_LIMITER", namespace_id: "21001", simple: { limit: 30, period: 60 } }],
+    triggers: { crons: ["23 3 * * *"] },
+};

package/src/tenants/wrangler-config.ts

@@ -0,0 +1,266 @@
+/**
+ * Tenant wrangler-config generation.
+ *
+ * A site's directory (`tenants/<id>/`) and the shared infrastructure are the source of truth for deployed sites. For
+ * every site this module writes a standalone frontend Worker config into the site's generated folder,
+ * `.generated/sites/<id>/wrangler.jsonc`, from the shared base in `wrangler-base.ts`
+ * and the site's modules. The files are gitignored and deterministic, and are regenerated by `hearthlog build`,
+ * the deploy tools, and `pnpm check:tenants`. Paths in them are relative to that folder, as wrangler resolves them.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+
+import type { ModuleManifest } from "@hearthlog/contracts";
+
+import { WRANGLER_BASE } from "./wrangler-base.js";
+import { activeIntegrations } from "@hearthlog/contracts/integrations/kinds";
+import { gatewayEntryPath, loadModules, modulesForFeatures } from "../compose/compose-modules.js";
+import {
+    gallerySweeperId,
+    infrastructureFor,
+    loadTenantConfig,
+    REPOSITORY_ROOT,
+    type InfrastructureDefinition,
+    type ResolvedSite,
+    type SiteStack,
+} from "./tenant-config.js";
+
+/** Strip line and block comments from wrangler's JSONC without touching strings. */
+export function stripJsonComments(jsonc: string): string {
+    let result = "";
+    let index = 0;
+    let inString = false;
+    while (index < jsonc.length) {
+        const char = jsonc[index];
+        const next = jsonc[index + 1];
+        if (inString) {
+            result += char;
+            if (char === "\\") {
+                result += next ?? "";
+                index += 2;
+                continue;
+            }
+            if (char === '"') inString = false;
+            index += 1;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            result += char;
+            index += 1;
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            while (index < jsonc.length && jsonc[index] !== "\n") index += 1;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            index += 2;
+            while (
+                index < jsonc.length &&
+                !(jsonc[index] === "*" && jsonc[index + 1] === "/")
+            ) {
+                index += 1;
+            }
+            index += 2;
+            continue;
+        }
+        result += char;
+        index += 1;
+    }
+    return result;
+}
+
+/** The folder a site's generated frontend Worker files are in. */
+export function siteConfigDirectory(siteId: string): string {
+    return dirname(gatewayEntryPath(siteId));
+}
+
+/** Where a site's frontend Worker config is written. */
+export function wranglerConfigPath(siteId: string): string {
+    return join(siteConfigDirectory(siteId), "wrangler.jsonc");
+}
+
+/** Where `vite build` writes a site's assets, from the repository root; the default site builds into `build`. */
+export function siteBuildDirectory(siteId: string): string {
+    return siteId === "st" ? "build" : `build/${siteId}`;
+}
+
+/** The server declarations of the modules a site enables, in module order. */
+export function serverDeclarations(features: readonly string[]): Array<NonNullable<ModuleManifest["server"]>> {
+    return modulesForFeatures(loadModules(), features).flatMap(({ manifest }) => manifest.server ? [manifest.server] : []);
+}
+
+/** `run_worker_first` entries for API prefixes: the prefix and everything beneath it. */
+export function workerFirstEntries(prefixes: readonly string[]): string[] {
+    // Wrangler rejects a rule another makes redundant, so a prefix beneath a listed one is left out
+    // (`/api/invoice-generation/logs` is served by the `/api/invoice-generation/*` rule).
+    const outer = prefixes.filter((prefix) => !prefixes.some((other) => other !== prefix && prefix.startsWith(`${other}/`)));
+    return outer.flatMap((prefix) => [prefix, `${prefix}/*`]);
+}
+
+/** The core's `run_worker_first` entries, then those of the site's modules. */
+export function siteWorkerFirst(features: readonly string[]): string[] {
+    return [...WRANGLER_BASE.assets.run_worker_first, ...workerFirstEntries(serverDeclarations(features).flatMap((server) => server.routes ?? []))];
+}
+
+/**
+ * The bindings and variables a site's modules need, from their manifests.
+ * `resource` names a key of the tenant's infrastructure.
+ */
+export function moduleBindings(
+    features: readonly string[],
+    infrastructure: InfrastructureDefinition,
+): { r2: Array<{ binding: string; bucket_name: string }>; images: boolean; vars: Record<string, string> } {
+    const keyed = infrastructure as unknown as Record<string, string | undefined>;
+    const lookup = (resource: string): string => {
+        const value = keyed[resource];
+        if (!value) throw new Error(`The infrastructure has no "${resource}"`);
+        return value;
+    };
+    const optional = (resource: string): string | undefined => keyed[resource];
+    const result = { r2: [] as Array<{ binding: string; bucket_name: string }>, images: false, vars: {} as Record<string, string> };
+    for (const server of serverDeclarations(features)) {
+        for (const binding of server.bindings ?? []) {
+            if (binding.type === "r2") result.r2.push({ binding: binding.binding, bucket_name: lookup(binding.resource) });
+            else result.images = true;
+        }
+        for (const variable of server.vars ?? []) {
+            const value = variable.optional ? optional(variable.resource) : lookup(variable.resource);
+            if (value) result.vars[variable.name] = value;
+        }
+    }
+    return result;
+}
+
+/**
+ * Derive the standalone wrangler config for one site. Everything not tenant-specific (compatibility, assets
+ * behavior, observability, smart placement) comes from the shared base; the identity, vars, and bindings come from
+ * tenants.json and the site's modules. Pass the site's own infrastructure (`infrastructureFor`): a site on its own
+ * stack binds only its own Ledger and buckets. `sweeps` marks the site that sweeps the public Gallery bucket it owns.
+ */
+export function buildTenantWranglerConfig(
+    site: ResolvedSite,
+    infrastructure: InfrastructureDefinition,
+    options: { sweeps?: boolean } = {},
+): Record<string, unknown> {
+    const modules = moduleBindings(site.features, infrastructure);
+    const scheduled = serverDeclarations(site.features).some((server) => server.scheduled);
+    const base = WRANGLER_BASE;
+    const directory = siteConfigDirectory(site.id);
+    return {
+        name: site.id,
+        ...(site.deployment?.accountId ? { account_id: site.deployment.accountId } : {}),
+        main: `./${relative(directory, gatewayEntryPath(site.id))}`,
+        compatibility_date: base.compatibility_date,
+        compatibility_flags: base.compatibility_flags,
+        // Sites live on their Access-protected workers.dev hostname only:
+        // version preview hostnames are never enabled.
+        workers_dev: true,
+        preview_urls: false,
+        assets: {
+            directory: relative(directory, join(REPOSITORY_ROOT, siteBuildDirectory(site.id))),
+            binding: base.assets.binding,
+            not_found_handling: base.assets.not_found_handling,
+            run_worker_first: siteWorkerFirst(site.features),
+        },
+        observability: base.observability,
+        placement: base.placement,
+        vars: {
+            LEDGER_ADMIN_EMAIL: infrastructure.ledgerAdminEmail,
+            STOR_AUTHORIZED_EMAILS: site.authorizedEmails.join(","),
+            STOR_ADMIN_ENABLED: String(site.admin),
+            ...modules.vars,
+            AI_CAPABILITIES: site.ai.join(","),
+            INTEGRATIONS: integrationsVariable(site),
+            ...siteIdentityVariables(site, infrastructure),
+        },
+        services: [
+            {
+                binding: "LEDGER",
+                service: infrastructure.ledgerWorker,
+            },
+        ],
+        // Each site's gateway entry bundles only the server code of the modules it enables.
+        ...(modules.images ? { images: base.images } : {}),
+        ratelimits: base.ratelimits,
+        ...(options.sweeps && scheduled ? { triggers: base.triggers } : {}),
+        ai: base.ai,
+        r2_buckets: [
+            {
+                binding: "CALENDAR_FEEDS",
+                bucket_name: infrastructure.calendarFeedsBucket,
+            },
+            ...modules.r2,
+        ],
+    };
+}
+
+/**
+ * The site that sweeps the shared stack's public Gallery bucket: the configured one (`gallerySweeper`), else the first
+ * site without a stack of its own (a site with its own stack sweeps its own bucket). Two sweepers on one bucket would race.
+ */
+export function sweepsSharedStack(
+    stacks: readonly SiteStack[],
+    infrastructure: Pick<InfrastructureDefinition, "gallerySweeper">,
+    site: Pick<ResolvedSite, "id" | "deployment">,
+): boolean {
+    return Boolean(site.deployment) || gallerySweeperId(stacks, infrastructure) === site.id;
+}
+
+/**
+ * Who the site is and where its calendar feeds are served: the feed UIDs carry
+ * the site's own hostname, and the drawer returns URLs on the feed Worker.
+ */
+export function siteIdentityVariables(
+    site: ResolvedSite,
+    infrastructure: Pick<InfrastructureDefinition, "calendarPublicOrigin">,
+): Record<string, string> {
+    return {
+        SITE_ID: site.id,
+        SITE_ORIGIN: site.hostname,
+        CALENDAR_FEED_ORIGIN: infrastructure.calendarPublicOrigin,
+    };
+}
+
+/** The non-secret integration list a site's Worker accepts, as the INTEGRATIONS variable. */
+export function integrationsVariable(site: ResolvedSite): string {
+    return JSON.stringify(activeIntegrations(site.integrations));
+}
+
+/**
+ * Generate the standalone wrangler config of a site (all of them without an id). A build passes its own site, whose modules are the only ones in its catalog. Returns the written paths.
+ */
+export async function generateTenantWranglerConfigs(siteId?: string): Promise<string[]> {
+    const { infrastructure, sites, stacks } = await loadTenantConfig(undefined, { only: siteId });
+    const written: string[] = [];
+    for (const site of sites) {
+        const path = wranglerConfigPath(site.id);
+        const config = buildTenantWranglerConfig(site, infrastructureFor(site, infrastructure), { sweeps: sweepsSharedStack(stacks, infrastructure, site) });
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+        written.push(path);
+    }
+    return written;
+}
+
+/** Where a site's wrangler config lives (relative to the repository root, where the tools run wrangler). */
+export interface WranglerTarget {
+    config: string;
+    /** --env value; null means the config is standalone (no --env). */
+    envKey: string | null;
+}
+
+export function resolveFrontendWranglerTarget(siteId: string): WranglerTarget {
+    return { config: relative(REPOSITORY_ROOT, wranglerConfigPath(siteId)), envKey: null };
+}
+
+export async function ensureTenantWranglerConfigs(): Promise<void> {
+    const written = await generateTenantWranglerConfigs();
+    if (written.length > 0 && process.env.STOR_VERBOSE) {
+        for (const path of written) {
+            console.log(`Generated ${path.replace(`${REPOSITORY_ROOT}/`, "")}`);
+        }
+    }
+}