@hearthlog/tooling 0.1.5 → 0.1.7

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.7",
   "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.7"
   },
   "bin": {
     "hearthlog": "./bin/hearthlog.mjs"

package/src/deploy/ensure-tenant.ts

@@ -108,6 +108,7 @@ import {
 import {
 	generateTenantWranglerConfigs,
 	moduleBindings,
+	serverDeclarations,
 	resolveFrontendWranglerTarget,
 } from "../tenants/wrangler-config.js";
 
@@ -694,7 +695,7 @@ async function ensureLedgerApp(
  * `LEDGER_ADMIN_TOKEN` environment variable is only the fallback when no Ledger was contacted (`--skip-ledger`).
  */
 export async function collectSecrets(
-	site: Pick<ResolvedSite, "id" | "admin" | "integrations">,
+	site: Pick<ResolvedSite, "id" | "admin" | "integrations"> & Partial<Pick<ResolvedSite, "features">>,
 	infrastructure: Pick<InfrastructureDefinition, "accessTeamDomain">,
 	ledgerToken: string | null,
 	accessAud: string | undefined,
@@ -718,10 +719,26 @@ export async function collectSecrets(
 	// The renderer's credential comes from the operator's environment; without one the renderer routes answer 503.
 	const rendererToken = process.env.INVOICE_RENDERER_TOKEN?.trim();
 	if (rendererToken) secrets.INVOICE_RENDERER_TOKEN = rendererToken;
-	Object.assign(secrets, extractionSecretsFromEnvironment());
+	Object.assign(secrets, extractionSecretsFromEnvironment(), moduleSecretsFromEnvironment(site.id, serverDeclarations(site.features ?? [])));
 	return secrets;
 }
 
+/** Site-scoped operator variables take precedence when provisioning several gateways. Values never enter generated files. */
+export function moduleSecretsFromEnvironment(
+    siteId: string,
+    servers: ReadonlyArray<{ secrets?: ReadonlyArray<{ name: string }> }>,
+    environment: Record<string, string | undefined> = process.env,
+): Record<string, string> {
+    const result: Record<string, string> = {};
+    const suffix = siteId.toUpperCase().replace(/-/g, '_');
+    for (const server of servers) for (const { name } of server.secrets ?? []) {
+        const value = environment[`${name}_${suffix}`]?.trim() || environment[name]?.trim();
+        if (!value) throw new TenantConfigError(`Site ${siteId}: supply ${name}_${suffix} (or ${name}) in the operator environment before setting module secrets`);
+        result[name] = value;
+    }
+    return result;
+}
+
 /**
  * Vertex AI credentials for AI invoice reading. Absent credentials are not a
  * failure: the feature answers 503 and the UI hides itself.

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/init/check-module.ts

@@ -43,6 +43,14 @@ export function assembleCheckSite(options: Required<Pick<CheckModuleOptions, "di
         mkdirSync(dirname(target), { recursive: true });
         writeFileSync(target, content, "utf8");
     }
+    // Required external module variables need harmless placeholders in this isolated build, not operator storage.
+    const configPath = join(options.work, "tenants.json");
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    for (const variable of loaded.manifest.server?.vars ?? []) {
+        if (variable.optional || config.infrastructure[variable.resource]) continue;
+        config.infrastructure[variable.resource] = /Endpoint$|Origin$/.test(variable.resource) ? 'https://storage.example.invalid' : /Region$/.test(variable.resource) ? 'us-east-1' : 'module-check-storage';
+    }
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
     const manifestPath = join(options.work, "package.json");
     const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as { dependencies: Record<string, string> };
     manifest.dependencies[name] = `file:${directory}`;
@@ -82,6 +90,12 @@ export function testConfig(directory: string, work: string): string {
         { find: "$tenant/generated", replacement: join(work, ".generated", "sites", "st", "tenant.ts") },
         { find: /^\$app\/.*/ as unknown as string, replacement: join(work, "app-stub.mjs") },
     ];
+    // Test the same platform the composed site built, including unreleased --overrides, rather than the module's older dev dependency.
+    const sdk = join(work, "node_modules", "@hearthlog", "sdk");
+    const sdkManifest = JSON.parse(readFileSync(join(sdk, "package.json"), "utf8")) as { exports: Record<string, string> };
+    for (const [entry, file] of Object.entries(sdkManifest.exports)) {
+        if (entry.startsWith('./') && typeof file === 'string') alias.push({ find: `@hearthlog/sdk/${entry.slice(2)}`, replacement: join(sdk, file) });
+    }
     const stub = join(work, "node_modules", "@hearthlog", "cloudflare", "src", "testing", "cloudflare-workers.ts");
     if (existsSync(stub)) alias.push({ find: "cloudflare:workers", replacement: stub });
     const options = JSON.stringify({ root: directory, resolve: { alias } }, null, 2).replace('"find": {}', '"find": /^\\$app\\/.*/');

package/src/security/audit-push.ts

@@ -30,7 +30,7 @@ export interface PushFinding {
     detail: string;
 }
 
-const SAFE_NOREPLY = /^(?:noreply@github\.com|[0-9]*\+?[a-z0-9-]+@users\.noreply\.github\.com)$/i;
+const SAFE_NOREPLY = /^(?:noreply@github\.com|[0-9]*\+?[a-z0-9-]+(?:\[bot\])?@users\.noreply\.github\.com)$/i;
 
 /** Every file under the directory except `.git`, as relative paths. */
 export function listFiles(directory: string): string[] {

package/src/tenants/tenant-config.ts

@@ -54,6 +54,11 @@ export interface SiteTheme {
 }
 
 export interface SiteDefinition {
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    stashMediaProxy?: string;
+
     id: string;
     ledgerAppName?: string;
     admin?: boolean;
@@ -95,6 +100,12 @@ export interface InfrastructureDefinition {
     galleryPublicBucket: string;
     galleryPublicWorker: string;
     galleryPublicOrigin: string;
+    /** Private S3-compatible video storage, provisioned separately by the site operator. */
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    /** "1" streams playback through the gateway instead of redirecting to storage. */
+    stashMediaProxy?: string;
     /** The account's workers.dev subdomain, for example `example.workers.dev`; Worker URLs derive from it. */
     workersDevDomain: string;
     /** The invoice renderer's HTTPS origin; Invoices answers 503 without one. */
@@ -119,6 +130,13 @@ export interface InfrastructureDefinition {
 
 /** `tenants/<site>/deployment.json`: a site that runs on its own stack. */
 export interface SiteDeployment {
+    /** Private S3-compatible video storage, provisioned separately by the site operator. */
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    /** "1" streams playback through the gateway instead of redirecting to storage. */
+    stashMediaProxy?: string;
+
     schemaVersion: 1;
     /**
      * Prefix of every resource the site owns, starting with the site id, for
@@ -160,6 +178,11 @@ export interface TenantFile {
 }
 
 export interface ResolvedSite {
+    stashMediaEndpoint?: string;
+    stashMediaBucket?: string;
+    stashMediaRegion?: string;
+    stashMediaProxy?: string;
+
     id: string;
     ledgerAppName: string;
     features: FeatureId[];
@@ -208,10 +231,12 @@ const SITE_KEYS = [
     "dynamicEntities",
     "theme",
     "hostname",
+    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
 ] as const satisfies readonly (keyof SiteDefinition)[];
 const DEPLOYMENT_KEYS = [
     "$schema", "schemaVersion", "resourcePrefix", "ledger", "accountId", "workersDevDomain", "authentication",
     "ledgerAdminEmail", "invoiceRendererOrigin", "kalApiOrigin", "accessSessionDuration", "accessGlobalSessionDuration",
+    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
 ] as const;
 const TENANT_FILE_KEYS = ["$schema", "schemaVersion", ...SITE_KEYS] as const;
 const WORKERS_DEV_PATTERN = /^[a-z0-9][a-z0-9-]*\.workers\.dev$/;
@@ -240,6 +265,7 @@ const INFRASTRUCTURE_KEYS = [
     "accessSessionDuration",
     "accessGlobalSessionDuration",
     "gallerySweeper",
+    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
     "accountId",
 ] as const satisfies readonly (keyof InfrastructureDefinition)[];
 
@@ -491,6 +517,7 @@ export function parseSiteDeployment(
         requireSessionDuration(`${label} ${key}`, duration);
         result[key] = duration;
     }
+    Object.assign(result, parseStashMediaConfiguration(deployment, label));
     if (options.standalone) {
         for (const key of ["workersDevDomain", "ledgerAdminEmail", "authentication"] as const) {
             if (result[key] === undefined) throw new TenantConfigError(`${label}: ${key} is required when there is no tenants.json`);
@@ -499,6 +526,22 @@ export function parseSiteDeployment(
     return result;
 }
 
+/** Validate optional media settings without requiring storage for sites that do not enable it. */
+export function parseStashMediaConfiguration(value: Partial<InfrastructureDefinition>, label: string): Partial<InfrastructureDefinition> {
+    const result: Partial<InfrastructureDefinition> = {};
+    for (const key of ['stashMediaEndpoint', 'stashMediaBucket', 'stashMediaRegion', 'stashMediaProxy'] as const) {
+        const text = value[key];
+        if (text === undefined) continue;
+        if (typeof text !== 'string' || !text.trim()) throw new TenantConfigError(`${label}.${key} must be a non-empty string`);
+        if (key === 'stashMediaEndpoint') requireHttpsOrigin(`${label}.${key}`, text);
+        if (key === 'stashMediaBucket' && !/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(text)) throw new TenantConfigError(`${label}.${key} must be an S3 bucket name`);
+        if (key === 'stashMediaRegion' && !/^[a-z0-9-]+$/.test(text)) throw new TenantConfigError(`${label}.${key} must be an S3 region`);
+        if (key === 'stashMediaProxy' && !['0', '1'].includes(text)) throw new TenantConfigError(`${label}.${key} must be 0 or 1`);
+        result[key] = text;
+    }
+    return result;
+}
+
 function requireSessionDuration(label: string, duration: unknown): asserts duration is string {
     if (typeof duration !== "string" || !/^[1-9]\d*h$/.test(duration) || Number(duration.slice(0, -1)) > 720) {
         throw new TenantConfigError(`${label} must be whole hours between 1h and 720h`);
@@ -527,10 +570,10 @@ export function workersDevDomainFor(site: Pick<ResolvedSite, "deployment">, shar
  * every name from its resource prefix. Account-wide settings stay shared.
  */
 export function infrastructureFor(
-    site: Pick<ResolvedSite, "deployment">,
+    site: Pick<ResolvedSite, "deployment"> & Partial<Pick<ResolvedSite, "stashMediaEndpoint" | "stashMediaBucket" | "stashMediaRegion" | "stashMediaProxy">>,
     shared: InfrastructureDefinition,
 ): InfrastructureDefinition {
-    if (!site.deployment) return shared;
+    if (!site.deployment) return { ...shared, ...parseStashMediaConfiguration(site, "site") };
     const prefix = site.deployment.resourcePrefix;
     const origin = (worker: string) => `https://${worker}.${workersDevDomainFor(site, shared)}`;
     const names = {
@@ -547,6 +590,8 @@ export function infrastructureFor(
     return {
         ...shared,
         ...names,
+        ...parseStashMediaConfiguration(site.deployment, "site deployment"),
+        ...parseStashMediaConfiguration(site, "site"),
         workersDevDomain: workersDevDomainFor(site, shared),
         ...(site.deployment.authentication ? { accessTeamDomain: site.deployment.authentication.teamDomain } : {}),
         ...(site.deployment.ledgerAdminEmail ? { ledgerAdminEmail: site.deployment.ledgerAdminEmail } : {}),
@@ -670,6 +715,7 @@ export function resolveSite(
     return {
         id: site.id,
         ledgerAppName: site.ledgerAppName ?? site.id,
+        ...parseStashMediaConfiguration(site, label),
         features: [...features],
         ai: [...ai],
         integrations,
@@ -824,6 +870,7 @@ export function resolveInfrastructure(
         const duration = infrastructure[key];
         if (duration !== undefined) requireSessionDuration(`tenants.json infrastructure.${key}`, duration);
     }
+    parseStashMediaConfiguration(infrastructure, "tenants.json infrastructure");
     return infrastructure;
 }
 

package/src/tenants/tenant-schema.ts

@@ -78,6 +78,10 @@ export function buildTenantSchema(): Record<string, unknown> {
                     workersDevDomain: { type: "string", pattern: "^[a-z0-9][a-z0-9-]*\\.workers\\.dev$", description: "The account's workers.dev subdomain." },
                     invoiceRendererOrigin: httpsOrigin,
                     kalApiOrigin: httpsOrigin,
+                    stashMediaEndpoint: httpsOrigin,
+                    stashMediaBucket: nonEmptyString,
+                    stashMediaRegion: nonEmptyString,
+                    stashMediaProxy: { enum: ["0", "1"] },
                     ledgerAdminEmail: { type: "string", format: "email" },
                     accessTeamDomain: httpsOrigin,
                     accessSessionDuration: hours,
@@ -140,6 +144,10 @@ export function buildTenantSchema(): Record<string, unknown> {
                             },
                         },
                         hostname: { type: "string", format: "uri" },
+                        stashMediaEndpoint: httpsOrigin,
+                        stashMediaBucket: nonEmptyString,
+                        stashMediaRegion: nonEmptyString,
+                        stashMediaProxy: { enum: ["0", "1"] },
                     },
                 },
             },

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';
@@ -20,20 +21,11 @@ import {
 	localLedgerGatewayPath,
 	localLedgerOriginGuardPlugin,
 	localReceivedInvoiceFilesPlugin,
+	localStashMediaPlugin,
 } from './dev-plugins.js';
 
 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 +126,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');
@@ -283,6 +276,7 @@ return defineConfig(({ command, mode }): UserConfig => {
                 localLedgerOriginGuardPlugin(Boolean(localLedgerCredential)),
                 localInvoicePdfGatewayFallbackPlugin(Boolean(invoiceRendererToken)),
                 localReceivedInvoiceFilesPlugin(),
+                localStashMediaPlugin(localLedgerCredential),
                 localInvoiceExtractionPlugin(),
                 localAiDecisionsPlugin(isE2E),
                 e2eLedgerStubPlugin(isE2E),
@@ -310,7 +304,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/dev-plugins.ts

@@ -336,3 +336,42 @@ export async function readJsonBody(request: import('node:http').IncomingMessage)
         return undefined;
     }
 }
+
+/** Real S3 signing against loopback MinIO; no production credentials or Access bypass reach a deployed build. */
+export function localStashMediaPlugin(credential?: import('../dev/local-development.js').LocalLedgerCredential): Plugin {
+    return {
+        name: 'local-stash-media',
+        configureServer(server) {
+            server.middlewares.use(async (incoming, outgoing, next) => {
+                if (!incoming.url?.startsWith('/api/stash-media/v1/')) return next();
+                const respond = (status: number, message: string) => { outgoing.statusCode = status; outgoing.setHeader('Content-Type', 'application/json'); outgoing.end(JSON.stringify({ error: message, code: 'local_media_unavailable' })); };
+                if (!localGatewayOriginAllowed(incoming.headers.origin, incoming.headers.host) || incoming.headers['sec-fetch-site'] === 'cross-site') return respond(403, 'Cross-origin local media requests are not allowed');
+                if (!credential) return respond(503, 'Start the local Ledger and run ledger:provision-local before uploading videos locally');
+                try {
+                    const [{ loadModules }, { loadTenantConfig }, { activeSiteId }] = await Promise.all([import('../compose/compose-modules.js'), import('../tenants/tenant-config.js'), import('../root.js')]);
+                    const config = await loadTenantConfig(), site = config.sites.find(site => site.id === activeSiteId());
+                    const module = loadModules().find(module => module.manifest.server?.routes?.includes('/api/stash-media/v1') && module.manifest.features.some(feature => site?.features.some(enabled => enabled === feature.id)));
+                    if (!module) return respond(404, 'Video media is not enabled for this site');
+                    const endpoint = new URL(process.env.STASH_MEDIA_DEV_ENDPOINT || 'http://127.0.0.1:9000');
+                    if (!['localhost', '127.0.0.1', '[::1]'].includes(endpoint.hostname)) return respond(503, 'Development media storage must use a loopback MinIO endpoint');
+                    const { handleStashMediaRequest } = await server.ssrLoadModule(`${module.directory}/src/server/media.ts`);
+                    const chunks: Buffer[] = []; let size = 0;
+                    for await (const chunk of incoming) { size += chunk.length; if (size > 1024 * 1024) return respond(413, 'Media control request is too large'); chunks.push(Buffer.from(chunk)); }
+                    const headers = new Headers();
+                    for (const [name, value] of Object.entries(incoming.headers)) if (typeof value === 'string') headers.set(name, value);
+                    const request = new Request(new URL(incoming.url, `http://${incoming.headers.host}`), { method: incoming.method, headers, ...(size ? { body: Buffer.concat(chunks) } : {}) });
+                    const env = {
+                        STASH_MEDIA_ENDPOINT: endpoint.origin, STASH_MEDIA_BUCKET: 'hearthlog-dev', STASH_MEDIA_REGION: 'us-east-1',
+                        STASH_MEDIA_KEY_ID: 'hearthlog-local', STASH_MEDIA_APP_KEY: 'hearthlog-local-only', LEDGER_AUTH_TOKEN: credential.token,
+                        LEDGER: { fetch: (request: Request) => { const url = new URL(request.url); return fetch(new URL(`${url.pathname}${url.search}`, credential.baseUrl), { method: request.method, headers: request.headers }); } },
+                    };
+                    const response: Response = await handleStashMediaRequest(request, env, async () => ({ email: 'local@example.invalid' }));
+                    outgoing.statusCode = response.status;
+                    response.headers.forEach((value, name) => outgoing.setHeader(name, value));
+                    if (response.body) for await (const chunk of response.body) outgoing.write(chunk);
+                    outgoing.end();
+                } catch { respond(503, 'Local video storage is unavailable. Check that MinIO and the local Ledger are running'); }
+            });
+        },
+    };
+}

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"
   }