@hearthlog/tooling 0.0.0-stage → 0.1.1

package/src/vite/vite-plugin-entity-gen.ts

@@ -0,0 +1,70 @@
+/**
+ * Vite Plugin: Entity Generator
+ * 
+ * Watches entity-definitions.ts and auto-regenerates types on change.
+ * This provides a better DX by eliminating the need to manually run
+ * `pnpm generate:entities` during development.
+ */
+
+import type { Plugin } from 'vite';
+import { spawn } from 'child_process';
+import path from 'path';
+
+let isGenerating = false;
+
+export function entityGeneratorPlugin(): Plugin {
+    return {
+        name: 'entity-generator',
+        configureServer(server) {
+            const entityDefsPath = path.resolve('packages/contracts/src/event/entity-definitions.ts');
+
+            // Add the file to the watcher
+            server.watcher.add(entityDefsPath);
+
+            server.watcher.on('change', (changedPath) => {
+                // Normalize paths for comparison
+                const normalizedChanged = path.normalize(changedPath);
+                const normalizedTarget = path.normalize(entityDefsPath);
+
+                if (normalizedChanged === normalizedTarget && !isGenerating) {
+                    isGenerating = true;
+                    console.log('\n[entity-gen] 🔄 Regenerating entity types...');
+
+                    const startTime = Date.now();
+                    const child = spawn('pnpm', ['generate:entities'], {
+                        stdio: 'pipe',
+                        shell: true,
+                        cwd: process.cwd()
+                    });
+
+                    child.stdout?.on('data', (data) => {
+                        const output = data.toString().trim();
+                        if (output) console.log(`[entity-gen] ${output}`);
+                    });
+
+                    child.stderr?.on('data', (data) => {
+                        const output = data.toString().trim();
+                        if (output) console.error(`[entity-gen] ❌ ${output}`);
+                    });
+
+                    child.on('close', (code) => {
+                        const elapsed = Date.now() - startTime;
+                        if (code === 0) {
+                            console.log(`[entity-gen] ✅ Done in ${elapsed}ms`);
+                        } else {
+                            console.error(`[entity-gen] ❌ Failed with code ${code}`);
+                        }
+                        isGenerating = false;
+                    });
+
+                    child.on('error', (err) => {
+                        console.error(`[entity-gen] ❌ Failed to start: ${err.message}`);
+                        isGenerating = false;
+                    });
+                }
+            });
+
+            console.log('[entity-gen] 👀 Watching entity-definitions.ts for changes');
+        },
+    };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Vite Plugin: Tenant Web App Manifest
+ *
+ * Serves and emits /manifest.webmanifest for the tenant selected with
+ * VITE_STOR_TENANT, so each installed app gets its own name, theme colour, and
+ * icon set (tenants/<site-id>/static/icons/<site-id>/, see packages/tooling/src/generate/generate-brand-icons.ts).
+ */
+
+import type { Plugin } from 'vite';
+
+import { themeVariablesFor } from '../../../contracts/src/tenant/theme.js';
+import { loadTenantConfig, siteById } from '../tenants/tenant-config.js';
+
+const MANIFEST_PATH = '/manifest.webmanifest';
+
+async function manifestJson(siteId: string): Promise<string> {
+    const { sites } = await loadTenantConfig(undefined, { only: siteId });
+    const site = siteById(sites, siteId);
+    const color = themeVariablesFor(site.theme.accent, 'light')['--stor-theme-color'];
+    const icons = `/icons/${site.id}`;
+    return JSON.stringify(
+        {
+            name: site.title,
+            short_name: site.title,
+            id: site.title.trim().toLowerCase(),
+            start_url: '/',
+            scope: '/',
+            display: 'standalone',
+            theme_color: color,
+            background_color: color,
+            icons: [
+                { src: `${icons}/pwa-192.png`, sizes: '192x192', type: 'image/png', purpose: 'any' },
+                { src: `${icons}/pwa-512.png`, sizes: '512x512', type: 'image/png', purpose: 'any' },
+                { src: `${icons}/maskable-512.png`, sizes: '512x512', type: 'image/png', purpose: 'maskable' },
+            ],
+        },
+        null,
+        2,
+    );
+}
+
+export function tenantManifestPlugin(): Plugin {
+    const siteId = process.env.VITE_STOR_TENANT?.trim() || 'st';
+    return {
+        name: 'tenant-manifest',
+        configureServer(server) {
+            server.middlewares.use(MANIFEST_PATH, async (_request, response) => {
+                response.setHeader('Content-Type', 'application/manifest+json; charset=utf-8');
+                response.end(await manifestJson(siteId));
+            });
+        },
+        async generateBundle() {
+            if (this.environment?.name !== 'client') return;
+            this.emitFile({
+                type: 'asset',
+                fileName: MANIFEST_PATH.slice(1),
+                source: await manifestJson(siteId),
+            });
+        },
+    };
+}

package/src/vite/vite-plugin-worker-assets.ts

@@ -0,0 +1,42 @@
+/**
+ * Vite Plugin: Worker asset list for the service worker
+ *
+ * SvelteKit's `$app/manifest` lists the worker entry files but not the chunks
+ * and WASM they load, because those are copied into the client output after the
+ * service worker is bundled. The SQLite WASM worker needs all of them offline,
+ * so `virtual:worker-assets` lists everything Kit emitted under
+ * `_app/immutable/workers`.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+import type { Plugin } from 'vite';
+
+const VIRTUAL_ID = 'virtual:worker-assets';
+const RESOLVED_ID = `\0${VIRTUAL_ID}`;
+
+function listFiles(directory: string): string[] {
+    if (!existsSync(directory)) return [];
+    return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(directory, entry.name);
+        return entry.isDirectory() ? listFiles(path) : [path];
+    });
+}
+
+export function workerAssetsPlugin(outDir: string): Plugin {
+    const clientOutput = join(outDir, 'output', 'client');
+    return {
+        name: 'worker-assets',
+        resolveId(id) {
+            return id === VIRTUAL_ID ? RESOLVED_ID : undefined;
+        },
+        load(id) {
+            if (id !== RESOLVED_ID) return undefined;
+            const paths = listFiles(join(clientOutput, '_app', 'immutable', 'workers'))
+                .map((file) => ({ path: relative(clientOutput, file).split('\\').join('/') }))
+                .sort((left, right) => left.path.localeCompare(right.path));
+            return `export const workerAssets = ${JSON.stringify(paths)};`;
+        },
+    };
+}

package/templates/host/app.d.ts.txt

@@ -0,0 +1,31 @@
+import 'unplugin-icons/types/svelte';
+
+declare global {
+	namespace App { }
+	const __BUILD_TIMESTAMP__: string;
+	const __STACK_INFO__: {
+		packages: Record<string, string>;
+		node: string;
+		commit: string;
+		branch: string;
+		dirty: boolean;
+	};
+	interface Window {
+		__storE2E?: import('@hearthlog/runtime/testing/e2e-seed.js').StorE2ESeedApi;
+	}
+}
+
+interface ImportMetaEnv {
+	readonly VITE_LEDGER_SERVICE_URL?: string;
+	readonly VITE_LEDGER_AUTH_TOKEN?: string;
+	readonly VITE_LEDGER_TIMEOUT_MS?: string;
+	readonly VITE_LEDGER_MAX_RETRIES?: string;
+	readonly VITE_LEDGER_ENABLE_REALTIME?: string;
+	readonly VITE_E2E?: string;
+}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv;
+}
+
+export { };

package/templates/host/microlighter.d.ts.txt

@@ -0,0 +1,11 @@
+declare module "microlighter" {
+    interface HighlightOptions {
+        root?: ParentNode;
+        selector?: string;
+        languageAliases?: Record<string, string>;
+    }
+
+    export function highlightAll(
+        options?: HighlightOptions,
+    ): Promise<HTMLElement[]>;
+}

package/templates/module/ci.yml.tmpl

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Builds into a site, unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 24
+      - run: pnpm install
+      # Generates a site that enables this module against the platform range, installs and builds it, then runs the
+      # module's unit tests against that site's generated files.
+      - run: pnpm test
+
+  secrets:
+    name: Secret scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          fetch-depth: 0
+      - name: Install gitleaks
+        run: |
+          version=8.30.1
+          curl -sSfL -o gitleaks.tar.gz "https://github.com/gitleaks/gitleaks/releases/download/v${version}/gitleaks_${version}_linux_x64.tar.gz"
+          echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb  gitleaks.tar.gz" | sha256sum --check
+          tar xzf gitleaks.tar.gz gitleaks
+      - run: ./gitleaks git --redact --no-banner --verbose .
+      - run: ./gitleaks dir --redact --no-banner --verbose .

package/templates/module/gitignore.tmpl

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.DS_Store
+.env
+.env.*
+.dev.vars
+.wrangler/

package/templates/module/gitleaks.toml.tmpl

@@ -0,0 +1,11 @@
+title = "hearthlog"
+
+[extend]
+useDefault = true
+
+# Entity definitions name the fields of an event payload (`payloadKey: "caloriesPer100g"`); a field name that ends in
+# digits and a letter looks like a key to the generic rule, but it is not a credential.
+[[allowlists]]
+description = "payloadKey names a payload field"
+regexTarget = "line"
+regexes = ['''payloadKey:\s*["'][A-Za-z0-9_]+["']''']

package/templates/module/release.yml.tmpl

@@ -0,0 +1,53 @@
+name: Release
+
+# Set "version" in package.json, commit, then push the tag `v<version>`. The publish job waits for approval in the
+# protected `npm` environment; the registry credential is the organization secret NPM_TOKEN.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 24
+      - name: The tag names the version in package.json
+        run: test "$GITHUB_REF_NAME" = "v$(node -p "require('./package.json').version")"
+      - run: pnpm install
+      - run: pnpm test
+
+  publish:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: npm
+    permissions:
+      contents: read
+      id-token: write # provenance
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install
+      - run: pnpm publish --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - run: gh release create "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --title "$GITHUB_REF_NAME" --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

package/templates/tenant/README.md.tmpl

@@ -0,0 +1,13 @@
+# {{title}}
+
+A Hearthlog site. `tenants/{{id}}/tenant.json` says what it enables, `tenants/{{id}}/modules.lock.json` records the
+modules it ships, and 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/
+```
+
+`tenants.json` holds placeholder infrastructure names: it makes the site load, and it cannot be deployed until real
+values replace them.

package/templates/tenant/generated-package.json.tmpl

@@ -0,0 +1,16 @@
+{
+  "name": "@hearthlog/generated",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./schema": "./src/schema.generated.ts",
+    "./types": "./src/types.generated.ts",
+    "./standard-commands": "./src/standard-commands.generated.ts",
+    "./standard-db": "./src/standard-db.generated.ts",
+    "./module-repositories": "./src/module-repositories.generated.ts",
+    "./modules": "./src/modules.generated.ts",
+    "./module-icons": "./src/module-icons.generated.ts",
+    "./event-schemas": "./src/event-schemas.generated.ts"
+  }
+}

package/templates/tenant/github-workflows/deploy.yml.tmpl

@@ -0,0 +1,111 @@
+name: Deploy {{id}}
+
+# Two jobs. `build` has no secrets: it installs the locked dependencies, builds the site, and seals the result in
+# artifact-manifest.json. `deploy` runs in the protected `{{id}}` environment, so it starts only once a reviewer
+# approves, and it is the only job that holds secrets. It installs the same lockfile with scripts disabled, checks the
+# manifest, and deploys what `build` made. It never creates a Ledger token or signing key: provision the stack once
+# on your machine with `hearthlog apply`. Each run uploads its receipt (no secrets) as an artifact.
+#
+# In the `{{id}}` environment: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and LEDGER_ADMIN_TOKEN (the administrator
+# token of this site's Ledger); optionally INVOICE_RENDERER_TOKEN, VERTEX_API_KEY, and VERTEX_SERVICE_ACCOUNT.
+
+on:
+  pull_request:
+  push:
+    branches: [main]{{pushPaths}}
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: Validate and bundle without uploading
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build {{id}}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 24
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Build and seal
+        env:
+          VITE_STOR_TENANT: {{id}}
+        run: |
+          pnpm exec hearthlog build
+          pnpm exec hearthlog gallery-public:build --site {{id}}
+          pnpm exec vite build
+          pnpm exec hearthlog artifact manifest --site {{id}}
+      # After the build: the plan reads the generated files the build writes.
+      - name: Plan (read-only)
+        run: pnpm exec hearthlog plan --site {{id}}
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release
+          path: |
+            build
+            .generated
+            artifact-manifest.json
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 14
+
+  deploy:
+    name: Deploy {{id}}
+    needs: build
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment: {{id}}
+    concurrency:
+      group: deploy-{{id}}
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 24
+          cache: pnpm
+      # No lifecycle script of any dependency runs in the job that holds the secrets.
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile --ignore-scripts
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release
+          path: .
+      - name: Check the release against its manifest
+        run: pnpm exec hearthlog artifact verify --site {{id}}
+      - name: Deploy
+        env:
+          DRY_RUN: ${{ github.event.inputs.dry_run }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          LEDGER_ADMIN_TOKEN_{{idUpper}}: ${{ secrets.LEDGER_ADMIN_TOKEN }}
+          INVOICE_RENDERER_TOKEN: ${{ secrets.INVOICE_RENDERER_TOKEN }}
+          INVOICE_EXTRACTION_API_KEY: ${{ secrets.VERTEX_API_KEY }}
+          INVOICE_EXTRACTION_SERVICE_ACCOUNT: ${{ secrets.VERTEX_SERVICE_ACCOUNT }}
+        run: |
+          set -euo pipefail
+          args=(--site {{id}} --yes --skip-build --no-bootstrap)
+          if [ "$DRY_RUN" = "true" ]; then args+=(--dry-run); fi
+          pnpm exec hearthlog apply "${args[@]}"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        if: always()
+        with:
+          name: receipt
+          path: .wrangler/tenants/{{id}}/receipt.json
+          include-hidden-files: true
+          if-no-files-found: ignore
+          retention-days: 90

package/templates/tenant/gitignore.tmpl

@@ -0,0 +1,11 @@
+# What `hearthlog build` writes; only .generated/package.json is committed.
+/.generated/*
+!/.generated/package.json
+/.svelte-kit/
+/build/
+# The seal of a build (`hearthlog artifact manifest`): it travels with the release artifact, not with the source.
+/artifact-manifest.json
+node_modules/
+# Native apps (`hearthlog apple:*`): build output and personal device settings
+/.apple-build/
+/resign.local.json

package/templates/tenant/package.json.tmpl

@@ -0,0 +1,11 @@
+{
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.32.1",
+  "scripts": {
+    "build:generated": "hearthlog build",
+    "dev": "hearthlog build && vite dev",
+    "build": "hearthlog build && vite build",
+    "check": "hearthlog build && svelte-kit sync && tsc --noEmit -p tsconfig.json --skipLibCheck"
+  }
+}

package/templates/tenant/patches/sqlocal@0.18.0.patch

@@ -0,0 +1,18 @@
+diff --git a/dist/processor.js b/dist/processor.js
+--- a/dist/processor.js
++++ b/dist/processor.js
+@@ -453,12 +453,13 @@ export class SQLocalProcessor {
+                 const { queryKey } = message;
+                 try {
+                     const { name, data } = await this.driver.export();
++                    const transfer = data instanceof ArrayBuffer ? data : data.buffer;
+                     this.emitMessage({
+                         type: 'buffer',
+                         queryKey,
+                         bufferName: name,
+                         buffer: data,
+-                    }, [data]);
++                    }, [transfer]);
+                 }
+                 catch (error) {
+                     this.emitMessage({

package/templates/tenant/pnpm-workspace.yaml.tmpl

@@ -0,0 +1,8 @@
+onlyBuiltDependencies:
+  - '@tailwindcss/oxide'
+  - esbuild
+  - sharp
+  - workerd
+
+patchedDependencies:
+  sqlocal@0.18.0: patches/sqlocal@0.18.0.patch

package/templates/tenant/tenants/__id__/tenant.json.tmpl

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "id": "{{id}}",
+  "ledgerAppName": "{{id}}",
+  "title": "{{title}}",
+  "features": {{features}},
+  "authorizedEmails": ["owner@example.com"]
+}

package/templates/tenant/tenants.json.tmpl

@@ -0,0 +1,17 @@
+{
+  "infrastructure": {
+    "ledgerWorker": "example-ledger",
+    "invoicePdfsBucket": "example-invoice-pdfs",
+    "calendarFeedsBucket": "example-calendar-feeds",
+    "calendarPublicWorker": "example-calendar-public",
+    "calendarPublicOrigin": "https://example-calendar-public.example.workers.dev",
+    "galleryFilesBucket": "example-gallery-files",
+    "galleryPublicBucket": "example-gallery-public",
+    "galleryPublicWorker": "example-gallery-public",
+    "galleryPublicOrigin": "https://example-gallery-public.example.workers.dev",
+    "workersDevDomain": "example.workers.dev",
+    "ledgerAdminEmail": "owner@example.com",
+    "accessTeamDomain": "https://example.cloudflareaccess.com"
+  },
+  "sites": []
+}

package/templates/tenant/tsconfig.json.tmpl

@@ -0,0 +1,21 @@
+{
+	"extends": ["$app/tsconfig", "./.generated/tsconfig.json"],
+	"compilerOptions": {
+		"strict": true,
+		"noUnusedLocals": true,
+		"types": ["node", "$app/types"]
+	},
+	"include": [
+		".svelte-kit/ambient.d.ts",
+		".svelte-kit/env.d.ts",
+		".svelte-kit/non-ambient.d.ts",
+		".svelte-kit/types/**/$types.d.ts",
+		"vite.config.ts",
+		".generated/routes/**/*.ts",
+		".generated/routes/**/*.svelte",
+		".generated/*.d.ts",
+		"src/**/*.ts",
+		"src/**/*.svelte"
+	],
+	"exclude": ["node_modules/**"]
+}

package/templates/tenant/vite.config.ts.tmpl

@@ -0,0 +1,5 @@
+// The site's Vite configuration is the shared one; the import is a relative path because Vite's config
+// loader cannot load TypeScript from a package by name.
+import { hearthlogConfig } from './node_modules/@hearthlog/tooling/src/vite/config.ts';
+
+export default hearthlogConfig();

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.