@hearthlog/tooling 0.0.0-stage → 0.1.1

package/src/generate/generate-tenant.ts

@@ -0,0 +1,161 @@
+#!/usr/bin/env npx tsx
+/**
+ * Tenant Code Generator
+ *
+ * Resolves one site from tenants.json and emits the runtime module the
+ * browser app consumes, plus the tenant-branded app shell. The site is
+ * selected with VITE_STOR_TENANT (default: "st").
+ *
+ * Usage: VITE_STOR_TENANT=bravo pnpm build:generated
+ *
+ * Generated files, in .generated/sites/<id>/:
+ * - tenant.ts   (tenant module consumed by the app as $tenant/generated)
+ * - app.html    (boot shell branded from src/app.template.html)
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import { siteDirectory } from "../compose/compose-modules.js";
+import { packageDirectory } from "../host/write-host.js";
+import {
+    loadTenantConfig,
+    siteById,
+    validateCrossSite,
+    REPOSITORY_ROOT,
+    TenantConfigError,
+} from "../tenants/tenant-config.js";
+import { generateHostConfigs } from "../tenants/host-configs.js";
+import { generateTenantWranglerConfigs } from "../tenants/wrangler-config.js";
+import { brandMarkMaskUrl, wordmarkParts } from "@hearthlog/contracts/tenant/brand";
+import {
+    themeVariablesCss,
+    themeVariablesFor,
+} from "@hearthlog/contracts/tenant/theme";
+
+const APP_TEMPLATE_PATH = join(packageDirectory("@hearthlog/shell"), "src/app.template.html");
+
+export interface GenerateTenantOptions {
+    outputPath?: string;
+    appOutputPath?: string;
+    generateWranglerConfigs?: boolean;
+}
+
+function repositoryPath(path: string): string {
+    return isAbsolute(path) ? path : resolve(REPOSITORY_ROOT, path);
+}
+
+export async function generateTenant(
+    siteId: string,
+    options: GenerateTenantOptions = {},
+): Promise<{ outputPath: string; appOutputPath: string; wranglerConfigs: string[] }> {
+    const outputPath = repositoryPath(
+        options.outputPath ?? join(siteDirectory(siteId), "tenant.ts"),
+    );
+    const appOutputPath = repositoryPath(
+        options.appOutputPath ?? join(siteDirectory(siteId), "app.html"),
+    );
+    const { sites, infrastructure } = await loadTenantConfig(undefined, { only: siteId });
+    validateCrossSite(sites);
+    const site = siteById(sites, siteId);
+
+    const content = `/**
+ * AUTO-GENERATED by packages/tooling/src/generate/generate-tenant.ts — do not edit.
+ *
+ * Source: tenants.json (site "${site.id}").
+ * Regenerate with: VITE_STOR_TENANT=${site.id} pnpm build:generated
+ */
+
+export const TENANT_ID = "${site.id}" as const;
+
+export const TENANT = {
+    id: "${site.id}",
+    ledgerAppName: "${site.ledgerAppName}",
+    title: ${JSON.stringify(site.title)},
+    home: "${site.home}",
+    features: ${JSON.stringify(site.features)} as const,
+    ai: ${JSON.stringify(site.ai)} as const,
+    developerNavVisible: ${site.developerNavVisible},
+    entitiesNavVisible: ${site.entitiesNavVisible},
+    dynamicEntities: ${site.dynamicEntities},
+    theme: ${JSON.stringify(site.theme)} as { accent?: string },
+    admin: ${site.admin},
+    hostname: ${JSON.stringify(site.hostname)},
+    kalApiOrigin: ${JSON.stringify(infrastructure.kalApiOrigin ?? "")}
+} as const;
+`;
+
+    await mkdir(dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, content, "utf8");
+
+// Brand the boot shell so the pre-app skeleton matches the tenant. The
+// template keeps explicit %%BRAND_*%% markers; everything else stays
+// byte-identical across tenants.
+const template = await readFile(APP_TEMPLATE_PATH, "utf8");
+const lightTheme = themeVariablesFor(site.theme.accent, "light");
+const darkTheme = themeVariablesFor(site.theme.accent, "dark");
+const themeStyle = themeVariablesCss(lightTheme);
+const brandable = template
+    .replaceAll("%%BRAND_MARK_MASK%%", brandMarkMaskUrl())
+    .replaceAll("%%BRAND_WORDMARK%%", wordmarkHtml(site.title))
+    .replaceAll("%%BRAND_TITLE%%", escapeHtml(site.title))
+    .replaceAll("%%BRAND_ID%%", escapeHtml(site.id))
+    .replaceAll("%%BRAND_THEME_COLOR%%", escapeHtml(lightTheme["--stor-theme-color"]))
+    .replaceAll("%%BRAND_DARK_THEME%%", escapeHtml(themeVariablesCss(darkTheme)))
+    .replaceAll("%%BRAND_THEME%%", escapeHtml(themeStyle));
+if (/%%BRAND_[A-Z_]+%%/.test(brandable)) {
+    throw new TenantConfigError(
+        "app.template.html still contains unresolved %%BRAND_*%% markers",
+    );
+}
+    await mkdir(dirname(appOutputPath), { recursive: true });
+    await writeFile(appOutputPath, brandable, "utf8");
+
+    // The site's Worker config in its own generated folder, and the Workers of its stack (the Ledger and the public
+    // calendar and Gallery Workers), from the tenant files.
+    const wranglerConfigs = options.generateWranglerConfigs === false
+        ? []
+        : [
+            ...(await generateTenantWranglerConfigs(site.id)),
+            ...(await generateHostConfigs(site.deployment ? site.id : "shared")),
+        ];
+
+    console.log(
+        `Generated tenant module for "${site.id}" (${site.features.length} ` +
+            `features, home ${site.home}, accent ${site.theme.accent ?? "default"}) ` +
+            `at ${outputPath}`,
+    );
+    if (wranglerConfigs.length > 0) {
+        console.log(
+            `Generated ${wranglerConfigs.length} tenant wrangler config(s): ` +
+                wranglerConfigs
+                    .map((path) => path.replace(`${REPOSITORY_ROOT}/`, ""))
+                    .join(", "),
+        );
+    }
+    return { outputPath, appOutputPath, wranglerConfigs };
+}
+
+if (process.env.STOR_SKIP_TENANT_GENERATION !== "1") {
+    await generateTenant(process.env.VITE_STOR_TENANT?.trim() || "st", {
+        generateWranglerConfigs: process.env.STOR_WRANGLER_CONFIGS !== "0",
+    });
+}
+
+/** The tenant title with the brand mark in place of its first "s". */
+function wordmarkHtml(title: string): string {
+    const parts = wordmarkParts(title);
+    if (!parts) return escapeHtml(title);
+    return (
+        `<span class="stor-wordmark" role="img" aria-label="${escapeHtml(title)}">` +
+        `${escapeHtml(parts.before)}<span class="stor-mark"></span>${escapeHtml(parts.after)}</span>`
+    );
+}
+
+function escapeHtml(value: string): string {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}

package/src/host/core-routes.ts

@@ -0,0 +1,39 @@
+/**
+ * The host's own routes: the thin files every site shares. Each page renders a page of `@hearthlog/shell`,
+ * and each loader re-declares the shell's `load` (a plain `export { load } from` makes SvelteKit's static
+ * page-option analysis give up and import the module while building) next to the literal page options.
+ * `pnpm build:generated` writes them into `.generated/routes/`, beside the composed module routes.
+ */
+
+export interface RouteFile {
+    /** Relative to the routes directory. */
+    path: string;
+    content: string;
+}
+
+export const CORE_ROUTE_FILES: readonly RouteFile[] = [
+    { path: "+error.svelte", content: "<script lang=\"ts\">\n    import ErrorPage from '@hearthlog/shell/pages/error/ErrorPage.svelte';\n</script>\n\n<ErrorPage />\n" },
+    { path: "+layout.svelte", content: "<script lang=\"ts\">\n    import '../app.css';\n    import ShellLayout from '@hearthlog/shell/pages/layout/Layout.svelte';\n    // The tenant's composed modules: `hearthlog compose` writes this file; the shell does not know them.\n    import { attentionContributions, startModules } from './(modules)/startup';\n\n    let { data, children } = $props();\n</script>\n\n<ShellLayout {data} {children} startup={{ attentionContributions, startModules }} />\n" },
+    { path: "+layout.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/layout/load.js';\n\nexport const load = shellLoad;\n\nexport const ssr = false;\nexport const prerender = false;\n" },
+    { path: "+page.svelte", content: "<p role=\"status\">Opening your last section\u2026</p>\n" },
+    { path: "+page.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/redirects/start.js';\n\nexport const load = shellLoad;\n\nexport const ssr = false;\nexport const prerender = false;\n" },
+    { path: "calendar/+page.svelte", content: "<script lang=\"ts\">\n    import Page from '@hearthlog/shell/pages/calendar/Page.svelte';\n\n    let { data } = $props();\n</script>\n\n<Page {data} />\n" },
+    { path: "calendar/+page.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/calendar/load.js';\n\nexport const load = shellLoad;\n" },
+    { path: "developer/+page.svelte", content: "<script lang=\"ts\">\n    import Page from '@hearthlog/shell/pages/developer/Page.svelte';\n\n    let { data } = $props();\n</script>\n\n<Page {data} />\n" },
+    { path: "developer/+page.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/developer/load.js';\n\nexport const load = shellLoad;\n" },
+    { path: "entities/+page.svelte", content: "<script lang=\"ts\">\n    import Page from '@hearthlog/shell/pages/entities/Page.svelte';\n\n    let { data } = $props();\n</script>\n\n<Page {data} />\n" },
+    { path: "entities/+page.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/entities/load.js';\n\nexport const load = shellLoad;\n" },
+    { path: "entities/[type]/+page.svelte", content: "<script lang=\"ts\">\n    import Page from '@hearthlog/shell/pages/entity/Page.svelte';\n\n    let { data } = $props();\n</script>\n\n<Page {data} />\n" },
+    { path: "entities/[type]/+page.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/entity/load.js';\n\nexport const load = shellLoad;\n" },
+    { path: "history/+page.svelte", content: "<svelte:head><title>Opening history</title></svelte:head>\n\n<p class=\"sr-only\" role=\"status\">Opening history in the sidebar\u2026</p>\n" },
+    { path: "history/+page.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/redirects/history.js';\n\nexport const load = shellLoad;\n" },
+    { path: "today/+page.ts", content: "import { load as shellLoad } from '@hearthlog/shell/pages/redirects/today.js';\n\nexport const load = shellLoad;\n\nexport const ssr = false;\nexport const prerender = false;\n" },
+];
+
+/** The URL paths the core routes serve; no module may take one. */
+export const CORE_ROUTE_PATHS: readonly string[] = [...new Set(
+    CORE_ROUTE_FILES.filter(({ path }) => /(^|\/)\+page\.(svelte|ts)$/.test(path)).map(({ path }) => {
+        const directory = path.replace(/\/?\+page\.(svelte|ts)$/, '');
+        return `/${directory}`;
+    }),
+)].sort();

package/src/host/write-host.ts

@@ -0,0 +1,119 @@
+#!/usr/bin/env npx tsx
+/**
+ * Write the host files every site shares into the gitignored `.generated/`, for the SvelteKit app:
+ *
+ *   routes/            the core routes (a table in this package) and the site's own `src/routes/`;
+ *                      `pnpm build:generated` composes the site's module routes into `routes/(modules)/` afterwards
+ *   app.css            Tailwind, the design system's and the shell's styles, the enabled modules' stylesheets
+ *   service-worker/    the entry SvelteKit bundles as the service worker (the code is `@hearthlog/shell`)
+ *   app.d.ts, microlighter.d.ts   ambient types
+ *   tsconfig.json      the paths a site's tsconfig extends (`$tenant/generated` is the site's tenant module)
+ *   static/            the shell's core static files and the site's own `static/`, with only this site's icons
+ *
+ * Usage: pnpm build:generated (runs this after the catalog is written)
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { hostRoot } from "../root.js";
+import { CORE_ROUTE_FILES } from "./core-routes.js";
+
+const ROOT = hostRoot();
+const GENERATED = join(ROOT, ".generated");
+const TEMPLATES = resolve(dirname(fileURLToPath(import.meta.url)), "../../templates/host");
+
+/** The directory of an installed package, found from the host so a site resolves its own copy. */
+export function packageDirectory(name: string): string {
+    return dirname(createRequire(join(ROOT, "package.json")).resolve(`${name}/package.json`));
+}
+
+export function renderAppCss(hasSiteSources: boolean): string {
+    return [
+        "/* AUTO-GENERATED by packages/tooling/src/host/write-host.ts. Do not edit. */",
+        "@import 'tailwindcss' source('./');",
+        "@import '@hearthlog/ui/styles/index.css';",
+        "@import '@hearthlog/shell/styles/index.css';",
+        "/* The enabled modules' stylesheets and Tailwind sources: written beside this file by the composer. */",
+        "@import './module-sources.generated.css';",
+        // The generated folder is gitignored, which Tailwind's automatic detection honours; name its routes.
+        "@source './routes';",
+        ...(hasSiteSources ? ["@source '../src';"] : []),
+        "",
+    ].join("\n");
+}
+
+export function renderServiceWorkerEntry(): string {
+    return [
+        "// AUTO-GENERATED by packages/tooling/src/host/write-host.ts. Do not edit.",
+        "// SvelteKit bundles this reserved entry as the service worker; the code is the shell's.",
+        "import '@hearthlog/shell/service-worker/index.js';",
+        "",
+    ].join("\n");
+}
+
+function filesIn(directory: string): string[] {
+    if (!existsSync(directory)) return [];
+    return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.name !== ".DS_Store").flatMap((entry) => {
+        const path = join(directory, entry.name);
+        return entry.isDirectory() ? filesIn(path) : [path];
+    });
+}
+
+async function writeRoutes(): Promise<void> {
+    const routes = join(GENERATED, "routes");
+    await rm(routes, { recursive: true, force: true });
+    const written = new Set<string>();
+    for (const { path, content } of CORE_ROUTE_FILES) {
+        await mkdir(dirname(join(routes, path)), { recursive: true });
+        await writeFile(join(routes, path), content, "utf8");
+        written.add(path);
+    }
+    const own = join(ROOT, "src", "routes");
+    for (const file of filesIn(own)) {
+        const path = relative(own, file).split(sep).join("/");
+        if (path.startsWith("(modules)/")) throw new Error(`src/routes/${path}: the (modules) group belongs to the composed module routes`);
+        if (written.has(path)) throw new Error(`src/routes/${path} collides with a core route`);
+        await mkdir(dirname(join(routes, path)), { recursive: true });
+        await cp(file, join(routes, path));
+    }
+}
+
+async function writeStatic(siteId: string): Promise<void> {
+    const target = join(GENERATED, "static");
+    await rm(target, { recursive: true, force: true });
+    await cp(join(packageDirectory("@hearthlog/shell"), "static"), target, { recursive: true });
+    // The host's own `static/` is shared by every site; the site's `tenants/<id>/static/` (its icon set, any other
+    // brand file) lands on top of it at the same paths.
+    for (const own of [join(ROOT, "static"), join(ROOT, "tenants", siteId, "static")]) {
+        for (const file of filesIn(own)) {
+            const path = relative(own, file).split(sep).join("/");
+            await mkdir(dirname(join(target, path)), { recursive: true });
+            await cp(file, join(target, path));
+        }
+    }
+}
+
+export async function writeHost(siteId: string): Promise<void> {
+    await writeRoutes();
+    await writeFile(join(GENERATED, "app.css"), renderAppCss(existsSync(join(ROOT, "src")) && statSync(join(ROOT, "src")).isDirectory()), "utf8");
+    await mkdir(join(GENERATED, "service-worker"), { recursive: true });
+    await writeFile(join(GENERATED, "service-worker", "index.ts"), renderServiceWorkerEntry(), "utf8");
+    await writeFile(join(GENERATED, "service-worker", "tsconfig.json"), `${JSON.stringify({ extends: "$app/tsconfig/service-worker" }, null, "\t")}\n`, "utf8");
+    for (const name of ["app.d.ts", "microlighter.d.ts"]) {
+        await writeFile(join(GENERATED, name), await readFile(join(TEMPLATES, `${name}.txt`), "utf8"), "utf8");
+    }
+    await writeFile(join(GENERATED, "tsconfig.json"), `${JSON.stringify({ compilerOptions: { paths: { "$tenant/generated": [`./sites/${siteId}/tenant.ts`] } } }, null, "\t")}\n`, "utf8");
+    await writeStatic(siteId);
+    console.log(`Wrote the host files for ${siteId}.`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    writeHost(process.env.VITE_STOR_TENANT?.trim() || "st").catch((error: unknown) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { planDeployment, isolationProblems, renderPlan } from './plan.js';
+export type { DeploymentPlan, PlanInput, PlanModule, PlannedResource, PlannedStep, StepId, TenantResources } from './plan.js';
+export { newReceipt, parseReceipt, receiptProblems, recordStep, serializeReceipt, stepDone } from './receipt.js';
+export type { Receipt } from './receipt.js';
+export { ApplyError, runApply } from './apply.js';
+export type { ApplyOptions, ApplyResult, StepExecutor } from './apply.js';
+export { MoveError, moveApplication, sameChecksums } from './move.js';
+export type { AdminCall, LogChecksum, MoveOptions, MoveReport } from './move.js';

package/src/init/check-module.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env npx tsx
+/**
+ * `hearthlog check-module [<directory>] [--work <dir>] [--keep] [--overrides <file.json>]`
+ *
+ * Proves that a module repository composes into a site and passes its tests: it generates a throwaway site that
+ * enables the module (the starter `hearthlog init` writes, the module installed from the directory), installs it
+ * against the platform range, and builds it, which runs the composer, the boundary checks and the Ledger contract
+ * generation. Then it runs the module's own unit tests (`vitest`, from the module's directory) with the site's generated
+ * files standing in for `@hearthlog/generated`, which the platform packages import and only a site can write.
+ * `--overrides` is a JSON object of package name to `file:` tarball, used to run against a platform that is not
+ * published yet.
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadModuleAt } from "../compose/compose-modules.js";
+import { renderSite } from "./init.js";
+
+export interface CheckModuleOptions {
+    directory: string;
+    work?: string;
+    keep?: boolean;
+    overrides?: Record<string, string>;
+}
+
+function run(command: string, args: string[], cwd: string): void {
+    const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+    if (result.status !== 0) throw new Error(`${command} ${args.join(" ")} failed in ${cwd}`);
+}
+
+/** Writes the site into `work` and returns the module's package name. */
+export function assembleCheckSite(options: Required<Pick<CheckModuleOptions, "directory" | "work">> & Pick<CheckModuleOptions, "overrides">): string {
+    const directory = resolve(options.directory);
+    const loaded = loadModuleAt(directory);
+    const name = loaded.manifest.package;
+    for (const [path, content] of renderSite({ directory: options.work, id: "st", modules: [name], available: [loaded] })) {
+        const target = join(options.work, path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, content, "utf8");
+    }
+    const manifestPath = join(options.work, "package.json");
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { dependencies: Record<string, string> };
+    manifest.dependencies[name] = `file:${directory}`;
+    const overrides = options.overrides ?? {};
+    // A peer the module needs is the site's to provide; without a published platform it comes from the tarball.
+    const peers = Object.keys((JSON.parse(readFileSync(join(directory, "package.json"), "utf8")) as { peerDependencies?: Record<string, string> }).peerDependencies ?? {});
+    for (const [dependency, value] of Object.entries(overrides)) {
+        if (dependency !== name && (dependency in manifest.dependencies || peers.includes(dependency))) manifest.dependencies[dependency] = value;
+    }
+    writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    if (Object.keys(overrides).length > 0) {
+        // pnpm 10 reads overrides from pnpm-workspace.yaml, not from package.json.
+        appendFileSync(join(options.work, "pnpm-workspace.yaml"), `\noverrides:\n${Object.entries(overrides).map(([dependency, value]) => `  '${dependency}': '${value}'`).join("\n")}\n`);
+    }
+    return name;
+}
+
+/** What the SvelteKit modules the platform imports (`$app/*`) give a unit test: nothing that runs in a browser. */
+const APP_STUB = `const noop = () => {};
+export const goto = async () => {}, invalidate = async () => {}, invalidateAll = async () => {}, preloadData = async () => ({}), preloadCode = async () => {};
+export const afterNavigate = noop, beforeNavigate = noop, onNavigate = noop, pushState = noop, replaceState = noop, disableScrollHandling = noop;
+export const browser = false, dev = false, building = false, version = "test";
+export const page = { url: new URL("http://localhost/"), params: {}, route: { id: null }, status: 200, error: null, data: {}, state: {}, form: null };
+export const navigating = { current: null };
+export const base = "", assets = "", resolve = (path) => path, resolveRoute = (path) => path;
+`;
+
+/**
+ * Vitest's configuration for a module's tests, run from the site so that its generated files are the ones used: the
+ * module's directory is the root, the platform source is transformed here (it ships as TypeScript), `$tenant/generated`
+ * is the site's tenant module, `$app/*` is a stub, and `cloudflare:workers` is the platform's stub. The platform
+ * packages import `@hearthlog/generated` through their own `imports` map, which no alias reaches, so the site's
+ * generated package is linked into the module's `node_modules` (see `linkGenerated`).
+ */
+export function testConfig(directory: string, work: string): string {
+    const alias: Array<{ find: string; replacement: string }> = [
+        { find: "$tenant/generated", replacement: join(work, ".generated", "sites", "st", "tenant.ts") },
+        { find: /^\$app\/.*/ as unknown as string, replacement: join(work, "app-stub.mjs") },
+    ];
+    const stub = join(work, "node_modules", "@hearthlog", "cloudflare", "src", "testing", "cloudflare-workers.ts");
+    if (existsSync(stub)) alias.push({ find: "cloudflare:workers", replacement: stub });
+    const options = JSON.stringify({ root: directory, resolve: { alias } }, null, 2).replace('"find": {}', '"find": /^\\$app\\/.*/');
+    // The platform's `.svelte.ts` files use runes, which need the Svelte compiler.
+    return `import { svelte } from "@sveltejs/vite-plugin-svelte";\nconst options = ${options};\noptions.plugins = [svelte()];\noptions.test = { include: ["src/**/*.test.ts"], passWithNoTests: true, server: { deps: { inline: [/@hearthlog\\//] } } };\nexport default options;\n`;
+}
+
+/** Links the site's generated package where the platform packages, installed under the module, look for it; returns the link. */
+function linkGenerated(directory: string, work: string): string {
+    const scope = join(directory, "node_modules", "@hearthlog");
+    mkdirSync(scope, { recursive: true });
+    const link = join(scope, "generated");
+    rmSync(link, { recursive: true, force: true });
+    symlinkSync(join(work, ".generated"), link, "dir");
+    return link;
+}
+
+export function checkModule(options: CheckModuleOptions): void {
+    const work = options.work ? resolve(options.work) : mkdtempSync(join(tmpdir(), "hearthlog-check-module-"));
+    try {
+        const name = assembleCheckSite({ directory: options.directory, work, overrides: options.overrides });
+        console.log(`Checking ${name} in a throwaway site at ${work}`);
+        run("pnpm", ["install", "--no-frozen-lockfile"], work);
+        run("pnpm", ["build"], work);
+        console.log(`${name} composes into a site and builds.`);
+        const config = join(work, "vitest.module.config.mjs");
+        writeFileSync(config, testConfig(resolve(options.directory), work));
+        writeFileSync(join(work, "app-stub.mjs"), APP_STUB);
+        const link = linkGenerated(resolve(options.directory), work);
+        try {
+            // Run from the site (its Vite configuration resolves relative to it) with the module's own vitest.
+            const vitest = join(dirname(createRequire(join(resolve(options.directory), "package.json")).resolve("vitest/package.json")), "vitest.mjs");
+            run(process.execPath, [vitest, "run", "--config", config], work);
+        } finally {
+            rmSync(link, { force: true });
+        }
+        console.log(`${name} passes its unit tests.`);
+    } finally {
+        if (!options.keep) rmSync(work, { recursive: true, force: true });
+    }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        const argv = process.argv.slice(2);
+        const value = (flag: string) => (argv.includes(flag) ? argv[argv.indexOf(flag) + 1] : undefined);
+        const directory = argv.find((argument, index) => !argument.startsWith("--") && !["--work", "--overrides"].includes(argv[index - 1] ?? "")) ?? ".";
+        const overridesFile = value("--overrides");
+        checkModule({
+            directory,
+            work: value("--work"),
+            keep: argv.includes("--keep"),
+            overrides: overridesFile ? (JSON.parse(readFileSync(resolve(overridesFile), "utf8")) as Record<string, string>) : undefined,
+        });
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}

package/src/init/export-tenant.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env npx tsx
+/**
+ * `hearthlog export <id> --out <dir>` (root script `pnpm tenant:export -- <id> --out <dir>`)
+ *
+ * Write the repository of one tenant that owns its stack: what `hearthlog init` renders (package.json, Vite and
+ * TypeScript configuration, pnpm settings, workflow, `.gitignore`) plus the tenant's own `tenants/<id>/`. The shared
+ * account values the site read from this repository's `tenants.json` are written into the exported `deployment.json`
+ * (an own-stack site needs no `tenants.json`, and the shared block names other tenants' resources). Nothing from
+ * `.wrangler/` is copied: no token files, no receipts, no device settings. Like `module:export`, this creates no
+ * repository and touches no remote.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { cp, mkdir, 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 { hostRoot } from "../root.js";
+import { renderSite } from "./init.js";
+
+export interface ExportOptions {
+    /** The host directory (it holds `tenants/<id>/` and, for a shared block, `tenants.json`). */
+    root: string;
+    id: string;
+    out: string;
+    available?: readonly LoadedModule[];
+}
+
+const readJson = (path: string): Record<string, unknown> => JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+
+/** The deployment file with the shared block's account values filled in where the site has none of its own. */
+export function exportedDeployment(deployment: Record<string, unknown>, shared: Record<string, unknown> | undefined): Record<string, unknown> {
+    const result: Record<string, unknown> = { ...deployment };
+    const take = (key: string, value: unknown) => {
+        if (result[key] === undefined && value !== undefined) result[key] = value;
+    };
+    take("workersDevDomain", shared?.workersDevDomain);
+    if (typeof shared?.accessTeamDomain === "string") take("authentication", { provider: "cloudflare-access", teamDomain: shared.accessTeamDomain });
+    for (const key of ["ledgerAdminEmail", "invoiceRendererOrigin", "kalApiOrigin", "accessSessionDuration", "accessGlobalSessionDuration"]) take(key, shared?.[key]);
+    for (const key of ["workersDevDomain", "authentication", "ledgerAdminEmail"]) {
+        if (result[key] === undefined) throw new Error(`tenants/<id>/deployment.json has no ${key} and the shared block has none to give`);
+    }
+    return result;
+}
+
+/** The site's definition with the shared `defaults` it relied on written in, so the repository needs no `tenants.json`. */
+export function exportedTenant(tenant: Record<string, unknown>, defaults: Record<string, unknown> | undefined): Record<string, unknown> {
+    const result: Record<string, unknown> = { ...tenant };
+    for (const [key, value] of Object.entries(defaults ?? {})) {
+        if (result[key] === undefined) result[key] = value;
+    }
+    return result;
+}
+
+function readme(title: string, id: string): string {
+    return `# ${title}
+
+The Hearthlog site \`${id}\`, on its own stack. \`tenants/${id}/\` holds what it enables and the stack it owns
+(\`tenant.json\`, \`deployment.json\`, \`modules.lock.json\`, \`static/\`); everything else the app needs is written by
+\`pnpm build:generated\` into \`.generated/\`.
+
+\`\`\`bash
+pnpm install
+pnpm dev     # builds the generated files, then starts Vite
+pnpm build   # a static build in build/
+pnpm hearthlog plan --site ${id}   # read-only: resources, steps, problems
+\`\`\`
+
+Deploys run from \`.github/workflows/deploy.yml\` in the protected \`${id}\` environment. To run \`hearthlog\` against the
+stack from this machine (plan with the real account, \`apply\`), copy the site's \`.wrangler/tenants/${id}/\` token files
+into this checkout's \`.wrangler/\`; they are never exported or committed.
+`;
+}
+
+export async function exportTenant(options: ExportOptions): Promise<string[]> {
+    const { root, id } = options;
+    const out = resolve(options.out);
+    const tenantDirectory = join(root, "tenants", id);
+    if (!existsSync(join(tenantDirectory, "tenant.json"))) throw new Error(`There is no site "${id}" in ${root}`);
+    if (!existsSync(join(tenantDirectory, "deployment.json"))) throw new Error(`${id} is on the shared stack (no deployment.json): move it to its own stack first`);
+    if (existsSync(out) && readdirSync(out).length > 0) throw new Error(`${out} is not empty`);
+
+    const sharedFile = join(root, "tenants.json");
+    const sharedBlock = existsSync(sharedFile) ? readJson(sharedFile) : {};
+    const shared = sharedBlock.infrastructure as Record<string, unknown> | undefined;
+    const deployment = exportedDeployment(readJson(join(tenantDirectory, "deployment.json")), shared);
+    const tenant = exportedTenant(readJson(join(tenantDirectory, "tenant.json")), sharedBlock.defaults as Record<string, unknown> | undefined);
+    const title = typeof tenant.title === "string" ? tenant.title : id;
+    const lock = readJson(join(tenantDirectory, "modules.lock.json")) as { modules: Array<{ package: string }> };
+
+    const written: string[] = [];
+    const put = async (path: string, content: string) => {
+        const target = join(out, path);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content, "utf8");
+        written.push(path);
+    };
+    for (const [path, content] of renderSite({ directory: out, id, title, modules: lock.modules.map((module) => module.package), available: options.available ?? loadModules() })) {
+        // The tenant's own files replace the starter's, and an own-stack site needs no tenants.json.
+        if (path === "tenants.json" || path.startsWith(`tenants/${id}/`)) continue;
+        await put(path, path === "README.md" ? readme(title, id) : content);
+    }
+    await mkdir(join(out, "tenants", id), { recursive: true });
+    await cp(tenantDirectory, join(out, "tenants", id), { recursive: true, filter: (source) => !/(deployment|tenant)\.json$|\.DS_Store$/.test(source) });
+    await put(`tenants/${id}/tenant.json`, `${JSON.stringify(tenant, null, 2)}\n`);
+    await put(`tenants/${id}/deployment.json`, `${JSON.stringify(deployment, null, 2)}\n`);
+    return written;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        const argv = process.argv.slice(2);
+        const flag = argv.indexOf("--out");
+        const out = flag >= 0 ? argv[flag + 1] : undefined;
+        const id = argv.find((argument, index) => !argument.startsWith("--") && index !== flag + 1);
+        if (!id || !out) throw new Error("Usage: hearthlog export <id> --out <dir>");
+        const written = await exportTenant({ root: hostRoot(), id, out });
+        console.log(`Wrote the repository of ${id} to ${resolve(out)} (${written.length} files plus tenants/${id}/). Next: cd there, pnpm install, pnpm build.`);
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}