@hearthlog/tooling 0.0.0-stage → 0.1.0

package/src/tenants/ledger-config.ts

@@ -0,0 +1,57 @@
+/**
+ * The Ledger Worker's config. The Ledger is the same code for every stack; only its Worker name (and, for a site in
+ * its own account, the account) differs. The Durable Object classes and their SQLite storage are tied to deployed data
+ * and are never renamed.
+ */
+
+import type { InfrastructureDefinition } from "./tenant-config.js";
+import { WRANGLER_BASE } from "./wrangler-base.js";
+
+export const LEDGER_BASE = {
+    main: "./index.ts",
+    compatibility_flags: ["nodejs_compat"],
+    preview_urls: false,
+    durable_objects: {
+        bindings: [
+            { name: "LEDGER_APP", class_name: "LedgerApp" },
+            { name: "APP_REGISTRY", class_name: "AppRegistry" },
+        ],
+    },
+    exports: {
+        LedgerApp: { type: "durable-object", storage: "sqlite" },
+        AppRegistry: { type: "durable-object", storage: "sqlite" },
+    },
+    vars: {
+        TOKEN_SIGNING_KEY_ID: "v1",
+        TOKEN_SIGNING_PREVIOUS_KEY_ID: "",
+        ALLOWED_ORIGINS: "",
+        // "report" logs payloads that "enforce" would reject with 422; flip to "enforce" once the logs show only
+        // intended rejections.
+        EVENT_VALIDATION: "report",
+    },
+    observability: {
+        enabled: true,
+        logs: { enabled: true, head_sampling_rate: 1 },
+        traces: { enabled: true, head_sampling_rate: 0.05 },
+    },
+} as const;
+
+/** The Ledger Worker of a stack: its name from the infrastructure, and the account when the site pins one. */
+export function buildLedgerConfig(
+    infrastructure: Pick<InfrastructureDefinition, "ledgerWorker">,
+    accountId?: string,
+): Record<string, unknown> {
+    return {
+        name: infrastructure.ledgerWorker,
+        main: LEDGER_BASE.main,
+        compatibility_date: WRANGLER_BASE.compatibility_date,
+        compatibility_flags: LEDGER_BASE.compatibility_flags,
+        preview_urls: LEDGER_BASE.preview_urls,
+        durable_objects: LEDGER_BASE.durable_objects,
+        exports: LEDGER_BASE.exports,
+        vars: LEDGER_BASE.vars,
+        observability: LEDGER_BASE.observability,
+        // Pinning the account makes Wrangler refuse to deploy into any other one.
+        ...(accountId ? { account_id: accountId } : {}),
+    };
+}

package/src/tenants/lock-file.ts

@@ -0,0 +1,45 @@
+/**
+ * The lock file's content: which modules a site ships and the exact manifest each was composed from. It
+ * imports nothing generated, so `hearthlog init` can write one before a site has any generated files.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { MODULE_API_VERSION } from "@hearthlog/contracts";
+
+import { modulesForFeatures, type LoadedModule } from "../compose/compose-modules.js";
+
+export interface ModuleLockEntry {
+    id: string;
+    package: string;
+    version: string;
+    /** The site's enabled features this module provides. */
+    features: string[];
+    /** SHA-256 of the module's `hearthlog.module.json`. */
+    manifestSha256: string;
+}
+
+export interface ModuleLock {
+    schemaVersion: 1;
+    platform: { moduleApi: number };
+    modules: ModuleLockEntry[];
+}
+
+/** The lock for the modules that provide a site's features. */
+export function lockFor(modules: readonly LoadedModule[], features: readonly string[]): ModuleLock {
+    const entries: ModuleLockEntry[] = modulesForFeatures(modules, features).map(({ directory, manifest }) => ({
+        id: manifest.id,
+        package: manifest.package,
+        version: manifest.version,
+        features: manifest.features.map((feature) => feature.id).filter((id) => features.includes(id)),
+        manifestSha256: createHash("sha256").update(readFileSync(join(directory, "hearthlog.module.json"))).digest("hex"),
+    }));
+    entries.sort((a, b) => a.id.localeCompare(b.id));
+    return { schemaVersion: 1, platform: { moduleApi: MODULE_API_VERSION }, modules: entries };
+}
+
+export function renderModuleLock(lock: ModuleLock): string {
+    return `${JSON.stringify(lock, null, 2)}\n`;
+}

package/src/tenants/module-lock.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env npx tsx
+/**
+ * `tenants/<site>/modules.lock.json`: the modules a site ships, with the
+ * exact manifest each was composed from. The composer builds from the
+ * workspace, so the lock does not choose versions; it records them, and
+ * `pnpm check:tenants` fails when a site's modules or a manifest changed
+ * without the lock being regenerated. That makes a release reviewable: the
+ * lock diff names every module whose contract moved.
+ *
+ * Usage: pnpm lock:modules [--check]
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadModules } from "../compose/compose-modules.js";
+import { lockFor, renderModuleLock, type ModuleLock } from "./lock-file.js";
+
+import { loadTenantConfig, TENANTS_DIRECTORY, type ResolvedSite } from "./tenant-config.js";
+
+export { lockFor, renderModuleLock, type ModuleLock, type ModuleLockEntry } from "./lock-file.js";
+
+export function moduleLockPath(siteId: string): string {
+    return join(TENANTS_DIRECTORY, siteId, "modules.lock.json");
+}
+
+export async function buildModuleLock(site: Pick<ResolvedSite, "features">): Promise<ModuleLock> {
+    return lockFor(loadModules(), site.features);
+}
+
+/** What differs between a site's lock file and the modules it would ship today. */
+export async function moduleLockProblems(site: Pick<ResolvedSite, "id" | "features">): Promise<string[]> {
+    const expected = renderModuleLock(await buildModuleLock(site));
+    const current = await readFile(moduleLockPath(site.id), "utf8").catch(() => null);
+    if (current === null) return [`tenants/${site.id}/modules.lock.json is missing; run pnpm lock:modules`];
+    return current === expected ? [] : [`tenants/${site.id}/modules.lock.json is stale; run pnpm lock:modules`];
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const { sites } = await loadTenantConfig();
+    const check = process.argv.includes("--check");
+    const problems: string[] = [];
+    for (const site of sites) {
+        if (check) {
+            problems.push(...(await moduleLockProblems(site)));
+            continue;
+        }
+        const path = moduleLockPath(site.id);
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, renderModuleLock(await buildModuleLock(site)));
+    }
+    if (problems.length) {
+        console.error(problems.join("\n"));
+        process.exit(1);
+    }
+    console.log(check ? "Module locks are current." : `Wrote ${sites.length} module lock(s).`);
+}