@hearthlog/tooling 0.1.5 → 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.5",
+  "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.5"
+    "@hearthlog/contracts": "0.1.6"
   },
   "bin": {
     "hearthlog": "./bin/hearthlog.mjs"

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/vite/config.ts

@@ -6,6 +6,7 @@ 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';
@@ -24,16 +25,6 @@ import {
 
 import { defineConfig, searchForWorkspaceRoot, 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 [];
-	}
-}
-
 function installedVersion(name: string): string {
 	try {
 		return JSON.parse(readFileSync(join('node_modules', name, 'package.json'), 'utf8')).version;
@@ -134,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');
@@ -310,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/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"
   }