@hearthlog/tooling 0.1.4 → 0.1.6

package/bin/hearthlog.mjs

@@ -2,8 +2,8 @@
 // The `hearthlog` command: runs the TypeScript tools through tsx. `build`, `init`, `export`, `check-module`, `lock`, `artifact`, and
 // `gallery-public:build` start before a site has generated files (or write their own), so they run alone; the
 // `apple:*` commands run the build and then the tools of `@hearthlog/native` (a dependency of the site, not of this
-// package); `ensure`, `deploy`, and `deploy-ledger` run the build and then a deploy tool; every other
-// command goes to the CLI.
+// package); `ensure`, `deploy`, and `deploy-ledger` run the build and then a deploy tool; `dev-ledger` runs the build
+// and then the dev server with a local Ledger; every other command goes to the CLI.
 import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
@@ -41,6 +41,12 @@ if (deployTools[command]) {
     process.exit(built === 0 ? (spawnSync(process.execPath, [tsx, source(deployTools[command]), ...rest], { stdio: 'inherit', env }).status ?? 1) : built);
 }
 
+// The dev server with a local Ledger starts that Ledger from the generated configuration: build it first.
+if (command === 'dev-ledger') {
+    const built = run([source('generate/build-generated.ts'), '--quiet']);
+    process.exit(built === 0 ? run([source('dev/dev-ledger.ts'), ...rest]) : built);
+}
+
 // The plan reads the site's generated files too: build them first (a no-op when they are current). `apply` does not,
 // because `apply --skip-build` deploys the release already in place and must not rewrite it.
 if (command === 'plan') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthlog/tooling",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "tsx": "^4.23.15",
-    "@hearthlog/contracts": "0.1.4"
+    "@hearthlog/contracts": "0.1.6"
   },
   "bin": {
     "hearthlog": "./bin/hearthlog.mjs"

package/src/check/check-layers.ts

@@ -12,9 +12,10 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, matchesGlob, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { hostRoot } from "../root.js";
+import { PLATFORM_ROOT } from "../root.js";
 
-const ROOT = hostRoot();
+// Layers are a property of the platform's packages, wherever the check runs from.
+const ROOT = PLATFORM_ROOT;
 const IMPORT = /(?:^|[^\w$.])(?:import|export)\s[^'"]*?from\s+['"]([^'"]+)['"]|import\(\s*['"]([^'"]+)['"]\s*\)|^\s*import\s+['"]([^'"]+)['"]/gm;
 
 export interface LayerConfig {

package/src/check/check-modules.ts

@@ -17,7 +17,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { hostRoot } from "../root.js";
+import { hostRoot, PLATFORM_ROOT } from "../root.js";
 
 const ROOT = hostRoot();
 const SOURCE = /\.(ts|svelte|js)$/;
@@ -89,6 +89,15 @@ export async function loadModuleDomain(root = ROOT): Promise<ModuleDomain> {
     };
 }
 
+/**
+ * The directories a check reads, each with the root it is under: the given ones under the host, or by default the host's
+ * own and the platform's (which are the same checkout unless the host is a site beside the platform's packages).
+ */
+function scanned(root: string, platform: string, given: string[] | undefined, host: string[], platformDirectories: string[]): Array<[string, string]> {
+    if (given) return given.map((directory) => [root, directory]);
+    return [...host.map((directory): [string, string] => [root, directory]), ...platformDirectories.map((directory): [string, string] => [platform, directory])];
+}
+
 const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
 /**
@@ -99,8 +108,10 @@ const escapeRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\
  */
 export function coreNamesNoDomain(
     root = ROOT,
-    directories = ["worker", "ledger/src", "packages/tooling/src/host", "packages/cloudflare/src", "packages/ledger/src", "packages/ledger-admin/src", "packages/contracts/src", "packages/runtime/src", "packages/ui/src"],
+    directories?: string[],
     domain: ModuleDomain = { names: [], eventTypes: [] },
+    /** The platform checkout, when it is not the host (`directories` are then the host's, under `root`). */
+    platform = root,
 ): string[] {
     const modulesDirectory = join(root, "modules");
     const featureIds = (existsSync(modulesDirectory) ? readdirSync(modulesDirectory) : []).flatMap((name) => {
@@ -113,16 +124,16 @@ export function coreNamesNoDomain(
     const quoted = quotedNames.length ? new RegExp(`(["'\`])(${quotedNames.map(escapeRegExp).join("|")})\\1`) : null;
     const events = domain.eventTypes.length ? new RegExp(`\\b(${domain.eventTypes.map(escapeRegExp).join("|")})\\b`) : null;
     const problems: string[] = [];
-    for (const directory of directories) {
-        for (const file of files(join(root, directory))) {
+    for (const [base, directory] of scanned(root, platform, directories, ["ledger/src"], ["packages/tooling/src/host", "packages/cloudflare/src", "packages/ledger/src", "packages/contracts/src", "packages/runtime/src", "packages/ui/src"])) {
+        for (const file of files(join(base, directory))) {
             if (/\.generated\.ts$|\.test\.ts$|\.d\.ts$|[\\/]generated\.ts$|worker-configuration/.test(file) || file.includes(`${sep}generated${sep}`) || file.includes(`${sep}(modules)${sep}`)) continue;
             readFileSync(file, "utf8").split("\n").forEach((line, index) => {
                 // Comments may use a domain as an example.
                 if (/^\s*(\*|\/\/|\/\*)/.test(line)) return;
                 const name = quoted?.exec(line);
-                if (name) problems.push(`${relative(root, file)}:${index + 1}: the core names ${name[1]}${name[2]}${name[1]}`);
+                if (name) problems.push(`${relative(base, file)}:${index + 1}: the core names ${name[1]}${name[2]}${name[1]}`);
                 const event = events?.exec(line);
-                if (event) problems.push(`${relative(root, file)}:${index + 1}: the core names the event type ${event[1]}`);
+                if (event) problems.push(`${relative(base, file)}:${index + 1}: the core names the event type ${event[1]}`);
             });
         }
     }
@@ -135,16 +146,16 @@ export function coreNamesNoDomain(
  * to one would break the day the file is no longer in this tree. The SDK facade, which still reaches
  * into `src/lib` by relative path, and the generated files themselves are exempt.
  */
-export function directGeneratedImports(root = ROOT, directories = ["src", "worker", "ledger", "scripts", "calendar-public", "packages/tooling/src", "packages/cloudflare/src", "packages/ledger/src", "packages/ledger-admin/src", "packages/contracts/src", "packages/runtime/src", "packages/ui/src"]): string[] {
+export function directGeneratedImports(root = ROOT, directories?: string[], platform = root): string[] {
     const problems: string[] = [];
     const generatedFile = /(^|[\\/])[\w-]+\.generated(\.js|\.ts)?$|(^|[\\/])tenant[\\/]generated(\.js|\.ts)?$/;
-    for (const directory of directories) {
-        for (const file of files(join(root, directory))) {
+    for (const [base, directory] of scanned(root, platform, directories, ["src", "ledger"], ["scripts", "packages/tooling/src", "packages/cloudflare/src", "packages/ledger/src", "packages/contracts/src", "packages/runtime/src", "packages/ui/src"])) {
+        for (const file of files(join(base, directory))) {
             // The scripts' own tests write fixture files whose text looks like imports, and the generators emit import lines.
             if (/\.generated\.ts$|[\\/]generated\.ts$/.test(file) || file.includes(`${sep}generated${sep}`) || file.includes(`${sep}(modules)${sep}`) || ((directory === "scripts" || directory === "packages/tooling/src") && /\.test\.ts$|(compose-modules|generate-[a-z-]+)\.ts$/.test(file))) continue;
             for (const specifier of specifiers(file)) {
                 if ((specifier.startsWith(".") || specifier.startsWith("#lib")) && generatedFile.test(specifier)) {
-                    problems.push(`${relative(root, file)}: "${specifier}" is a generated file (import it through #generated/*)`);
+                    problems.push(`${relative(base, file)}: "${specifier}" is a generated file (import it through #generated/*)`);
                 }
             }
         }
@@ -152,7 +163,7 @@ export function directGeneratedImports(root = ROOT, directories = ["src", "worke
     return problems;
 }
 
-export function checkBoundaries(root = ROOT, domain?: ModuleDomain): string[] {
+export function checkBoundaries(root = ROOT, domain?: ModuleDomain, platform = root): string[] {
     const problems: string[] = [];
     const modulesDirectory = join(root, "modules");
     // A platform workspace or a tenant repository has no modules directory.
@@ -174,21 +185,22 @@ export function checkBoundaries(root = ROOT, domain?: ModuleDomain): string[] {
         }
     }
     const generated = /\.generated\.ts$|[\\/]\(modules\)[\\/]/;
-    for (const directory of ["src", "worker", "packages"]) {
-        for (const file of files(join(root, directory))) {
+    for (const [base, directory] of scanned(root, platform, undefined, ["src"], ["packages"])) {
+        for (const file of files(join(base, directory))) {
             if (generated.test(file)) continue;
             for (const specifier of specifiers(file)) {
-                if (specifier.startsWith("@hearthlog/module-")) problems.push(`${relative(root, file)}: the core imports a module ("${specifier}")`);
+                if (specifier.startsWith("@hearthlog/module-")) problems.push(`${relative(base, file)}: the core imports a module ("${specifier}")`);
             }
         }
     }
-    problems.push(...coreNamesNoDomain(root, undefined, domain));
-    problems.push(...directGeneratedImports(root));
+    problems.push(...coreNamesNoDomain(root, undefined, domain, platform));
+    problems.push(...directGeneratedImports(root, undefined, platform));
     return problems;
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-    const problems = checkBoundaries(ROOT, await loadModuleDomain(ROOT));
+    // The host (its modules, its own code, the generated catalog) and the platform's packages may be different checkouts.
+    const problems = checkBoundaries(ROOT, await loadModuleDomain(ROOT), PLATFORM_ROOT);
     if (problems.length) {
         console.error(`Module boundaries are broken:\n  - ${problems.join("\n  - ")}`);
         process.exitCode = 1;

package/src/check/check-tenant-config.ts

@@ -186,7 +186,7 @@ for (const stack of stackNames) {
     if (JSON.stringify(feedSites) !== JSON.stringify(expectedSites)) problems.push(`${label}: the feed Worker should bind ${expectedSites.join(", ")}`);
     // A site on its own stack has a public Gallery Worker only when it ships the Gallery; the shared stack always has one.
     const ownSite = stack === "shared" ? undefined : sites.find((site) => site.id === stack)!;
-    if ((!ownSite || ownSite.features.includes("gallery")) && read("gallery-public").name !== siteInfrastructure.galleryPublicWorker) problems.push(`${label}: the public Gallery Worker should be named ${siteInfrastructure.galleryPublicWorker}`);
+    if ((!ownSite || (ownSite.features as readonly string[]).includes("gallery")) && read("gallery-public").name !== siteInfrastructure.galleryPublicWorker) problems.push(`${label}: the public Gallery Worker should be named ${siteInfrastructure.galleryPublicWorker}`);
 }
 
 for (const site of sites) problems.push(...(await moduleLockProblems(site)));

package/src/compose/compose-modules.ts

@@ -12,7 +12,7 @@
  *              gitignored `.generated/` by `pnpm build:generated`, which runs
  *              this first because everything else reads it. A site's modules
  *              are the ones in its `tenants/<id>/modules.lock.json`.
- *   (default)  The routes of one tenant (VITE_STOR_TENANT, default "st"):
+ *   (default)  The routes of one tenant (VITE_STOR_TENANT, default the host's only site, else "st"):
  *              thin wrappers in the gitignored `src/routes/(modules)/` for
  *              the modules whose features the tenant enables, so a tenant
  *              without a module ships none of its pages.
@@ -27,7 +27,7 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { CORE_ROUTE_PATHS } from "../host/core-routes.js";
-import { hostRoot } from "../root.js";
+import { activeSiteId, hostRoot } from "../root.js";
 
 import { findCollisions, validateManifest, type ModuleManifest } from "@hearthlog/contracts";
 
@@ -91,13 +91,13 @@ export function installedModuleDirectories(root = REPOSITORY_ROOT): string[] {
 }
 
 /**
- * The modules a host has: those in its `modules/` folder (a checkout that develops them) and the packages
- * it installs (a site that uses them). Given a directory, only that folder is scanned.
+ * The modules a host has: those in its `modules/` folder (a checkout that develops them, or a link to one) and
+ * the packages it installs (a site that uses them). Given a directory, only that folder is scanned.
  */
 export function loadModules(directory?: string): LoadedModule[] {
     const scanned = (folder: string): string[] => existsSync(folder)
         ? readdirSync(folder, { withFileTypes: true })
-            .filter((entry) => entry.isDirectory() && existsSync(join(folder, entry.name, "hearthlog.module.json")))
+            .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && existsSync(join(folder, entry.name, "hearthlog.module.json")))
             .map((entry) => join(folder, entry.name))
         : [];
     const directories = directory !== undefined ? scanned(directory) : [...scanned(MODULES_DIRECTORY), ...installedModuleDirectories()];
@@ -448,7 +448,7 @@ export async function generateCatalog({ siteId, all = false, check = false }: Ca
 async function composeRoutes(): Promise<void> {
     const modules = loadModules();
     checkComposition(modules);
-    const siteId = process.env.VITE_STOR_TENANT?.trim() || "st";
+    const siteId = activeSiteId();
     const { loadTenantConfig, siteById } = await import("../tenants/tenant-config.js");
     const { sites } = await loadTenantConfig(undefined, { only: siteId });
     const site = siteById(sites, siteId);
@@ -477,7 +477,7 @@ async function composeRoutes(): Promise<void> {
 
 export async function main(argv = process.argv.slice(2)): Promise<void> {
     const site = argv.indexOf("--site");
-    const siteId = (site >= 0 ? argv[site + 1] : undefined) ?? (process.env.VITE_STOR_TENANT?.trim() || "st");
+    const siteId = (site >= 0 ? argv[site + 1] : undefined) ?? activeSiteId();
     if (argv.includes("--catalog")) await generateCatalog({ siteId, all: argv.includes("--all"), check: argv.includes("--check") });
     else await composeRoutes();
 }

package/src/compose/module-scaffold.ts

@@ -18,6 +18,7 @@ import { fileURLToPath } from "node:url";
 
 import { MODULE_API_VERSION } from "@hearthlog/contracts";
 
+import { PLATFORM_ROOT } from "../root.js";
 import { REPOSITORY_ROOT } from "../tenants/tenant-config.js";
 
 const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates", "module");
@@ -92,10 +93,10 @@ export const load = ({ url }: { url: URL }) => deferLocalPage(url, {}, async ()
 `,
         "README.md": `# ${label}
 
-A module for the stor platform. It reaches the app only through \`@hearthlog/sdk\`; see
-\`docs/modules.md\` in the platform repository for what a module may declare (pages, entities,
-repositories, gateway code, startup code, attention badges) and \`pnpm check:modules\` for the
-boundary it enforces.
+A module for the Hearthlog platform. It reaches the app only through \`@hearthlog/sdk\`; the
+\`ModuleManifest\` type in \`@hearthlog/contracts\` documents what a module may declare (pages, entities,
+repositories, gateway code, startup code, attention badges), and \`pnpm check:modules\` enforces the
+boundary.
 `,
     };
 }
@@ -138,7 +139,8 @@ export function exportModule(modulesDirectory: string, name: string, out: string
     if (manifest.dependencies && Object.keys(manifest.dependencies).length === 0) delete manifest.dependencies;
     delete manifest.private;
     manifest.license = "AGPL-3.0-only";
-    const root = JSON.parse(readFileSync(join(REPOSITORY_ROOT, "package.json"), "utf8")) as { devDependencies?: Record<string, string>; packageManager?: string };
+    // The repository the module leaves: its pnpm and test tooling, and its license.
+    const root = JSON.parse(readFileSync(join(PLATFORM_ROOT, "package.json"), "utf8")) as { devDependencies?: Record<string, string>; packageManager?: string };
     const publishable = {
         ...manifest,
         repository: { type: "git", url: `git+https://github.com/hearthlog/hearthlog-module-${name}.git` },
@@ -160,7 +162,7 @@ export function exportModule(modulesDirectory: string, name: string, out: string
     writeFileSync(join(out, "pnpm-workspace.yaml"), "onlyBuiltDependencies:\n  - esbuild\n");
     copyFileSync(join(TEMPLATE, "ci.yml.tmpl"), join(out, ".github", "workflows", "ci.yml"));
     copyFileSync(join(TEMPLATE, "release.yml.tmpl"), join(out, ".github", "workflows", "release.yml"));
-    cpSync(join(REPOSITORY_ROOT, "LICENSE"), join(out, "LICENSE"));
+    cpSync(join(PLATFORM_ROOT, "LICENSE"), join(out, "LICENSE"));
     const readme = join(out, "README.md");
     const existing = existsSync(readme) ? readFileSync(readme, "utf8").trimEnd() : `# ${title(name)}`;
     writeFileSync(readme, `${existing}\n\n## Status\n\nIt installs against \`@hearthlog/sdk\` ${platformRange}.\n\n\`\`\`bash\npnpm install\npnpm test   # generates a site that enables this module, installs it, builds it, then runs the unit tests\n\`\`\`\n\nRelease: set \`version\` in \`package.json\`, commit, and push the tag \`v<version>\`; the release workflow publishes with provenance after approval.\n`);

package/src/deploy/deploy-tenant.ts

@@ -130,7 +130,7 @@ export async function deploySite(options: Options): Promise<void> {
 async function deployOwnPublicWorkers(site: ResolvedSite, dryRun: boolean, skipBuild: boolean): Promise<void> {
 	if (!site.deployment) return;
 	const args = ["deploy", ...(dryRun ? ["--dry-run"] : [])];
-	if (site.features.includes("gallery")) {
+	if ((site.features as readonly string[]).includes("gallery")) {
 		if (skipBuild) {
 			// A release built elsewhere carries its Worker bundle; only the configs are written here.
 			await generateHostConfigs(site.id);

package/src/dev/dev-ledger.ts

@@ -0,0 +1,138 @@
+/**
+ * `hearthlog dev-ledger [vite options]`: the site against a Ledger of its own on this machine, in one command. The
+ * `hearthlog` command builds the generated files first; this starts the site's Ledger Worker (`wrangler dev` on
+ * 127.0.0.1:8787, its data in `.wrangler/development/ledger-state/`), provisions the gateway credential the dev server
+ * reads (as `provision-local` does), then runs `vite dev` with the arguments given. Stopping either stops both.
+ *
+ * The Ledger's local secrets are written once to `.wrangler/development/ledger.dev.vars`: random, mode 600, and never
+ * committed (a site ignores `.wrangler/`). Delete `.wrangler/development/` to start from an empty Ledger.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { GENERATED_DIRECTORY, siteDirectory } from "../compose/compose-modules.js";
+import { activeSiteId, hostRoot } from "../root.js";
+import { DEFAULT_LOCAL_LEDGER_URL, ensureLocalLedgerCredential, localLedgerCredentialPath } from "./local-development.js";
+
+export const DEVELOPMENT_DIRECTORY = join(".wrangler", "development");
+export const LEDGER_DEV_VARS = join(DEVELOPMENT_DIRECTORY, "ledger.dev.vars");
+
+/** A new site's local Ledger secrets, in the `.dev.vars` format `wrangler dev --env-file` reads. */
+export function ledgerDevVars(secret: () => string = () => randomBytes(32).toString("hex")): string {
+    return `ADMIN_TOKEN=${secret()}\nTOKEN_SIGNING_KEY_CURRENT=${secret()}\nALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173\n`;
+}
+
+/** The `KEY=VALUE` lines of a `.dev.vars` file; blank lines and `#` comments are skipped. */
+export function parseDevVars(text: string): Record<string, string> {
+    const values: Record<string, string> = {};
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+        if (match && !line.trimStart().startsWith("#")) values[match[1]!] = match[2]!.replace(/^(["'])(.*)\1$/, "$2");
+    }
+    return values;
+}
+
+/** The Ledger configuration the build wrote for a site: its own (a dedicated Ledger), else the host's shared one. */
+export function ledgerConfigPath(siteId: string): string {
+    for (const candidate of [join(siteDirectory(siteId), "ledger", "wrangler.jsonc"), join(GENERATED_DIRECTORY, "shared", "ledger", "wrangler.jsonc")]) {
+        if (existsSync(candidate)) return candidate;
+    }
+    throw new Error(`No Ledger configuration for ${siteId} in .generated/: run hearthlog build`);
+}
+
+/** A tool's entry script as the site installs it, run with this Node rather than through a package manager. */
+function binary(root: string, name: string, bin: string): string {
+    const manifestPath = createRequire(join(root, "package.json")).resolve(`${name}/package.json`);
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { bin?: string | Record<string, string> };
+    const entry = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.[bin];
+    if (!entry) throw new Error(`${name} has no ${bin} binary`);
+    return join(dirname(manifestPath), entry);
+}
+
+async function waitForHealth(url: string, stopped: () => boolean): Promise<boolean> {
+    for (let attempt = 0; attempt < 120 && !stopped(); attempt++) {
+        try {
+            if ((await fetch(new URL("/health", url))).ok) return true;
+        } catch {
+            // Not listening yet.
+        }
+        await new Promise((done) => setTimeout(done, 500));
+    }
+    return false;
+}
+
+export async function devLedger(viteArguments: readonly string[]): Promise<number> {
+    const root = hostRoot();
+    const site = activeSiteId(root);
+    const varsPath = join(root, LEDGER_DEV_VARS);
+    mkdirSync(join(root, DEVELOPMENT_DIRECTORY), { recursive: true });
+    if (!existsSync(varsPath)) {
+        writeFileSync(varsPath, ledgerDevVars(), { mode: 0o600 });
+        console.log(`Wrote the local Ledger's secrets to ${LEDGER_DEV_VARS}`);
+    }
+    const adminToken = parseDevVars(readFileSync(varsPath, "utf8")).ADMIN_TOKEN ?? "";
+    const ledgerUrl = new URL(DEFAULT_LOCAL_LEDGER_URL);
+
+    const children = new Set<ChildProcess>();
+    let stopping = false;
+    let exitCode = 0;
+    let finished: (code: number) => void = () => {};
+    const done = new Promise<number>((resolveDone) => (finished = resolveDone));
+    const stop = (code: number) => {
+        if (stopping) return;
+        stopping = true;
+        exitCode = code;
+        // Each child leads a process group of its own, so this stops what it started too (wrangler's workerd).
+        for (const child of children) {
+            try {
+                process.kill(-child.pid!, "SIGTERM");
+            } catch {
+                // Already gone.
+            }
+        }
+        if (children.size === 0) finished(exitCode);
+    };
+    const start = (script: string, args: readonly string[]) => {
+        const child = spawn(process.execPath, [script, ...args], { cwd: root, stdio: "inherit", detached: true });
+        children.add(child);
+        child.on("exit", (code) => {
+            children.delete(child);
+            stop(code ?? 0);
+            if (children.size === 0) finished(exitCode);
+        });
+    };
+    process.on("SIGINT", () => stop(0));
+    process.on("SIGTERM", () => stop(0));
+
+    start(binary(root, "wrangler", "wrangler"), [
+        "dev",
+        "--config", ledgerConfigPath(site),
+        "--env-file", varsPath,
+        "--persist-to", join(root, DEVELOPMENT_DIRECTORY, "ledger-state"),
+        "--ip", ledgerUrl.hostname,
+        "--port", ledgerUrl.port,
+    ]);
+    if (!(await waitForHealth(ledgerUrl.href, () => stopping))) {
+        if (!stopping) console.error(`The local Ledger did not answer at ${new URL("/health", ledgerUrl).href}`);
+        stop(1);
+        return done;
+    }
+    try {
+        const { reused } = await ensureLocalLedgerCredential({ adminToken, baseUrl: ledgerUrl.href, credentialPath: localLedgerCredentialPath(root) });
+        console.log(`${reused ? "Reused" : "Provisioned"} the dev server's credential for the local Ledger (token not printed)`);
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        stop(1);
+        return done;
+    }
+    start(binary(root, "vite", "vite"), ["dev", ...viteArguments]);
+    return done;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    process.exitCode = await devLedger(process.argv.slice(2).filter((argument) => argument !== "--"));
+}

package/src/generate/build-generated.ts

@@ -17,7 +17,7 @@
  *
  *   pnpm build:generated [--site <id>] [--all-modules] [--check] [--force]
  *
- * The site defaults to VITE_STOR_TENANT, then "st". `--all-modules` writes the catalog of every installed
+ * The site defaults to VITE_STOR_TENANT, then the host's only site, then "st". `--all-modules` writes the catalog of every installed
  * module and nothing else (`pnpm lock:modules` reads it). `--check` fails when the outputs are stale.
  */
 
@@ -29,7 +29,7 @@ import { fileURLToPath } from "node:url";
 
 import { generateCatalog, GENERATED_DIRECTORY, loadModules, modulesInLock, siteDirectory } from "../compose/compose-modules.js";
 import { packageDirectory } from "../host/write-host.js";
-import { hostRoot } from "../root.js";
+import { activeSiteId, hostRoot } from "../root.js";
 
 const ROOT = hostRoot();
 const STATE_PATH = join(GENERATED_DIRECTORY, ".build.json");
@@ -153,7 +153,7 @@ export async function build(options: BuildOptions): Promise<"built" | "current">
 
 async function main(argv: string[]): Promise<void> {
     const site = argv.indexOf("--site");
-    const siteId = (site >= 0 ? argv[site + 1] : undefined) ?? (process.env.VITE_STOR_TENANT?.trim() || "st");
+    const siteId = (site >= 0 ? argv[site + 1] : undefined) ?? activeSiteId();
     const outcome = await build({ siteId, all: argv.includes("--all-modules"), check: argv.includes("--check"), force: argv.includes("--force") });
     if (outcome === "current" && !argv.includes("--quiet")) console.log(`Generated files are current for ${siteId}.`);
 }

package/src/generate/generate-tenant.ts

@@ -4,7 +4,7 @@
  *
  * 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").
+ * selected with VITE_STOR_TENANT (default: the host's only site, else "st").
  *
  * Usage: VITE_STOR_TENANT=bravo pnpm build:generated
  *
@@ -27,6 +27,7 @@ import {
 } from "../tenants/tenant-config.js";
 import { generateHostConfigs } from "../tenants/host-configs.js";
 import { generateTenantWranglerConfigs } from "../tenants/wrangler-config.js";
+import { activeSiteId } from "../root.js";
 import { brandMarkMaskUrl, wordmarkParts } from "@hearthlog/contracts/tenant/brand";
 import {
     themeVariablesCss,
@@ -137,7 +138,7 @@ if (/%%BRAND_[A-Z_]+%%/.test(brandable)) {
 }
 
 if (process.env.STOR_SKIP_TENANT_GENERATION !== "1") {
-    await generateTenant(process.env.VITE_STOR_TENANT?.trim() || "st", {
+    await generateTenant(activeSiteId(), {
         generateWranglerConfigs: process.env.STOR_WRANGLER_CONFIGS !== "0",
     });
 }

package/src/host/write-host.ts

@@ -19,7 +19,7 @@ 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 { activeSiteId, hostRoot } from "../root.js";
 import { CORE_ROUTE_FILES } from "./core-routes.js";
 
 const ROOT = hostRoot();
@@ -112,7 +112,7 @@ export async function writeHost(siteId: string): Promise<void> {
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-    writeHost(process.env.VITE_STOR_TENANT?.trim() || "st").catch((error: unknown) => {
+    writeHost(activeSiteId()).catch((error: unknown) => {
         console.error(error instanceof Error ? error.message : String(error));
         process.exitCode = 1;
     });

package/src/root.ts

@@ -1,5 +1,35 @@
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The platform checkout this tooling runs from: the repository with `packages/`, `scripts/`, and the license. Only the
+ * repository's own checks and exports use it; everything a site owns is under `hostRoot()`.
+ */
+export const PLATFORM_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+
+/**
+ * The site a build works on: `VITE_STOR_TENANT` when it is set, otherwise the host's only site (a repository
+ * made by `hearthlog init` or `hearthlog export` holds one), otherwise "st", the development site of the platform.
+ */
+export function activeSiteId(root: string = hostRoot()): string {
+    const named = process.env.VITE_STOR_TENANT?.trim();
+    if (named) return named;
+    const sites = new Set<string>();
+    const tenants = join(root, "tenants");
+    if (existsSync(tenants)) {
+        for (const entry of readdirSync(tenants, { withFileTypes: true })) {
+            if (entry.isDirectory() && existsSync(join(tenants, entry.name, "tenant.json"))) sites.add(entry.name);
+        }
+    }
+    try {
+        const listed = (JSON.parse(readFileSync(join(root, "tenants.json"), "utf8")) as { sites?: Array<{ id?: unknown }> }).sites ?? [];
+        for (const site of listed) if (typeof site.id === "string") sites.add(site.id);
+    } catch {
+        // No tenants.json, or one the tenant configuration check reports: the directories decide.
+    }
+    return sites.size === 1 ? [...sites][0]! : "st";
+}
 
 /**
  * The repository a command works on: the nearest directory, from the working directory upward, that

package/src/tenants/host-configs.ts

@@ -81,7 +81,7 @@ export async function generateHostConfigs(stack: Stack): Promise<string[]> {
         infrastructure = infrastructureFor(site, shared);
         ledgerAccount = site.deployment.accountId;
         calendarSites = [site.id];
-        gallery = site.features.includes("gallery");
+        gallery = (site.features as readonly string[]).includes("gallery");
     } else if (calendarSites.length === 0) {
         return written;
     }

package/src/vite/config.ts

@@ -6,10 +6,12 @@ import Icons from 'unplugin-icons/vite'
 import { entityGeneratorPlugin } from './vite-plugin-entity-gen.js';
 import { tenantManifestPlugin } from './vite-plugin-tenant-manifest.js';
 import { workerAssetsPlugin } from './vite-plugin-worker-assets.js';
+import { sourcePackages } from './source-packages.js';
 import { readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join, resolve } from 'node:path';
 import { localGatewayOriginAllowed, readLocalLedgerCredentialSync } from '../dev/local-development.js';
+import { activeSiteId } from '../root.js';
 import {
 	e2eLedgerStubPlugin,
 	localAiDecisionsPlugin,
@@ -21,17 +23,7 @@ import {
 	localReceivedInvoiceFilesPlugin,
 } from './dev-plugins.js';
 
-import { defineConfig, type ProxyOptions, type UserConfig } from 'vite';
-
-/** The `@hearthlog/*` packages the site depends on (the platform and its modules). */
-function hearthlogDependencies(): string[] {
-	try {
-		const manifest = JSON.parse(readFileSync('package.json', 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> };
-		return Object.keys({ ...manifest.dependencies, ...manifest.devDependencies }).filter((name) => name.startsWith('@hearthlog/') && name !== '@hearthlog/generated');
-	} catch {
-		return [];
-	}
-}
+import { defineConfig, searchForWorkspaceRoot, type ProxyOptions, type UserConfig } from 'vite';
 
 function installedVersion(name: string): string {
 	try {
@@ -75,7 +67,10 @@ const buildTimestamp = process.env.STOR_BUILD_TIMESTAMP?.trim() || new Date().to
 // Tenant build selection: VITE_STOR_TENANT=bravo writes the site into
 // build/bravo (matching wrangler env.bravo assets.directory). The default
 // tenant keeps the historical ./build output used by the top-level Worker.
-const tenantId = process.env.VITE_STOR_TENANT?.trim() || 'st';
+// Without VITE_STOR_TENANT a host with one site builds that site; the value is
+// set here so the plugins and `import.meta.env` (the service worker) agree.
+const tenantId = activeSiteId();
+process.env.VITE_STOR_TENANT = tenantId;
 const buildDirectory = process.env.STOR_BUILD_OUTPUT_ROOT?.trim() ||
 	(tenantId === 'st' ? 'build' : `build/${tenantId}`);
 const svelteKitOutDir = process.env.STOR_SVELTEKIT_OUT_DIR?.trim() || '.svelte-kit';
@@ -130,6 +125,7 @@ return defineConfig(({ command, mode }): UserConfig => {
 			? readLocalLedgerCredentialSync()
 			: undefined;
 	const isE2E = process.env.VITE_E2E === '1';
+	const sources = sourcePackages();
 	const usesSameOriginLedger = Boolean(localLedgerCredential) || isE2E;
 	// The dev proxy needs both: the renderer's address and its bearer token (from .dev.vars or the environment).
 	const invoiceRendererOrigin = readDevVar('INVOICE_RENDERER_ORIGIN');
@@ -238,8 +234,9 @@ return defineConfig(({ command, mode }): UserConfig => {
 		},
 		server: {
 			...devServerProxy,
-			// Module and SDK sources live outside src/; Kit's default list omits them.
-			fs: { allow: [resolve('modules'), resolve('packages')] }
+			// Module and SDK sources live outside src/; Kit's default list omits them. In a workspace the platform's packages
+			// are linked from outside the site, so the workspace root is allowed too.
+			fs: { allow: [resolve('modules'), resolve('packages'), searchForWorkspaceRoot(process.cwd())] }
 		},
 		resolve: {
 			alias: {
@@ -305,7 +302,12 @@ return defineConfig(({ command, mode }): UserConfig => {
 	optimizeDeps: {
 		// The platform and the modules ship Svelte and TypeScript source; installed from the registry they sit in node_modules,
 		// where the dependency scan cannot resolve their relative imports. They are compiled with the site, not pre-bundled.
-		exclude: ['sqlocal', 'microlighter', ...hearthlogDependencies()]
+		exclude: ['sqlocal', 'microlighter', ...sources.filter((name) => name !== '@hearthlog/generated')]
+	},
+	ssr: {
+		// For the same reason server rendering must compile them: externalized, Node would load their TypeScript from
+		// node_modules, which it refuses to strip. The pattern also catches a platform package the walk did not reach.
+		noExternal: [/^@hearthlog\//, ...sources],
 	},
 	build: {
 		// Bundle Microlighter's lazy grammars, which Vite skips in dependencies by default.

package/src/vite/source-packages.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+interface PackageManifest {
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+	peerDependencies?: Record<string, string>;
+	optionalDependencies?: Record<string, string>;
+}
+
+function readManifest(directory: string): PackageManifest | undefined {
+	try {
+		return JSON.parse(readFileSync(join(directory, 'package.json'), 'utf8')) as PackageManifest;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Node's lookup of `name` from `directory`: the nearest `node_modules/<name>` up the tree, as its real path. */
+function packageDirectory(name: string, directory: string): string | undefined {
+	for (let current = directory; ; current = dirname(current)) {
+		const candidate = basename(current) === 'node_modules' ? join(current, name) : join(current, 'node_modules', name);
+		if (existsSync(join(candidate, 'package.json'))) return realpathSync(candidate);
+		if (dirname(current) === current) return undefined;
+	}
+}
+
+/** The platform's packages and the modules (any package with a module manifest, whatever its scope) ship source. */
+function shipsSource(name: string, directory: string): boolean {
+	return name.startsWith('@hearthlog/') || existsSync(join(directory, 'hearthlog.module.json'));
+}
+
+/**
+ * The packages a site installs that ship Svelte and TypeScript source instead of JavaScript: every `@hearthlog/*`
+ * package and every module, direct or transitive. They are reached through the site's dependencies and, from each
+ * of them, through their own (peer) dependencies, so a module's `@hearthlog/czech` or a private-scope module counts.
+ */
+export function sourcePackages(root = process.cwd()): string[] {
+	const site = readManifest(root);
+	if (!site) return [];
+	const found = new Set<string>();
+	const visited = new Set<string>();
+	const visit = (names: Iterable<string>, from: string): void => {
+		for (const name of names) {
+			const directory = packageDirectory(name, from);
+			if (!directory || !shipsSource(name, directory)) continue;
+			found.add(name);
+			if (visited.has(directory)) continue;
+			visited.add(directory);
+			const manifest = readManifest(directory);
+			visit(Object.keys({ ...manifest?.dependencies, ...manifest?.peerDependencies, ...manifest?.optionalDependencies }), directory);
+		}
+	};
+	visit(Object.keys({ ...site.dependencies, ...site.devDependencies }), resolve(root));
+	return [...found].sort();
+}

package/src/vite/vite-plugin-tenant-manifest.ts

@@ -9,6 +9,7 @@
 import type { Plugin } from 'vite';
 
 import { themeVariablesFor } from '../../../contracts/src/tenant/theme.js';
+import { activeSiteId } from '../root.js';
 import { loadTenantConfig, siteById } from '../tenants/tenant-config.js';
 
 const MANIFEST_PATH = '/manifest.webmanifest';
@@ -40,7 +41,7 @@ async function manifestJson(siteId: string): Promise<string> {
 }
 
 export function tenantManifestPlugin(): Plugin {
-    const siteId = process.env.VITE_STOR_TENANT?.trim() || 'st';
+    const siteId = activeSiteId();
     return {
         name: 'tenant-manifest',
         configureServer(server) {

package/templates/tenant/README.md.tmpl

@@ -6,8 +6,13 @@ modules it ships, and everything else the app needs is written by `pnpm build:ge
 ```bash
 pnpm install
 pnpm dev     # builds the generated files, then starts Vite
+pnpm dev:ledger   # the same, with a Ledger of its own on this machine (127.0.0.1:8787)
 pnpm build   # a static build in build/
 ```
 
 `tenants.json` holds placeholder infrastructure names: it makes the site load, and it cannot be deployed until real
 values replace them.
+
+`pnpm dev:ledger` runs the site's Ledger Worker with `wrangler dev`, gives the dev server a credential for it, and
+starts Vite; Ctrl+C stops both. Its secrets, data, and credential live in `.wrangler/development/` (ignored): delete
+that folder to start from an empty Ledger.

package/templates/tenant/gitignore.tmpl

@@ -9,3 +9,6 @@ node_modules/
 # Native apps (`hearthlog apple:*`): build output and personal device settings
 /.apple-build/
 /resign.local.json
+# Deployment token files and the local Ledger's secrets, data and credential (`pnpm dev:ledger`): never committed
+/.wrangler/
+.dev.vars

package/templates/tenant/package.json.tmpl

@@ -5,6 +5,7 @@
   "scripts": {
     "build:generated": "hearthlog build",
     "dev": "hearthlog build && vite dev",
+    "dev:ledger": "hearthlog dev-ledger",
     "build": "hearthlog build && vite build",
     "check": "hearthlog build && svelte-kit sync && tsc --noEmit -p tsconfig.json --skipLibCheck"
   }