@hearthlog/tooling 0.1.8 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hearthlog/tooling",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "tsx": "^4.23.15",
-    "@hearthlog/contracts": "0.1.8"
+    "@hearthlog/contracts": "0.2.0"
   },
   "bin": {
     "hearthlog": "./bin/hearthlog.mjs"

package/src/init/check-module.ts

@@ -18,6 +18,8 @@ import { createRequire } from "node:module";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { moduleSettingPlaceholder } from "@hearthlog/contracts";
+
 import { loadModuleAt } from "../compose/compose-modules.js";
 import { renderSite } from "./init.js";
 
@@ -47,8 +49,13 @@ export function assembleCheckSite(options: Required<Pick<CheckModuleOptions, "di
     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';
+        if (variable.optional) continue;
+        if ("resource" in variable) {
+            config.infrastructure[variable.resource] ??= /Origin$/.test(variable.resource) ? 'https://module-check.example.invalid' : 'module-check';
+            continue;
+        }
+        const settings = ((config.infrastructure.moduleSettings ??= {})[loaded.manifest.id] ??= {});
+        settings[variable.setting] ??= moduleSettingPlaceholder(variable);
     }
     writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
     const manifestPath = join(options.work, "package.json");

package/src/tenants/tenant-config.ts

@@ -53,12 +53,13 @@ export interface SiteTheme {
     accent?: string;
 }
 
-export interface SiteDefinition {
-    stashMediaEndpoint?: string;
-    stashMediaBucket?: string;
-    stashMediaRegion?: string;
-    stashMediaProxy?: string;
+/**
+ * Settings a module declares in its manifest (`server.vars[].setting`), by module id and then setting key.
+ * The core checks only the shape here; the module's manifest decides which keys exist and what they look like.
+ */
+export type ModuleSettings = Record<string, Record<string, string>>;
 
+export interface SiteDefinition {
     id: string;
     ledgerAppName?: string;
     admin?: boolean;
@@ -82,6 +83,8 @@ export interface SiteDefinition {
     dynamicEntities?: boolean;
     theme?: SiteTheme;
     hostname?: string;
+    /** Module settings for this site only; they override the deployment's and the shared ones key by key. */
+    moduleSettings?: ModuleSettings;
 }
 
 export interface InfrastructureDefinition {
@@ -100,12 +103,8 @@ 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;
+    /** Module settings every site shares unless its deployment or its own definition overrides them. */
+    moduleSettings?: ModuleSettings;
     /** 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. */
@@ -130,13 +129,6 @@ 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
@@ -157,6 +149,8 @@ export interface SiteDeployment {
     kalApiOrigin?: string;
     accessSessionDuration?: string;
     accessGlobalSessionDuration?: string;
+    /** Module settings of this stack; the site's own override them key by key. */
+    moduleSettings?: ModuleSettings;
 }
 
 export interface TenantFile {
@@ -178,11 +172,6 @@ export interface TenantFile {
 }
 
 export interface ResolvedSite {
-    stashMediaEndpoint?: string;
-    stashMediaBucket?: string;
-    stashMediaRegion?: string;
-    stashMediaProxy?: string;
-
     id: string;
     ledgerAppName: string;
     features: FeatureId[];
@@ -202,6 +191,8 @@ export interface ResolvedSite {
     deployment: SiteDeployment | null;
     /** The site came from `tenants/<id>/tenant.json` rather than `tenants.json`. */
     fromTenantFile: boolean;
+    /** The site's own module settings; `infrastructureFor` layers them over the stack's. */
+    moduleSettings?: ModuleSettings;
 }
 
 export class TenantConfigError extends Error {
@@ -231,12 +222,12 @@ const SITE_KEYS = [
     "dynamicEntities",
     "theme",
     "hostname",
-    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
+    "moduleSettings",
 ] 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",
+    "moduleSettings",
 ] as const;
 const TENANT_FILE_KEYS = ["$schema", "schemaVersion", ...SITE_KEYS] as const;
 const WORKERS_DEV_PATTERN = /^[a-z0-9][a-z0-9-]*\.workers\.dev$/;
@@ -265,7 +256,7 @@ const INFRASTRUCTURE_KEYS = [
     "accessSessionDuration",
     "accessGlobalSessionDuration",
     "gallerySweeper",
-    "stashMediaEndpoint", "stashMediaBucket", "stashMediaRegion", "stashMediaProxy",
+    "moduleSettings",
     "accountId",
 ] as const satisfies readonly (keyof InfrastructureDefinition)[];
 
@@ -517,7 +508,7 @@ export function parseSiteDeployment(
         requireSessionDuration(`${label} ${key}`, duration);
         result[key] = duration;
     }
-    Object.assign(result, parseStashMediaConfiguration(deployment, label));
+    if (deployment.moduleSettings !== undefined) result.moduleSettings = parseModuleSettings(deployment.moduleSettings, `${label} moduleSettings`);
     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`);
@@ -526,22 +517,38 @@ 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;
+const MODULE_ID_PATTERN = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9-]*)+$/;
+const SETTING_KEY_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+
+/**
+ * Check the shape of a `moduleSettings` block: module ids to setting keys to non-empty strings. Which keys a
+ * module accepts, and their formats, are checked against its manifest when its Worker is configured.
+ */
+export function parseModuleSettings(value: unknown, label: string): ModuleSettings {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TenantConfigError(`${label} must be an object`);
+    const result: ModuleSettings = {};
+    for (const [moduleId, settings] of Object.entries(value)) {
+        if (!MODULE_ID_PATTERN.test(moduleId)) throw new TenantConfigError(`${label}: "${moduleId}" is not a module id`);
+        if (typeof settings !== "object" || settings === null || Array.isArray(settings)) throw new TenantConfigError(`${label}.${moduleId} must be an object`);
+        result[moduleId] = {};
+        for (const [key, setting] of Object.entries(settings)) {
+            if (!SETTING_KEY_PATTERN.test(key)) throw new TenantConfigError(`${label}.${moduleId}: "${key}" is not a setting key`);
+            if (typeof setting !== "string" || !setting.trim()) throw new TenantConfigError(`${label}.${moduleId}.${key} must be a non-empty string`);
+            result[moduleId][key] = setting;
+        }
     }
     return result;
 }
 
+/** Layer module settings key by key; later layers win. */
+export function mergeModuleSettings(...layers: ReadonlyArray<ModuleSettings | undefined>): ModuleSettings | undefined {
+    const present = layers.filter((layer): layer is ModuleSettings => layer !== undefined);
+    if (!present.length) return undefined;
+    const result: ModuleSettings = {};
+    for (const layer of present) for (const [moduleId, settings] of Object.entries(layer)) result[moduleId] = { ...result[moduleId], ...settings };
+    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`);
@@ -570,10 +577,12 @@ 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"> & Partial<Pick<ResolvedSite, "stashMediaEndpoint" | "stashMediaBucket" | "stashMediaRegion" | "stashMediaProxy">>,
+    site: Pick<ResolvedSite, "deployment"> & Partial<Pick<ResolvedSite, "moduleSettings">>,
     shared: InfrastructureDefinition,
 ): InfrastructureDefinition {
-    if (!site.deployment) return { ...shared, ...parseStashMediaConfiguration(site, "site") };
+    const moduleSettings = mergeModuleSettings(shared.moduleSettings, site.deployment?.moduleSettings, site.moduleSettings);
+    const withSettings = moduleSettings ? { moduleSettings } : {};
+    if (!site.deployment) return { ...shared, ...withSettings };
     const prefix = site.deployment.resourcePrefix;
     const origin = (worker: string) => `https://${worker}.${workersDevDomainFor(site, shared)}`;
     const names = {
@@ -590,8 +599,7 @@ export function infrastructureFor(
     return {
         ...shared,
         ...names,
-        ...parseStashMediaConfiguration(site.deployment, "site deployment"),
-        ...parseStashMediaConfiguration(site, "site"),
+        ...withSettings,
         workersDevDomain: workersDevDomainFor(site, shared),
         ...(site.deployment.authentication ? { accessTeamDomain: site.deployment.authentication.teamDomain } : {}),
         ...(site.deployment.ledgerAdminEmail ? { ledgerAdminEmail: site.deployment.ledgerAdminEmail } : {}),
@@ -715,7 +723,7 @@ export function resolveSite(
     return {
         id: site.id,
         ledgerAppName: site.ledgerAppName ?? site.id,
-        ...parseStashMediaConfiguration(site, label),
+        ...(site.moduleSettings !== undefined ? { moduleSettings: parseModuleSettings(site.moduleSettings, `${label} moduleSettings`) } : {}),
         features: [...features],
         ai: [...ai],
         integrations,
@@ -870,7 +878,7 @@ export function resolveInfrastructure(
         const duration = infrastructure[key];
         if (duration !== undefined) requireSessionDuration(`tenants.json infrastructure.${key}`, duration);
     }
-    parseStashMediaConfiguration(infrastructure, "tenants.json infrastructure");
+    if (infrastructure.moduleSettings !== undefined) parseModuleSettings(infrastructure.moduleSettings, "tenants.json infrastructure.moduleSettings");
     return infrastructure;
 }
 

package/src/tenants/tenant-schema.ts

@@ -16,6 +16,8 @@ import { fileURLToPath } from "node:url";
 import { FEATURES } from "@hearthlog/contracts/features/registry";
 import { AI_CAPABILITIES } from "@hearthlog/contracts/ai/capabilities";
 import { INTEGRATION_ID_PATTERN, INTEGRATION_KINDS } from "@hearthlog/contracts/integrations/kinds";
+import type { ModuleSettingFormat } from "@hearthlog/contracts";
+import { loadModules } from "../compose/compose-modules.js";
 import { DEVELOPER_PATH, REPOSITORY_ROOT } from "./tenant-config.js";
 
 export const TENANT_SCHEMA_FILE = join(REPOSITORY_ROOT, "tenants.schema.json");
@@ -26,6 +28,7 @@ const hours = { type: "string", pattern: "^[1-9][0-9]*h$", description: "Whole h
 
 export function buildTenantSchema(): Record<string, unknown> {
     const featureIds = FEATURES.map((feature) => feature.id);
+    const moduleSettings = moduleSettingsSchema();
     const homePaths = [...new Set(["/", DEVELOPER_PATH, ...FEATURES.flatMap((feature) => feature.page ? [feature.page.path] : [])])];
     const shared = {
         features: {
@@ -78,10 +81,7 @@ 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"] },
+                    moduleSettings,
                     ledgerAdminEmail: { type: "string", format: "email" },
                     accessTeamDomain: httpsOrigin,
                     accessSessionDuration: hours,
@@ -144,10 +144,7 @@ export function buildTenantSchema(): Record<string, unknown> {
                             },
                         },
                         hostname: { type: "string", format: "uri" },
-                        stashMediaEndpoint: httpsOrigin,
-                        stashMediaBucket: nonEmptyString,
-                        stashMediaRegion: nonEmptyString,
-                        stashMediaProxy: { enum: ["0", "1"] },
+                        moduleSettings,
                     },
                 },
             },
@@ -155,6 +152,36 @@ export function buildTenantSchema(): Record<string, unknown> {
     };
 }
 
+/** `moduleSettings`, with a block for each installed module that declares settings. */
+function moduleSettingsSchema(): Record<string, unknown> {
+    const properties: Record<string, unknown> = {};
+    for (const { manifest } of loadModules()) {
+        const settings = (manifest.server?.vars ?? []).filter((variable) => "setting" in variable);
+        if (!settings.length) continue;
+        properties[manifest.id] = {
+            type: "object",
+            additionalProperties: false,
+            properties: Object.fromEntries(settings.map((variable) => [variable.setting, settingSchema(variable)])),
+        };
+    }
+    return {
+        type: "object",
+        description: "Settings of installed modules, by module id. A site's override its deployment's, which override the shared ones.",
+        additionalProperties: false,
+        properties,
+    };
+}
+
+function settingSchema(variable: { format?: ModuleSettingFormat; values?: string[] }): Record<string, unknown> {
+    if (variable.values) return { enum: variable.values };
+    switch (variable.format ?? "text") {
+        case "https-origin": return httpsOrigin;
+        case "s3-bucket": return { type: "string", pattern: "^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$" };
+        case "s3-region": return { type: "string", pattern: "^[a-z0-9-]+$" };
+        default: return nonEmptyString;
+    }
+}
+
 export function renderTenantSchema(): string {
     return `${JSON.stringify(buildTenantSchema(), null, 2)}\n`;
 }

package/src/tenants/wrangler-config.ts

@@ -11,7 +11,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, relative } from "node:path";
 
-import type { ModuleManifest } from "@hearthlog/contracts";
+import { moduleSettingProblem, type ModuleManifest } from "@hearthlog/contracts";
 
 import { WRANGLER_BASE } from "./wrangler-base.js";
 import { activeIntegrations } from "@hearthlog/contracts/integrations/kinds";
@@ -21,6 +21,7 @@ import {
     infrastructureFor,
     loadTenantConfig,
     REPOSITORY_ROOT,
+    TenantConfigError,
     type InfrastructureDefinition,
     type ResolvedSite,
     type SiteStack,
@@ -107,7 +108,8 @@ export function siteWorkerFirst(features: readonly string[]): string[] {
 
 /**
  * The bindings and variables a site's modules need, from their manifests.
- * `resource` names a key of the tenant's infrastructure.
+ * A `resource` names a key of the tenant's infrastructure; a `setting` names a key of the module's block in
+ * `infrastructure.moduleSettings`, checked against the format the manifest declares.
  */
 export function moduleBindings(
     features: readonly string[],
@@ -119,17 +121,35 @@ export function moduleBindings(
         if (!value) throw new Error(`The infrastructure has no "${resource}"`);
         return value;
     };
-    const optional = (resource: string): string | undefined => keyed[resource];
     const result = { r2: [] as Array<{ binding: string; bucket_name: string }>, images: false, vars: {} as Record<string, string> };
-    for (const server of serverDeclarations(features)) {
+    for (const { manifest } of modulesForFeatures(loadModules(), features)) {
+        const server = manifest.server;
+        if (!server) continue;
         for (const binding of server.bindings ?? []) {
             if (binding.type === "r2") result.r2.push({ binding: binding.binding, bucket_name: lookup(binding.resource) });
             else result.images = true;
         }
+        const settings = infrastructure.moduleSettings?.[manifest.id] ?? {};
+        const declared = new Set<string>();
         for (const variable of server.vars ?? []) {
-            const value = variable.optional ? optional(variable.resource) : lookup(variable.resource);
-            if (value) result.vars[variable.name] = value;
+            if ("resource" in variable) {
+                const value = variable.optional ? keyed[variable.resource] : lookup(variable.resource);
+                if (value) result.vars[variable.name] = value;
+                continue;
+            }
+            declared.add(variable.setting);
+            const value = settings[variable.setting];
+            const label = `moduleSettings.${manifest.id}.${variable.setting}`;
+            if (value === undefined) {
+                if (variable.optional) continue;
+                throw new TenantConfigError(`${label} is required by ${manifest.id}`);
+            }
+            const problem = moduleSettingProblem(variable, value);
+            if (problem) throw new TenantConfigError(`${label} ${problem}`);
+            result.vars[variable.name] = value;
         }
+        const unknown = Object.keys(settings).filter((key) => !declared.has(key));
+        if (unknown.length) throw new TenantConfigError(`moduleSettings.${manifest.id}: unknown key "${unknown[0]}" (known keys: ${[...declared].join(", ") || "none"})`);
     }
     return result;
 }

package/src/vite/config.ts

@@ -21,7 +21,7 @@ import {
 	localLedgerGatewayPath,
 	localLedgerOriginGuardPlugin,
 	localReceivedInvoiceFilesPlugin,
-	localStashMediaPlugin,
+	localModuleServerPlugin,
 } from './dev-plugins.js';
 
 import { defineConfig, searchForWorkspaceRoot, type ProxyOptions, type UserConfig } from 'vite';
@@ -276,7 +276,7 @@ return defineConfig(({ command, mode }): UserConfig => {
                 localLedgerOriginGuardPlugin(Boolean(localLedgerCredential)),
                 localInvoicePdfGatewayFallbackPlugin(Boolean(invoiceRendererToken)),
                 localReceivedInvoiceFilesPlugin(),
-                localStashMediaPlugin(localLedgerCredential),
+                localModuleServerPlugin(localLedgerCredential),
                 localInvoiceExtractionPlugin(),
                 localAiDecisionsPlugin(isE2E),
                 e2eLedgerStubPlugin(isE2E),

package/src/vite/dev-plugins.ts

@@ -338,48 +338,57 @@ export async function readJsonBody(request: import('node:http').IncomingMessage)
     }
 }
 
-/** 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 {
+/**
+ * Serves the routes of modules that declare a `server.dev` entry, for the active site's enabled modules only. The
+ * entry gets the local Ledger and a stand-in identity; nothing here, nor any module's dev entry, reaches a deployed build.
+ */
+export function localModuleServerPlugin(credential?: import('../dev/local-development.js').LocalLedgerCredential): Plugin {
     return {
-        name: 'local-stash-media',
+        name: 'local-module-server',
         configureServer(server) {
+            type DevModule = { id: string; directory: string; dev: string; routes: string[]; features: string[] };
+            let declared: Promise<DevModule[]> | undefined;
+            // Vite's config bundler follows literal imports even inside this dev-only callback.
+            // Load these through Vite so their TypeScript package dependencies stay out of config loading.
+            const load = (path: string) => server.ssrLoadModule(fileURLToPath(new URL(path, import.meta.url)));
+            const devModules = () => declared ??= load('../compose/compose-modules.js').then(({ loadModules }) =>
+                (loadModules() as ReturnType<typeof import('../compose/compose-modules.js').loadModules>).flatMap(({ directory, manifest }) =>
+                    manifest.server?.dev ? [{ id: manifest.id, directory, dev: manifest.server.dev, routes: manifest.server.routes ?? [], features: manifest.features.map(feature => feature.id) }] : []));
             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');
+                const path = incoming.url?.split('?')[0];
+                if (!path?.startsWith('/api/')) 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_module_unavailable' })); };
+                let found: DevModule | undefined;
+                try {
+                    found = (await devModules()).find(candidate => candidate.routes.some(prefix => path === prefix || path.startsWith(`${prefix}/`)));
+                } catch { return respond(503, 'Local module routes could not be loaded'); }
+                if (!found) return next();
+                const module = found;
+                if (!localGatewayOriginAllowed(incoming.headers.origin, incoming.headers.host) || incoming.headers['sec-fetch-site'] === 'cross-site') return respond(403, 'Cross-origin local module requests are not allowed');
+                if (!credential) return respond(503, 'Start the local Ledger and run ledger:provision-local before using this locally');
                 try {
-                    // Vite's config bundler follows literal imports even inside this dev-only callback.
-                    // Load these through Vite so their TypeScript package dependencies stay out of config loading.
-                    const [{ loadModules }, { loadTenantConfig }, { activeSiteId }] = await Promise.all([
-                        server.ssrLoadModule(fileURLToPath(new URL('../compose/compose-modules.js', import.meta.url))),
-                        server.ssrLoadModule(fileURLToPath(new URL('../tenants/tenant-config.js', import.meta.url))),
-                        server.ssrLoadModule(fileURLToPath(new URL('../root.js', import.meta.url))),
-                    ]);
+                    const [{ loadTenantConfig }, { activeSiteId }] = await Promise.all([load('../tenants/tenant-config.js'), load('../root.js')]);
                     const config: Awaited<ReturnType<typeof import('../tenants/tenant-config.js').loadTenantConfig>> = await loadTenantConfig();
                     const site = config.sites.find(site => site.id === activeSiteId());
-                    const modules: ReturnType<typeof import('../compose/compose-modules.js').loadModules> = loadModules();
-                    const module = modules.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`);
+                    if (!site?.features.some(enabled => module.features.includes(enabled))) return respond(404, `${module.id} is not enabled for this site`);
                     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)); }
+                    for await (const chunk of incoming) { size += chunk.length; if (size > 1024 * 1024) return respond(413, 'Local module 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' }));
+                    const request = new Request(new URL(incoming.url!, `http://${incoming.headers.host}`), { method: incoming.method, headers, ...(size ? { body: Buffer.concat(chunks) } : {}) });
+                    const { default: dev } = await server.ssrLoadModule(`${module.directory}/${module.dev.slice(2)}`) as { default: import('@hearthlog/contracts').DevServerModule };
+                    const response = await dev.handle(request, {
+                        env: {
+                            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 }); } },
+                        },
+                        identity: { 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'); }
+                } catch { respond(503, `${module.id} is unavailable locally. Check that its local services and the local Ledger are running`); }
             });
         },
     };