@hearthlog/tooling 0.0.0-stage → 0.1.1

package/src/init/init.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env npx tsx
+/**
+ * `hearthlog init <dir> --id <id> [--title <title>] [--modules <list>] [--workspace] [--check] [--force]`
+ *
+ * Render `templates/tenant/` into a new site: the package.json, the Vite and TypeScript configuration, a
+ * `tenants.json` with placeholder infrastructure (it makes the site load and cannot be deployed), the site's
+ * `tenant.json`, its module lock, the committed `.generated/package.json`, and the pnpm settings the install needs (the
+ * build scripts to allow and the patch to `sqlocal`, which does not travel with a dependency). The modules are named by package
+ * (`@hearthlog/module-calc`), by short name (`calc`), or `none`; their features become the site's features.
+ * `--workspace` writes the `@hearthlog` dependencies as `workspace:*` (a site inside a workspace); otherwise
+ * they are `^<version of this package>`. `--check` writes nothing and fails when the files on disk differ
+ * from what init would write, so the committed examples cannot drift from the template; `--force` rewrites
+ * existing files (how an example is brought back in line).
+ *
+ * Nothing here reads generated files: init is how a site gets started, before `hearthlog build` has run.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadModules, type LoadedModule } from "../compose/compose-modules.js";
+import { lockFor, renderModuleLock } from "../tenants/lock-file.js";
+
+const TOOLING = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const TEMPLATE = join(TOOLING, "templates", "tenant");
+
+/** The @hearthlog packages every site depends on; the modules it uses are added to them. */
+const CORE_PACKAGES = ["cloudflare", "contracts", "ledger", "runtime", "sdk", "shell", "tooling", "ui"] as const;
+
+export interface InitOptions {
+    directory: string;
+    id: string;
+    title?: string;
+    /** Package names or short names of the modules the site ships. */
+    modules?: readonly string[];
+    workspace?: boolean;
+    /** The installed modules to choose from; defaults to the ones the current host has. */
+    available?: readonly LoadedModule[];
+}
+
+const SITE_ID = /^[a-z][a-z0-9-]{0,38}$/;
+
+function render(template: string, values: Record<string, string>): string {
+    return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => {
+        if (!(key in values)) throw new Error(`The template names {{${key}}}, which init does not know`);
+        return values[key]!;
+    });
+}
+
+/** A tenant's deploy workflow (`templates/tenant/github-workflows/deploy.yml.tmpl`); `paths` limits the pushes that run it. */
+export function renderWorkflow(id: string, paths: readonly string[] = []): string {
+    const pushPaths = paths.length > 0 ? `\n    paths:\n${paths.map((path) => `      - "${path}"`).join("\n")}` : "";
+    return render(readFileSync(join(TEMPLATE, "github-workflows", "deploy.yml.tmpl"), "utf8"), { id, idUpper: id.toUpperCase().replace(/-/g, "_"), pushPaths });
+}
+
+function toolingPackage(): { version: string; peerDependencies?: Record<string, string> } {
+    return JSON.parse(readFileSync(join(TOOLING, "package.json"), "utf8")) as { version: string; peerDependencies?: Record<string, string> };
+}
+
+function chooseModules(names: readonly string[], available: readonly LoadedModule[]): LoadedModule[] {
+    return names.map((name) => {
+        const found = available.find(({ manifest }) => manifest.package === name || manifest.package === `@hearthlog/module-${name}`);
+        if (!found) throw new Error(`No installed module is called "${name}" (installed: ${available.map(({ manifest }) => manifest.package).join(", ") || "none"})`);
+        return found;
+    });
+}
+
+/** Every file init writes, as [path relative to the site, content]. */
+export function renderSite(options: InitOptions): Array<[string, string]> {
+    const { id, workspace = false } = options;
+    if (!SITE_ID.test(id)) throw new Error(`The site id "${id}" must be lowercase letters, digits, and hyphens, starting with a letter`);
+    const title = options.title ?? id;
+    const modules = chooseModules(options.modules ?? [], options.available ?? loadModules());
+    const features = [...new Set(modules.flatMap(({ manifest }) => manifest.features.map((feature) => feature.id)))].sort();
+    const tooling = toolingPackage();
+    const own = workspace ? "workspace:*" : `^${tooling.version}`;
+
+    const manifest = JSON.parse(readFileSync(join(TEMPLATE, "package.json.tmpl"), "utf8")) as Record<string, unknown>;
+    const dependencies: Record<string, string> = Object.fromEntries([
+        ...CORE_PACKAGES.map((name) => [`@hearthlog/${name}`, own]),
+        // A module is released on its own version, not on the platform's.
+        ...modules.map(({ manifest: { package: name }, directory }) => [name, workspace ? own : `^${(JSON.parse(readFileSync(join(directory, "package.json"), "utf8")) as { version: string }).version}`]),
+        ["@hearthlog/generated", "link:.generated"],
+    ].sort(([a], [b]) => a!.localeCompare(b!)));
+    const devDependencies = Object.fromEntries(Object.entries(tooling.peerDependencies ?? {}).filter(([name]) => !name.startsWith("@hearthlog/")).sort(([a], [b]) => a.localeCompare(b)));
+    const packageJson = { name: id, ...manifest, dependencies, devDependencies };
+
+    const values = { id, title, features: JSON.stringify(features) };
+    const template = (name: string) => readFileSync(join(TEMPLATE, name), "utf8");
+    return [
+        ["package.json", `${JSON.stringify(packageJson, null, 2)}\n`],
+        ["vite.config.ts", template("vite.config.ts.tmpl")],
+        ["tsconfig.json", template("tsconfig.json.tmpl")],
+        ["tenants.json", template("tenants.json.tmpl")],
+        [`tenants/${id}/tenant.json`, render(template("tenants/__id__/tenant.json.tmpl"), values)],
+        [`tenants/${id}/modules.lock.json`, renderModuleLock(lockFor(modules, features))],
+        [".generated/package.json", template("generated-package.json.tmpl")],
+        ["pnpm-workspace.yaml", template("pnpm-workspace.yaml.tmpl")],
+        ["patches/sqlocal@0.18.0.patch", template("patches/sqlocal@0.18.0.patch")],
+        [".github/workflows/deploy.yml", renderWorkflow(id)],
+        [".gitignore", template("gitignore.tmpl")],
+        ["README.md", render(template("README.md.tmpl"), values)],
+    ];
+}
+
+/** The files whose content differs from what init would write. */
+export async function initProblems(options: InitOptions): Promise<string[]> {
+    const problems: string[] = [];
+    for (const [path, content] of renderSite(options)) {
+        const current = await readFile(join(options.directory, path), "utf8").catch(() => null);
+        if (current === null) problems.push(`${path} is missing`);
+        else if (current !== content) problems.push(`${path} differs from the template`);
+    }
+    return problems;
+}
+
+export async function init(options: InitOptions & { force?: boolean }): Promise<string[]> {
+    const written: string[] = [];
+    for (const [path, content] of renderSite(options)) {
+        const target = join(options.directory, path);
+        if (existsSync(target) && !options.force) throw new Error(`${path} already exists in ${options.directory}; init does not overwrite`);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content, "utf8");
+        written.push(path);
+    }
+    return written;
+}
+
+function parse(argv: string[]): { options: InitOptions & { force: boolean }; check: boolean } {
+    const value = (flag: string) => {
+        const index = argv.indexOf(flag);
+        return index >= 0 ? argv[index + 1] : undefined;
+    };
+    const directory = argv.find((argument, index) => !argument.startsWith("--") && !["--id", "--title", "--modules"].includes(argv[index - 1] ?? ""));
+    const id = value("--id");
+    if (!directory || !id) throw new Error("Usage: hearthlog init <dir> --id <id> [--title <title>] [--modules <list|none>] [--workspace] [--check] [--force]");
+    const modules = value("--modules");
+    return {
+        options: {
+            directory: resolve(directory),
+            id,
+            title: value("--title"),
+            modules: modules === undefined || modules === "none" ? [] : modules.split(",").map((name) => name.trim()).filter(Boolean),
+            workspace: argv.includes("--workspace"),
+            force: argv.includes("--force"),
+        } as InitOptions & { force: boolean },
+        check: argv.includes("--check"),
+    };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        const { options, check } = parse(process.argv.slice(2));
+        if (check) {
+            const problems = await initProblems(options);
+            if (problems.length > 0) throw new Error(`${options.directory} no longer matches the template:\n  - ${problems.join("\n  - ")}`);
+            console.log(`${options.directory} matches the template.`);
+        } else {
+            const written = await init(options);
+            console.log(`Wrote ${written.length} file(s) to ${options.directory}. Next: pnpm install && pnpm build`);
+        }
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}

package/src/move.ts

@@ -0,0 +1,189 @@
+/**
+ * Moves one Ledger application to another Ledger with every identity intact
+ * (`GET .../transfer` on the source, `POST /admin/v1/import` and friends on the
+ * destination), and proves the result. Pure over two administrator HTTP
+ * callers, so the whole procedure runs in tests with no network.
+ *
+ * A new attempt first clears an unfinished import that an earlier, interrupted one left on the destination.
+ * It only starts against a fenced source: an export taken while writes still
+ * land would silently miss them. On any failure after the import began it
+ * aborts the half-filled destination so the move can start over, and it never
+ * touches the source.
+ */
+
+export type AdminCall = (method: 'GET' | 'POST' | 'PUT', path: string, body?: unknown) => Promise<Response>;
+
+export interface LogChecksum {
+    id: string;
+    headVersion: number;
+    eventCount: number;
+    sha256: string;
+}
+
+export interface MoveReport {
+    appId: string;
+    name: string;
+    logs: number;
+    events: number;
+    requests: number;
+    checksums: LogChecksum[];
+    movedAt: string;
+}
+
+export interface MoveOptions {
+    appId: string;
+    source: AdminCall;
+    target: AdminCall;
+    /** Rehearsals against a copy may run without a fence; a real move never does. */
+    allowUnfenced?: boolean;
+    maxBatchRecords?: number;
+    maxBatchBytes?: number;
+    log?: (message: string) => void;
+    now?: () => Date;
+}
+
+export class MoveError extends Error {
+    constructor(message: string, options?: { cause?: unknown }) {
+        super(message, options);
+        this.name = 'MoveError';
+    }
+}
+
+type Line = { t: string } & Record<string, unknown>;
+
+async function json<T>(response: Response, what: string): Promise<T> {
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new MoveError(`${what} failed with ${response.status}${detail ? `: ${detail.slice(0, 300)}` : ''}`);
+    }
+    return (await response.json()) as T;
+}
+
+async function* lines(response: Response): AsyncGenerator<Line> {
+    if (!response.body) throw new MoveError('The export has no body');
+    const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+    let pending = '';
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (value) pending += value;
+        for (let newline = pending.indexOf('\n'); newline !== -1; newline = pending.indexOf('\n')) {
+            const text = pending.slice(0, newline);
+            pending = pending.slice(newline + 1);
+            if (text.trim()) yield JSON.parse(text) as Line;
+        }
+        if (done) break;
+    }
+    if (pending.trim()) yield JSON.parse(pending) as Line;
+}
+
+export function sameChecksums(source: readonly LogChecksum[], target: readonly LogChecksum[]): string[] {
+    const problems: string[] = [];
+    const left = new Map(source.map((log) => [log.id, log]));
+    const right = new Map(target.map((log) => [log.id, log]));
+    for (const [id, log] of left) {
+        const other = right.get(id);
+        if (!other) problems.push(`log ${id} is missing at the destination`);
+        else if (other.headVersion !== log.headVersion || other.eventCount !== log.eventCount || other.sha256 !== log.sha256) {
+            problems.push(`log ${id} differs: source ${log.eventCount} events at ${log.headVersion} (${log.sha256.slice(0, 12)}), destination ${other.eventCount} at ${other.headVersion} (${other.sha256.slice(0, 12)})`);
+        }
+    }
+    for (const id of right.keys()) if (!left.has(id)) problems.push(`log ${id} exists only at the destination`);
+    return problems;
+}
+
+export async function moveApplication(options: MoveOptions): Promise<MoveReport> {
+    const { appId, source, target } = options;
+    const log = options.log ?? (() => undefined);
+    const maxRecords = options.maxBatchRecords ?? 200;
+    const maxBytes = options.maxBatchBytes ?? 1_500_000;
+
+    if (!options.allowUnfenced) {
+        const state = await json<{ fence: { mode: string } | null }>(await source('GET', `/admin/v1/apps/${appId}/fence`), 'Reading the source fence');
+        if (state.fence?.mode !== 'tenant_migrating') {
+            throw new MoveError('The source is not fenced. Pause its writes first (mode "tenant_migrating"), or the copy would miss them.');
+        }
+    }
+
+    const exported = await source('GET', `/admin/v1/apps/${appId}/transfer`);
+    if (!exported.ok) {
+        const detail = await exported.text().catch(() => '');
+        throw new MoveError(`Exporting the source failed with ${exported.status}${detail ? `: ${detail.slice(0, 300)}` : ''}`);
+    }
+
+    // An earlier attempt that lost its connection could not abort itself, and leaves an unfinished import that refuses
+    // a new one. Aborting is safe here: it only acts on an import in progress and refuses a finished one.
+    await target('POST', `/admin/v1/apps/${appId}/import/abort`).catch(() => undefined);
+
+    let begun = false;
+    try {
+        let app: Line | null = null;
+        let end: Line | null = null;
+        const heads: Array<{ id: string; headVersion: number }> = [];
+        let batch: Line[] = [];
+        let batchBytes = 0;
+        const counted = { logs: 0, events: 0, requests: 0 };
+
+        const flush = async () => {
+            if (batch.length === 0) return;
+            await json(await target('POST', `/admin/v1/apps/${appId}/import`, { records: batch }), 'Importing a chunk');
+            batch = [];
+            batchBytes = 0;
+        };
+
+        for await (const line of lines(exported)) {
+            if (line.t === 'app') {
+                if (app) throw new MoveError('The export names two applications');
+                if (line.id !== appId) throw new MoveError(`The export is for ${String(line.id)}, not ${appId}`);
+                app = line;
+                await json(await target('POST', '/admin/v1/import', { id: appId, name: line.name, createdAt: line.createdAt, policy: line.policy ?? null }), 'Starting the import');
+                begun = true;
+                log(`importing "${String(line.name)}" (${appId})`);
+                continue;
+            }
+            if (!app) throw new MoveError('The export does not start with the application');
+            if (line.t === 'end') {
+                end = line;
+                continue;
+            }
+            if (end) throw new MoveError('The export continues after its end');
+            if (line.t === 'log') {
+                heads.push({ id: String(line.id), headVersion: Number(line.headVersion) });
+                counted.logs += 1;
+            } else if (line.t === 'events') {
+                counted.events += (line.events as unknown[]).length;
+            } else if (line.t === 'requests') {
+                counted.requests += (line.requests as unknown[]).length;
+            }
+            const size = JSON.stringify(line).length;
+            if (batch.length > 0 && (batch.length >= maxRecords || batchBytes + size > maxBytes)) await flush();
+            batch.push(line);
+            batchBytes += size;
+        }
+        if (!app || !end) throw new MoveError('The export was cut short: it has no end record');
+        for (const key of ['logs', 'events', 'requests'] as const) {
+            if (Number(end[key]) !== counted[key]) throw new MoveError(`The export says ${String(end[key])} ${key} but carried ${counted[key]}`);
+        }
+        await flush();
+
+        await json(await target('POST', `/admin/v1/apps/${appId}/import/finish`, { logs: heads }), 'Finishing the import');
+        const [before, after] = await Promise.all([
+            json<{ logs: LogChecksum[] }>(await source('GET', `/admin/v1/apps/${appId}/checksums`), 'Reading the source checksums'),
+            json<{ logs: LogChecksum[] }>(await target('GET', `/admin/v1/apps/${appId}/checksums`), 'Reading the destination checksums'),
+        ]);
+        const problems = sameChecksums(before.logs, after.logs);
+        if (problems.length) {
+            // The destination is open now and cannot be aborted: the operator must discard it.
+            throw new MoveError(`The destination differs from the source:\n  - ${problems.join('\n  - ')}`);
+        }
+        log(`verified ${before.logs.length} log(s), ${counted.events} event(s)`);
+        return {
+            appId, name: String(app.name), ...counted, checksums: after.logs, movedAt: (options.now ?? (() => new Date()))().toISOString(),
+        };
+    } catch (error) {
+        if (begun) {
+            // Best effort: a finished import refuses this, and then the error above says what differs.
+            await target('POST', `/admin/v1/apps/${appId}/import/abort`).catch(() => undefined);
+        }
+        throw error;
+    }
+}

package/src/plan.ts

@@ -0,0 +1,160 @@
+/**
+ * `hearthlog plan`: what deploying one tenant would create, in what order, and
+ * what stops it. Pure: the caller resolves names from `tenants.json`, the
+ * tenant files, and the module manifests, so the planner can be tested and
+ * run with no credentials and no network.
+ */
+
+export type StepId = 'resources' | 'ledger' | 'ledger-app' | 'frontend' | 'verify';
+
+export interface PlanModule {
+    id: string;
+    version: string;
+}
+
+/** A name the tenant's Workers bind or create, with whether it holds data that must survive. */
+export interface PlannedResource {
+    kind: 'frontend-worker' | 'ledger-worker' | 'calendar-feed-worker' | 'public-worker' | 'r2-bucket' | 'ledger-app' | 'access-app';
+    name: string;
+    /** Never deleted by apply, whatever the plan says. */
+    stateful: boolean;
+    billable: 'workers' | 'durable-objects' | 'r2' | 'access';
+}
+
+export interface PlannedStep {
+    id: StepId;
+    summary: string;
+    /** The step's work is the first mint of a credential: it must never run again once recorded. */
+    mintsCredentials: boolean;
+}
+
+export interface TenantResources {
+    ledgerWorker: string;
+    /** R2 bindings the tenant's gateway gets, by Worker binding name. */
+    buckets: Array<{ binding: string; bucket: string }>;
+    calendarFeedsBucket: string;
+    calendarPublicWorker: string;
+    /** Anonymous Workers a module deploys beside the gateway (Gallery's public pages). */
+    publicWorkers: string[];
+}
+
+export interface PlanInput {
+    site: {
+        id: string;
+        origin: string;
+        features: string[];
+        authorizedEmails: string[];
+        ledgerAppName: string;
+        /** Null: the site is served by the shared Ledger and buckets. */
+        deployment: { resourcePrefix: string; accountId?: string } | null;
+    };
+    modules: PlanModule[];
+    resources: TenantResources;
+    accessTeamDomain: string;
+    /** Every other site's resources, and the shared stack's, for the isolation check. */
+    others: Array<{ id: string; resources: TenantResources }>;
+    /** Absent in a repository with no shared stack (a site that owns its stack and is the only one in it). */
+    shared?: TenantResources;
+}
+
+export interface DeploymentPlan {
+    siteId: string;
+    origin: string;
+    topology: 'dedicated' | 'shared';
+    accountId: string | null;
+    modules: PlanModule[];
+    resources: PlannedResource[];
+    steps: PlannedStep[];
+    /** Anything here stops `hearthlog apply`. */
+    problems: string[];
+    /** Worth reading, not blocking. */
+    warnings: string[];
+}
+
+function owned(resources: TenantResources): Map<string, string> {
+    const names = new Map<string, string>();
+    names.set(resources.ledgerWorker, 'ledger Worker');
+    for (const { bucket } of resources.buckets) names.set(bucket, 'bucket');
+    names.set(resources.calendarFeedsBucket, 'bucket');
+    names.set(resources.calendarPublicWorker, 'Worker');
+    for (const worker of resources.publicWorkers) names.set(worker, 'Worker');
+    return names;
+}
+
+/** The tenant's own names that another tenant (or the shared stack) also holds. */
+export function isolationProblems(input: Pick<PlanInput, 'site' | 'resources' | 'others' | 'shared'>): string[] {
+    const mine = owned(input.resources);
+    const problems: string[] = [];
+    const against = [...input.others.map((other) => ({ label: `site "${other.id}"`, resources: other.resources })), ...(input.shared ? [{ label: 'the shared stack', resources: input.shared }] : [])];
+    for (const other of against) {
+        // A tenant on the shared stack is declared to share it; only a dedicated one must not.
+        if (!input.site.deployment) continue;
+        const theirs = owned(other.resources);
+        for (const [name, kind] of mine) {
+            if (theirs.has(name)) problems.push(`${kind} "${name}" is also used by ${other.label}: this tenant's gateway would reach its data`);
+        }
+    }
+    if (input.site.deployment) {
+        const prefix = `${input.site.deployment.resourcePrefix}-`;
+        for (const [name, kind] of mine) {
+            if (!name.startsWith(prefix)) problems.push(`${kind} "${name}" does not start with the resource prefix "${prefix}"`);
+        }
+    }
+    return problems;
+}
+
+export function planDeployment(input: PlanInput): DeploymentPlan {
+    const { site, resources } = input;
+    const dedicated = site.deployment !== null;
+    const problems = isolationProblems(input);
+    const warnings: string[] = [];
+    if (!input.accessTeamDomain) problems.push('No Cloudflare Access team is configured: the site would be deployed unprotected');
+    if (site.authorizedEmails.length === 0) problems.push('No user is allowed in: the Access policy would be empty');
+    if (dedicated && !site.deployment!.accountId) warnings.push('deployment.json names no accountId, so the CLI login cannot be checked against the intended account');
+
+    const planned: PlannedResource[] = [
+        { kind: 'frontend-worker', name: site.id, stateful: false, billable: 'workers' },
+        { kind: 'access-app', name: site.origin, stateful: false, billable: 'access' },
+        { kind: 'ledger-app', name: site.ledgerAppName, stateful: true, billable: 'durable-objects' },
+        { kind: 'calendar-feed-worker', name: resources.calendarPublicWorker, stateful: false, billable: 'workers' },
+        { kind: 'r2-bucket', name: resources.calendarFeedsBucket, stateful: true, billable: 'r2' },
+        ...resources.buckets.map(({ bucket }): PlannedResource => ({ kind: 'r2-bucket', name: bucket, stateful: true, billable: 'r2' })),
+        ...resources.publicWorkers.map((name): PlannedResource => ({ kind: 'public-worker', name, stateful: false, billable: 'workers' })),
+    ];
+    if (dedicated) planned.unshift({ kind: 'ledger-worker', name: resources.ledgerWorker, stateful: true, billable: 'durable-objects' });
+
+    const steps: PlannedStep[] = [
+        { id: 'resources', summary: 'Create the buckets and the Access application (existing ones are kept)', mintsCredentials: false },
+        ...(dedicated ? [{ id: 'ledger' as const, summary: `Deploy ${resources.ledgerWorker} and generate its administrator token and signing key once`, mintsCredentials: true }] : []),
+        { id: 'ledger-app', summary: `Register the Ledger application "${site.ledgerAppName}" with the site's event policy and give the gateway its token (an existing application keeps its token and policy)`, mintsCredentials: true },
+        { id: 'frontend', summary: 'Build and deploy the gateway and the public Workers', mintsCredentials: false },
+        { id: 'verify', summary: 'Check that the origin is not served without signing in', mintsCredentials: false },
+    ];
+    return {
+        siteId: site.id,
+        origin: site.origin,
+        topology: dedicated ? 'dedicated' : 'shared',
+        accountId: site.deployment?.accountId ?? null,
+        modules: input.modules,
+        resources: planned,
+        steps,
+        problems,
+        warnings,
+    };
+}
+
+export function renderPlan(plan: DeploymentPlan): string {
+    const lines = [
+        `Tenant ${plan.siteId} (${plan.topology}) at ${plan.origin}`,
+        `Modules: ${plan.modules.map((module) => `${module.id}@${module.version}`).join(', ') || 'none'}`,
+        '',
+        'Resources:',
+        ...plan.resources.map((resource) => `  ${resource.kind.padEnd(20)} ${resource.name}${resource.stateful ? '  (kept; never deleted)' : ''}  [${resource.billable}]`),
+        '',
+        'Steps:',
+        ...plan.steps.map((step, index) => `  ${index + 1}. ${step.id}: ${step.summary}`),
+    ];
+    if (plan.warnings.length) lines.push('', 'Warnings:', ...plan.warnings.map((warning) => `  - ${warning}`));
+    if (plan.problems.length) lines.push('', 'Problems (apply refuses until fixed):', ...plan.problems.map((problem) => `  - ${problem}`));
+    return `${lines.join('\n')}\n`;
+}

package/src/public-workers/build-gallery-public.ts

@@ -0,0 +1,114 @@
+/**
+ * `hearthlog gallery-public:build [--site <id>]`: build a stack's public Gallery Worker.
+ *
+ * The Gallery module ships the Worker's source (`public/` in its package). The browser bundle is built first, then the
+ * Worker, which renders the same Svelte components on the server and carries that bundle to serve it. Both go into
+ * `dist/` beside the stack's generated `wrangler.jsonc` (`.generated/shared/gallery-public/` or the site's own).
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadModules } from "../compose/compose-modules.js";
+import { generateHostConfigs, hostWorkerDirectory } from "../tenants/host-configs.js";
+import { loadTenantConfig } from "../tenants/tenant-config.js";
+
+const ASSETS_MODULE = "\0gallery-public-client-assets";
+
+export async function buildGalleryPublic(stack: string): Promise<string> {
+    await generateHostConfigs(stack);
+    const output = hostWorkerDirectory(stack, "gallery-public");
+    // A site without the Gallery has no public Gallery Worker to build.
+    if (!existsSync(join(output, "wrangler.jsonc"))) {
+        console.log(`The ${stack} stack has no public Gallery Worker.`);
+        return output;
+    }
+    const module = loadModules().find(({ manifest }) => manifest.publicWorker?.name === "gallery");
+    if (!module) throw new Error("No installed module has a public Gallery Worker");
+    const source = join(module.directory, "public");
+    const clientOut = join(output, "dist", "client");
+
+    // Loaded here, not at the top: only a site that builds the Worker needs them.
+    const { build } = await import("vite");
+    const { svelte } = await import("@sveltejs/vite-plugin-svelte");
+    const { default: Icons } = await import("unplugin-icons/vite");
+
+    /** Replaces the empty `client-assets` module with the built browser files. */
+    const clientAssets = {
+        name: "gallery-public-client-assets",
+        enforce: "pre" as const,
+        resolveId(id: string, importer?: string) {
+            return id === "./client-assets" && importer?.startsWith(source) ? ASSETS_MODULE : undefined;
+        },
+        load(id: string) {
+            if (id !== ASSETS_MODULE) return undefined;
+            const manifest = JSON.parse(readFileSync(join(clientOut, ".vite/manifest.json"), "utf8")) as Record<string, { file: string; css?: string[] }>;
+            const entry = manifest["app/client.ts"];
+            if (!entry) throw new Error("Build the public Gallery client first.");
+            const asset = (file: string, type: string) => ({ path: `/_app/${file.split("/").pop()}`, body: readFileSync(join(clientOut, file), "utf8"), type });
+            return `export const clientAssets = ${JSON.stringify({
+                script: asset(entry.file, "text/javascript; charset=utf-8"),
+                styles: (entry.css ?? []).map((file) => asset(file, "text/css; charset=utf-8")),
+            })};`;
+        },
+    };
+
+    const common = {
+        root: source,
+        configFile: false as const,
+        publicDir: false as const,
+        logLevel: "warn" as const,
+    };
+    await build({
+        ...common,
+        plugins: [svelte({ configFile: false }), Icons({ compiler: "svelte" })],
+        build: {
+            outDir: clientOut,
+            emptyOutDir: true,
+            manifest: true,
+            target: "es2022",
+            rolldownOptions: {
+                input: "app/client.ts",
+                output: { entryFileNames: "assets/app-[hash].js", assetFileNames: "assets/app-[hash][extname]" },
+            },
+        },
+    });
+    await build({
+        ...common,
+        plugins: [svelte({ configFile: false }), Icons({ compiler: "svelte" }), clientAssets],
+        // Resolve Svelte's server runtime (its `worker` export), never the browser one.
+        ssr: { target: "webworker", noExternal: true, resolve: { conditions: ["worker", "workerd", "svelte", "module", "import", "default"] } },
+        build: {
+            ssr: "index.ts",
+            outDir: join(output, "dist", "worker"),
+            emptyOutDir: true,
+            target: "es2022",
+            minify: true,
+            // Workers provide AsyncLocalStorage under the `nodejs_als` flag.
+            rolldownOptions: { external: ["node:async_hooks"], output: { entryFileNames: "index.js", format: "es" } },
+        },
+    });
+    return output;
+}
+
+/** The stack a command works on: `--site <id>` when that site has its own stack, else the shared one. */
+export async function stackFor(argv: string[]): Promise<string> {
+    const flag = argv.indexOf("--site");
+    const id = (flag >= 0 ? argv[flag + 1] : undefined) ?? "";
+    if (!id) return "shared";
+    const { sites } = await loadTenantConfig(undefined, { only: id });
+    const site = sites.find((candidate) => candidate.id === id);
+    if (!site) throw new Error(`Unknown site id "${id}"`);
+    return site.deployment ? id : "shared";
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    stackFor(process.argv.slice(2))
+        .then(buildGalleryPublic)
+        .then((output) => console.log(`Built the public Gallery Worker in ${output}`))
+        .catch((error: unknown) => {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        });
+}

package/src/public-workers/calendar-public-config.ts

@@ -0,0 +1,27 @@
+/** The public calendar feed Worker's config (generated by `host-configs.ts`). */
+import { siteBindingName } from '@hearthlog/contracts/calendar/feed-contract';
+import type { InfrastructureDefinition } from '../tenants/tenant-config.js';
+import { WRANGLER_BASE } from '../tenants/wrangler-base.js';
+
+/** Rate-limit namespace ids only have to be unique in the account. */
+const LIMITER = { name: 'FEEDS_LIMITER', namespace_id: '21002', simple: { limit: 60, period: 60 } };
+
+/**
+ * The feed Worker: the feed bucket and one renderer service binding per site it serves (the sites of the shared stack,
+ * or the one site of an own stack). It holds nothing else of a site and has no Ledger credential.
+ */
+export function buildCalendarPublicConfig(infrastructure: InfrastructureDefinition, siteIds: readonly string[]) {
+    return {
+        name: infrastructure.calendarPublicWorker,
+        main: './index.ts',
+        compatibility_date: WRANGLER_BASE.compatibility_date,
+        workers_dev: true,
+        preview_urls: false,
+        // The feed URL carries the secret, and invocation logs record request paths.
+        observability: { enabled: false },
+        vars: { PUBLIC_ORIGIN: infrastructure.calendarPublicOrigin },
+        r2_buckets: [{ binding: 'CALENDAR_FEEDS', bucket_name: infrastructure.calendarFeedsBucket }],
+        services: siteIds.map((id) => ({ binding: siteBindingName(id), service: id, entrypoint: 'CalendarFeedRenderer' })),
+        ratelimits: [LIMITER],
+    };
+}