@hearthlog/tooling 0.0.0-stage → 0.1.1

package/src/dev/local-development.ts

@@ -0,0 +1,288 @@
+import { readFileSync } from "node:fs";
+import {
+    chmod,
+    mkdir,
+    readFile,
+    rename,
+    writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_LOCAL_LEDGER_URL = "http://127.0.0.1:8787";
+export const DEFAULT_LOCAL_LEDGER_CREDENTIAL_PATH =
+    ".wrangler/development/st-local-ledger.json";
+
+export interface LocalLedgerCredential {
+    version: 1;
+    baseUrl: string;
+    appId: string;
+    token: string;
+    createdAt: string;
+}
+
+interface EnsureLocalLedgerOptions {
+    adminToken: string;
+    baseUrl?: string;
+    credentialPath?: string;
+    fetch?: typeof fetch;
+}
+
+export interface EnsureLocalLedgerResult {
+    credential: LocalLedgerCredential;
+    reused: boolean;
+}
+
+export function localGatewayOriginAllowed(
+    origin: string | undefined,
+    host: string | undefined,
+): boolean {
+    if (origin === undefined) return true;
+    if (host === undefined) return false;
+    try {
+        const url = new URL(origin);
+        return (
+            (url.protocol === "http:" || url.protocol === "https:") &&
+            !url.username &&
+            !url.password &&
+            url.pathname === "/" &&
+            !url.search &&
+            !url.hash &&
+            url.host.toLowerCase() === host.toLowerCase()
+        );
+    } catch {
+        return false;
+    }
+}
+
+export function localLedgerCredentialPath(
+    projectRoot = process.cwd(),
+): string {
+    return path.resolve(
+        projectRoot,
+        process.env.LEDGER_LOCAL_CREDENTIAL_PATH ??
+            DEFAULT_LOCAL_LEDGER_CREDENTIAL_PATH,
+    );
+}
+
+export async function readLocalLedgerCredential(
+    credentialPath = localLedgerCredentialPath(),
+): Promise<LocalLedgerCredential | undefined> {
+    try {
+        return parseLocalLedgerCredential(
+            JSON.parse(await readFile(credentialPath, "utf8")),
+        );
+    } catch {
+        return undefined;
+    }
+}
+
+export function readLocalLedgerCredentialSync(
+    credentialPath = localLedgerCredentialPath(),
+): LocalLedgerCredential | undefined {
+    try {
+        return parseLocalLedgerCredential(
+            JSON.parse(readFileSync(credentialPath, "utf8")),
+        );
+    } catch {
+        return undefined;
+    }
+}
+
+export function parseLocalLedgerCredential(
+    value: unknown,
+): LocalLedgerCredential | undefined {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value as Record<string, unknown>;
+    if (
+        record.version !== 1 ||
+        typeof record.baseUrl !== "string" ||
+        !isHttpUrl(record.baseUrl) ||
+        typeof record.appId !== "string" ||
+        record.appId.length === 0 ||
+        typeof record.token !== "string" ||
+        record.token.length === 0 ||
+        typeof record.createdAt !== "string" ||
+        !Number.isFinite(Date.parse(record.createdAt))
+    ) {
+        return undefined;
+    }
+    return {
+        version: 1,
+        baseUrl: normalizeBaseUrl(record.baseUrl),
+        appId: record.appId,
+        token: record.token,
+        createdAt: record.createdAt,
+    };
+}
+
+export async function ensureLocalLedgerCredential(
+    options: EnsureLocalLedgerOptions,
+): Promise<EnsureLocalLedgerResult> {
+    if (!options.adminToken) {
+        throw new Error(
+            "ADMIN_TOKEN is missing; configure ledger/.dev.vars before starting Vite",
+        );
+    }
+    const baseUrl = normalizeBaseUrl(
+        options.baseUrl ??
+            process.env.LEDGER_LOCAL_URL ??
+            DEFAULT_LOCAL_LEDGER_URL,
+    );
+    const credentialPath =
+        options.credentialPath ?? localLedgerCredentialPath();
+    const fetchImpl = options.fetch ?? fetch;
+
+    await requireHealthyLedger(fetchImpl, baseUrl);
+
+    const existing = await readLocalLedgerCredential(credentialPath);
+    if (
+        existing?.baseUrl === baseUrl &&
+        (await credentialIsActive(fetchImpl, existing))
+    ) {
+        await chmod(credentialPath, 0o600);
+        return { credential: existing, reused: true };
+    }
+
+    const response = await fetchImpl(new URL("/admin/v1/apps", baseUrl), {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${options.adminToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            name:
+                `st-local-${new Date().toISOString().replaceAll(/[^0-9]/g, "")}` +
+                `-${crypto.randomUUID().slice(0, 8)}`,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(
+            `Local Ledger app provisioning failed with HTTP ${response.status}`,
+        );
+    }
+    const body: unknown = await response.json();
+    const credential = credentialFromProvisioningResponse(body, baseUrl);
+    await writeCredential(credentialPath, credential);
+    return { credential, reused: false };
+}
+
+async function requireHealthyLedger(
+    fetchImpl: typeof fetch,
+    baseUrl: string,
+): Promise<void> {
+    let response: Response;
+    try {
+        response = await fetchImpl(new URL("/health", baseUrl));
+    } catch {
+        throw new Error(
+            `Local Ledger is unavailable at ${baseUrl}; start pnpm ledger:dev first`,
+        );
+    }
+    if (response.status !== 204) {
+        throw new Error(
+            `Local Ledger health check failed with HTTP ${response.status}`,
+        );
+    }
+}
+
+async function credentialIsActive(
+    fetchImpl: typeof fetch,
+    credential: LocalLedgerCredential,
+): Promise<boolean> {
+    try {
+        const response = await fetchImpl(
+            new URL("/session", credential.baseUrl),
+            {
+                headers: {
+                    Authorization: `Bearer ${credential.token}`,
+                },
+            },
+        );
+        if (!response.ok) return false;
+        const value: unknown = await response.json();
+        return (
+            value !== null &&
+            typeof value === "object" &&
+            !Array.isArray(value) &&
+            (value as Record<string, unknown>).appId === credential.appId
+        );
+    } catch {
+        return false;
+    }
+}
+
+function credentialFromProvisioningResponse(
+    value: unknown,
+    baseUrl: string,
+): LocalLedgerCredential {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Local Ledger returned an invalid provisioning response");
+    }
+    const response = value as Record<string, unknown>;
+    const app =
+        response.app !== null &&
+        typeof response.app === "object" &&
+        !Array.isArray(response.app)
+            ? response.app as Record<string, unknown>
+            : undefined;
+    if (
+        typeof response.token !== "string" ||
+        response.token.length === 0 ||
+        typeof app?.id !== "string" ||
+        app.id.length === 0
+    ) {
+        throw new Error("Local Ledger returned an invalid provisioning response");
+    }
+    return {
+        version: 1,
+        baseUrl,
+        appId: app.id,
+        token: response.token,
+        createdAt: new Date().toISOString(),
+    };
+}
+
+async function writeCredential(
+    credentialPath: string,
+    credential: LocalLedgerCredential,
+): Promise<void> {
+    const directory = path.dirname(credentialPath);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporaryPath =
+        `${credentialPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    await writeFile(
+        temporaryPath,
+        `${JSON.stringify(credential, null, 2)}\n`,
+        {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 0o600,
+        },
+    );
+    await rename(temporaryPath, credentialPath);
+    await chmod(credentialPath, 0o600);
+}
+
+function normalizeBaseUrl(value: string): string {
+    if (!isHttpUrl(value)) {
+        throw new Error(
+            `LEDGER_LOCAL_URL must be an HTTP URL, received ${value}`,
+        );
+    }
+    const url = new URL(value);
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+
+function isHttpUrl(value: string): boolean {
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    } catch {
+        return false;
+    }
+}

package/src/dev/provision-local.ts

@@ -0,0 +1,13 @@
+import {
+    ensureLocalLedgerCredential,
+    localLedgerCredentialPath,
+} from "./local-development.js";
+
+const result = await ensureLocalLedgerCredential({
+    adminToken: process.env.ADMIN_TOKEN ?? "",
+});
+
+console.log(
+    `${result.reused ? "Reused" : "Provisioned"} local Ledger gateway ` +
+        `credential at ${localLedgerCredentialPath()} (token not printed)`,
+);

package/src/generate/build-generated.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env npx tsx
+/**
+ * `pnpm build:generated`: write everything the build generates, once, for one site.
+ *
+ *   .generated/src/           the shared package (@hearthlog/generated) for the active site: the module
+ *                             catalog, icons, repositories, entity types and schema, data APIs, and the
+ *                             Ledger's event schemas
+ *   .generated/sites/<id>/    the site's tenant module, boot shell (app.html), and gateway table
+ *   routes/, app.css, service-worker/, static/, app.d.ts   the SvelteKit host (see host/write-host.ts), with the
+ *                             site's module routes composed into routes/(modules)/
+ *
+ * A site's modules are the ones in `tenants/<id>/modules.lock.json`. The catalog is written first, in this
+ * process, because everything else reads it; the generators that do run in processes of their own, so they
+ * see the new catalog. The inputs (tenants.json, the site's files, the lock's manifests and entity
+ * definitions, the core entity definitions, and the generators) are hashed; a build with the same hash and
+ * the outputs in place does nothing.
+ *
+ *   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
+ * module and nothing else (`pnpm lock:modules` reads it). `--check` fails when the outputs are stale.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+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";
+
+const ROOT = hostRoot();
+const STATE_PATH = join(GENERATED_DIRECTORY, ".build.json");
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TOOLING = resolve(HERE, "..");
+
+/** What the generators read besides the modules: the core entity definitions, the tooling, the boot shell template. */
+const SHARED_INPUTS = [
+    "tenants.json",
+    "src/routes",
+    "static",
+].map((path) => join(ROOT, path));
+const GENERATOR_INPUTS = [...["generate", "compose", "tenants", "host"].map((folder) => join(TOOLING, folder)), join(TOOLING, "..", "templates")];
+
+export interface BuildOptions {
+    siteId: string;
+    all?: boolean;
+    check?: boolean;
+    force?: boolean;
+}
+
+interface BuildState {
+    hash: string;
+    site: string;
+    all: boolean;
+}
+
+function files(path: string): string[] {
+    if (!existsSync(path)) return [];
+    if (!statSync(path).isDirectory()) return [path];
+    return readdirSync(path, { withFileTypes: true })
+        .filter((entry) => entry.name !== "node_modules" && !entry.name.endsWith(".test.ts"))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .flatMap((entry) => files(join(path, entry.name)));
+}
+
+/** The hash of everything a build of this site and mode reads. */
+export function inputHash({ siteId, all = false }: Pick<BuildOptions, "siteId" | "all">): string {
+    const installed = loadModules();
+    const modules = all ? installed : modulesInLock(installed, siteId);
+    const inputs = [
+        ...SHARED_INPUTS,
+        join(packageDirectory("@hearthlog/contracts"), "src"),
+        join(packageDirectory("@hearthlog/shell"), "static"),
+        join(packageDirectory("@hearthlog/shell"), "src", "app.template.html"),
+        ...GENERATOR_INPUTS,
+        ...(all ? [] : files(join(ROOT, "tenants", siteId))),
+        ...modules.flatMap(({ directory }) => [join(directory, "hearthlog.module.json"), join(directory, "src", "data")]),
+    ];
+    const hash = createHash("sha256").update(`${siteId}\0${all}\0`);
+    for (const file of inputs.flatMap(files)) {
+        hash.update(`${relative(ROOT, file)}\0`).update(readFileSync(file)).update("\0");
+    }
+    return hash.digest("hex");
+}
+
+function outputs(siteId: string, all: boolean): string[] {
+    const shared = ["modules", "module-icons", "module-repositories", "types", "schema", "standard-commands", "standard-db", "event-schemas"]
+        .map((name) => join(GENERATED_DIRECTORY, "src", `${name}.generated.ts`));
+    if (all) return shared.slice(0, 3);
+    return [
+        ...shared,
+        join(siteDirectory(siteId), "tenant.ts"),
+        join(siteDirectory(siteId), "app.html"),
+        join(siteDirectory(siteId), "server-modules.ts"),
+        join(siteDirectory(siteId), "worker.ts"),
+        join(siteDirectory(siteId), "wrangler.jsonc"),
+        join(GENERATED_DIRECTORY, "routes", "(modules)", "startup.ts"),
+        join(GENERATED_DIRECTORY, "routes", "+layout.svelte"),
+        join(GENERATED_DIRECTORY, "module-sources.generated.css"),
+        join(GENERATED_DIRECTORY, "app.css"),
+        join(GENERATED_DIRECTORY, "app.d.ts"),
+        join(GENERATED_DIRECTORY, "tsconfig.json"),
+        join(GENERATED_DIRECTORY, "service-worker", "index.ts"),
+        join(GENERATED_DIRECTORY, "static", "_headers"),
+    ];
+}
+
+function readState(): BuildState | undefined {
+    try {
+        return JSON.parse(readFileSync(STATE_PATH, "utf8")) as BuildState;
+    } catch {
+        return undefined;
+    }
+}
+
+function isCurrent({ siteId, all = false }: BuildOptions): boolean {
+    const state = readState();
+    return state !== undefined
+        && state.site === siteId
+        && state.all === all
+        && state.hash === inputHash({ siteId, all })
+        && outputs(siteId, all).every((path) => existsSync(path));
+}
+
+function runGenerator(script: string, siteId: string): void {
+    const result = spawnSync(process.execPath, [...process.execArgv, join(TOOLING, script)], {
+        cwd: ROOT,
+        stdio: "inherit",
+        env: { ...process.env, VITE_STOR_TENANT: siteId },
+    });
+    if (result.status !== 0) throw new Error(`${script} failed`);
+}
+
+export async function build(options: BuildOptions): Promise<"built" | "current"> {
+    const { siteId, all = false } = options;
+    if (!options.force && isCurrent(options)) return "current";
+    if (options.check) throw new Error(`The generated files are stale for ${all ? "every module" : `site ${siteId}`} (run pnpm build:generated)`);
+    await generateCatalog({ siteId, all });
+    if (!all) {
+        runGenerator("generate/generate-entities.ts", siteId);
+        runGenerator("generate/generate-tenant.ts", siteId);
+        runGenerator("host/write-host.ts", siteId);
+        runGenerator("compose/compose-modules.ts", siteId);
+    }
+    mkdirSync(GENERATED_DIRECTORY, { recursive: true });
+    const state: BuildState = { hash: inputHash({ siteId, all }), site: siteId, all };
+    writeFileSync(STATE_PATH, `${JSON.stringify(state)}\n`, "utf8");
+    return "built";
+}
+
+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 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}.`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main(process.argv.slice(2)).catch((error: unknown) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}

package/src/generate/generate-brand-icons.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env npx tsx
+/**
+ * Brand Icon Generator
+ *
+ * Renders the brand mark into one icon set per tenant under
+ * tenants/<site-id>/static/icons/<site-id>/ (favicon, Apple touch icon, PWA and maskable icons),
+ * plus the default packages/shell/static/favicon.ico. The tile colour comes from the tenant
+ * accent; tenants without one use the original teal. Rasterizing uses the
+ * Chromium that Playwright already installs.
+ *
+ * The output is committed. Re-run after changing the mark or a tenant accent:
+ *
+ *   pnpm generate:icons
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { chromium } from "@playwright/test";
+
+import {
+    brandColor,
+    brandTileSvg,
+    BRAND_MARK_DEFAULT_COLOR,
+} from "@hearthlog/contracts/tenant/brand";
+import { themeVariablesFor } from "@hearthlog/contracts/tenant/theme";
+import {
+    loadTenantConfig,
+    REPOSITORY_ROOT,
+    validateCrossSite,
+} from "../tenants/tenant-config.js";
+
+const MARK_ON_TILE = "#fbf9fa";
+
+interface IconSpec {
+    file: string;
+    size: number;
+    scale: number;
+    /** Rounded tile with transparent corners instead of full bleed. */
+    radius?: number;
+}
+
+const ICONS: readonly IconSpec[] = [
+    // Full bleed: iOS applies its own mask and rejects transparency.
+    { file: "apple-touch-icon.png", size: 180, scale: 0.62 },
+    { file: "pwa-192.png", size: 192, scale: 0.66, radius: 112 },
+    { file: "pwa-512.png", size: 512, scale: 0.66, radius: 112 },
+    // Maskable icons keep the mark inside the 80% safe circle.
+    { file: "maskable-512.png", size: 512, scale: 0.5 },
+];
+
+const FAVICON_SIZES = [16, 32, 48] as const;
+
+/** Packs PNGs into one ICO container (PNG-compressed entries). */
+function icoFromPngs(entries: readonly { size: number; png: Buffer }[]): Buffer {
+    const header = Buffer.alloc(6);
+    header.writeUInt16LE(1, 2);
+    header.writeUInt16LE(entries.length, 4);
+    let offset = 6 + entries.length * 16;
+    const directory = entries.map(({ size, png }) => {
+        const entry = Buffer.alloc(16);
+        entry.writeUInt8(size, 0);
+        entry.writeUInt8(size, 1);
+        entry.writeUInt16LE(1, 4);
+        entry.writeUInt16LE(32, 6);
+        entry.writeUInt32LE(png.length, 8);
+        entry.writeUInt32LE(offset, 12);
+        offset += png.length;
+        return entry;
+    });
+    return Buffer.concat([header, ...directory, ...entries.map(({ png }) => png)]);
+}
+
+const { sites } = await loadTenantConfig();
+validateCrossSite(sites);
+
+const browser = await chromium.launch();
+const page = await browser.newPage();
+
+async function render(svg: string, size: number): Promise<Buffer> {
+    await page.setViewportSize({ width: size, height: size });
+    await page.setContent(
+        `<body style="margin:0;background:transparent"><div style="width:${size}px;height:${size}px">` +
+            svg.replace("<svg ", `<svg width="${size}" height="${size}" `) +
+            `</div></body>`,
+    );
+    return page.screenshot({ omitBackground: true, type: "png" });
+}
+
+async function faviconIco(svg: string): Promise<Buffer> {
+    return icoFromPngs(
+        await Promise.all(
+            FAVICON_SIZES.map(async (size) => ({
+                size,
+                png: await render(svg, size),
+            })),
+        ),
+    );
+}
+
+function faviconSvg(background: string): string {
+    return brandTileSvg({ background, fill: MARK_ON_TILE, scale: 0.7, radius: 112 });
+}
+
+try {
+    for (const site of sites) {
+        const accent = site.theme.accent;
+        const action = themeVariablesFor(accent, "light")["--stor-action"];
+        const background = brandColor(accent, action);
+        const directory = join(REPOSITORY_ROOT, "tenants", site.id, "static", "icons", site.id);
+        await mkdir(directory, { recursive: true });
+
+        for (const { file, size, scale, radius } of ICONS) {
+            const svg = brandTileSvg({ background, fill: MARK_ON_TILE, scale, radius });
+            await writeFile(join(directory, file), await render(svg, size));
+        }
+        await writeFile(join(directory, "favicon.ico"), await faviconIco(faviconSvg(background)));
+        console.log(`Generated icons for "${site.id}" (${background}).`);
+    }
+
+    // Default for clients that request /favicon.ico without reading the page; the shell ships it to every site.
+    await writeFile(
+        join(REPOSITORY_ROOT, "packages", "shell", "static", "favicon.ico"),
+        await faviconIco(faviconSvg(BRAND_MARK_DEFAULT_COLOR)),
+    );
+} finally {
+    await browser.close();
+}