beehaven 0.8.16

package/dist/local-app-manager.js

@@ -0,0 +1,660 @@
+// ============================================================================
+// LocalAppManager — Hosts Beehaven Buildings locally inside the daemon.
+//
+// The daemon is a hybrid node: it relays events to Clearly cloud AND hosts
+// local Building instances via LocalHive. Cloud DOs can route requests to
+// local Buildings through the relay WebSocket, and local clients can connect
+// directly via the local WebSocket server.
+//
+// Usage:
+//   const manager = new LocalAppManager({ dataDir: '~/.beehaven/apps' });
+//   await manager.loadBuildings('~/my-project/src/buildings');
+//   await manager.start(9876);
+// ============================================================================
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'fs';
+import { join, resolve, basename, extname } from 'path';
+import { homedir } from 'os';
+import { EventEmitter } from 'events';
+import { pathToFileURL } from 'url';
+// ── Manager ──────────────────────────────────────────────────────────────────
+export class LocalAppManager extends EventEmitter {
+    config;
+    localServer = null; // LocalHive instance (lazy-loaded)
+    _running = false;
+    _port = null;
+    _buildings = {};
+    _dataDir;
+    _installedApps = new Map();
+    constructor(config = {}) {
+        super();
+        this.config = config;
+        this._dataDir = config.dataDir ?? join(homedir(), '.beehaven', 'apps');
+    }
+    /** Get current status */
+    status() {
+        return {
+            running: this._running,
+            port: this._port,
+            buildingTypes: Object.keys(this._buildings),
+            activeInstances: this.localServer ? Array.from(this.localServer.active.keys()) : [],
+            dataDir: this._dataDir,
+            apps: this.getAgentCatalog(),
+        };
+    }
+    /**
+     * Compact catalog describing every installed app — the shape Omni /
+     * cloud agents consume to understand what's available on this machine.
+     * Strips secrets and large blobs; includes recipes by id so an agent
+     * can reference them ("run nitepunk-piano:build") without having to
+     * read the whole manifest.
+     *
+     * `frontend.url` and `cloudBuildings[].cloudUrl` pass through template
+     * substitution here (see resolveTemplateVars) so the same manifest
+     * targets dev / staging / prod without per-env .app rebuilds, and so
+     * multi-instance apps (store-per-user) resolve the current user's ids.
+     */
+    getAgentCatalog() {
+        const vars = this.templateVars();
+        const entries = [];
+        for (const h of this._installedApps.values()) {
+            const resolvedFrontendUrl = h.frontendUrl
+                ? resolveTemplateVars(h.frontendUrl, vars)
+                : undefined;
+            entries.push({
+                name: h.name,
+                version: h.version,
+                description: h.manifest.description ?? '',
+                vendor: h.manifest.vendor?.name ?? '',
+                tier: h.manifest.license?.tier ?? 'free',
+                buildings: h.buildings,
+                cloudBuildings: h.cloudBuildings.map((c) => c.name),
+                browserBuildings: h.browserBuildings.map((b) => ({
+                    name: b.name,
+                    url: b.url,
+                    fallbackFor: b.fallbackFor,
+                    handles: b.handles,
+                })),
+                recipes: Object.keys(h.recipes),
+                depends: h.depends,
+                frontend: resolvedFrontendUrl
+                    ? {
+                        title: h.manifest.frontend?.title ?? h.name,
+                        icon: h.manifest.frontend?.icon ?? '',
+                        url: resolvedFrontendUrl,
+                        hosted: h.frontendHosted ?? 'local',
+                        window: h.manifest.frontend?.window ?? null,
+                    }
+                    : null,
+            });
+        }
+        return entries;
+    }
+    /**
+     * Snapshot the template variables substitution uses. Read from the
+     * daemon's env + config every catalog request so an in-flight sign-in
+     * (which writes new values to config) reflects immediately without
+     * daemon restart.
+     */
+    templateVars() {
+        // `webBase` — dev Mac app sets this via env; defaults to production.
+        const webBase = process.env.BEEHAVEN_WEB_BASE ?? process.env.CLEARLY_WEB_BASE ?? 'https://clearly.sh';
+        // User identity — the daemon stores these in config on sign-in
+        // install(), so they're available without decoding the JWT here.
+        const cfg = readDaemonConfigSafe();
+        return {
+            webBase,
+            userId: cfg.user?.uid ?? cfg.user?.userId ?? '',
+            email: cfg.user?.email ?? '',
+            storeId: cfg.activeStoreId ?? cfg.user?.activeStoreId ?? '',
+            teamId: cfg.activeTeamId ?? '',
+            tier: cfg.tier ?? 'local',
+        };
+    }
+    /**
+     * Register a building class manually.
+     * Used by daemon integrations that import building classes directly.
+     */
+    registerBuilding(name, BuildingClass) {
+        this._buildings[name] = BuildingClass;
+        this.emit('building-registered', name);
+    }
+    /**
+     * Load building classes from a directory.
+     * Looks for .ts/.js files that export a class extending Workspace.
+     * Uses dynamic import, so the files must be importable at runtime.
+     */
+    async loadBuildings(dir) {
+        const absDir = resolve(dir);
+        if (!existsSync(absDir)) {
+            this.emit('error', new Error(`Buildings directory not found: ${absDir}`));
+            return [];
+        }
+        const loaded = [];
+        const files = readdirSync(absDir).filter((f) => (f.endsWith('.ts') || f.endsWith('.js')) &&
+            !f.endsWith('.test.ts') &&
+            !f.endsWith('.test.js') &&
+            !f.endsWith('.d.ts'));
+        for (const file of files) {
+            try {
+                const filePath = join(absDir, file);
+                const mod = await import(pathToFileURL(filePath).href);
+                // Find exported classes (look for default export or named exports)
+                const candidates = mod.default ? { [basename(file, extname(file))]: mod.default } : mod;
+                for (const [name, value] of Object.entries(candidates)) {
+                    if (typeof value === 'function' && value.prototype?.fetch) {
+                        // Looks like a Building class (has fetch method on prototype)
+                        const buildingName = name.charAt(0).toLowerCase() + name.slice(1);
+                        this._buildings[buildingName] = value;
+                        loaded.push(buildingName);
+                        this.emit('building-registered', buildingName);
+                    }
+                }
+            }
+            catch (err) {
+                this.emit('error', new Error(`Failed to load ${file}: ${err.message}`));
+            }
+        }
+        return loaded;
+    }
+    /**
+     * Load buildings from a beehaven project config (beehaven.config.ts/json).
+     */
+    async loadFromProject(projectDir) {
+        const absDir = resolve(projectDir);
+        // Try beehaven.config.json first
+        const jsonConfig = join(absDir, 'beehaven.config.json');
+        if (existsSync(jsonConfig)) {
+            try {
+                const config = JSON.parse(readFileSync(jsonConfig, 'utf8'));
+                if (config.buildings && typeof config.buildings === 'object') {
+                    const buildingsDir = join(absDir, config.buildingsDir ?? 'src/buildings');
+                    return this.loadBuildings(buildingsDir);
+                }
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        // Try src/buildings/ convention
+        const conventionDir = join(absDir, 'src', 'buildings');
+        if (existsSync(conventionDir)) {
+            return this.loadBuildings(conventionDir);
+        }
+        return [];
+    }
+    /**
+     * Scan ~/.beehaven/apps/ for installed .app packages and register
+     * them in two passes:
+     *
+     *   Pass 1 — parse every manifest, build the dep graph.
+     *   Pass 2 — topo-sort by depends, load each app in order. An app
+     *            whose dependency is missing or whose dependency load
+     *            failed is marked with an error string and skipped
+     *            (rather than failing the whole scan).
+     *
+     * Building-name conflicts (two apps trying to register the same
+     * building name, e.g. an installed `ableton` vs. a dev-linked `ableton`)
+     * resolve to the FIRST-REGISTERED winner. The later one is skipped with
+     * a visible warning so the dev loop (linkedProject first, installed
+     * apps second) is predictable: your source edits always win.
+     */
+    async loadInstalledApps(hivesRoot) {
+        // Scan ~/.beehaven/apps/ (canonical) and ~/.beehaven/hives/ (legacy).
+        // Accept app.json or hive.json as manifest.
+        const roots = hivesRoot
+            ? (Array.isArray(hivesRoot) ? hivesRoot.map((root) => resolve(root)) : [resolve(hivesRoot)])
+            : [join(homedir(), '.beehaven', 'apps'), join(homedir(), '.beehaven', 'hives')];
+        let entries = [];
+        const seen = new Set(); // dedupe by directory name
+        for (const root of roots) {
+            if (!existsSync(root))
+                continue;
+            try {
+                // A bundled first-party hive is often handed in as its app directory
+                // (Resources/beehaven/hives/avatar), while user-installed roots are
+                // containers of app directories. Accept both shapes so the bundle can
+                // be loaded without copying it into ~/.beehaven/apps.
+                const directManifest = existsSync(join(root, 'app.json')) || existsSync(join(root, 'hive.json'));
+                if (directManifest) {
+                    const parent = resolve(root, '..');
+                    const entry = basename(root);
+                    if (!seen.has(entry)) {
+                        seen.add(entry);
+                        entries.push({ dir: parent, entry });
+                    }
+                    continue;
+                }
+                for (const entry of readdirSync(root)) {
+                    if (!seen.has(entry)) {
+                        seen.add(entry);
+                        entries.push({ dir: root, entry });
+                    }
+                }
+            }
+            catch { }
+        }
+        if (entries.length === 0)
+            return [];
+        const pending = [];
+        for (const { dir: root, entry } of entries) {
+            if (entry.startsWith('.'))
+                continue;
+            const appDir = join(root, entry);
+            // Accept app.json (canonical) or hive.json (legacy)
+            const appManifest = join(appDir, 'app.json');
+            const hiveManifest = join(appDir, 'hive.json');
+            const manifestPath = existsSync(appManifest)
+                ? appManifest
+                : existsSync(hiveManifest)
+                    ? hiveManifest
+                    : null;
+            if (!manifestPath)
+                continue;
+            let manifest;
+            try {
+                manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            }
+            catch (err) {
+                this.emit('error', new Error(`Skipping app at ${appDir} — bad manifest: ${err.message}`));
+                continue;
+            }
+            // Auth gate. Apps that declare `requiresAuth: true` are
+            // skipped entirely when the daemon is signed out — building
+            // classes don't load, IPC routes don't register, and the
+            // tray-coupled BrowserWindow never spawns. The whole hive
+            // disappears from the running process until the user signs
+            // back in (which restarts the daemon and re-runs this load).
+            if (manifest.requiresAuth === true) {
+                const isAuthed = this.config.isAuthenticated?.() ?? true;
+                if (!isAuthed) {
+                    this.emit('info', `Skipping app "${manifest.name}" — requiresAuth:true and daemon is signed out.`);
+                    continue;
+                }
+            }
+            let frontendAbs;
+            if (manifest.frontend?.dir) {
+                const candidate = join(appDir, manifest.frontend.dir);
+                if (existsSync(candidate))
+                    frontendAbs = candidate;
+            }
+            const recipes = {};
+            if (manifest.recipes && typeof manifest.recipes === 'object') {
+                for (const [rid, val] of Object.entries(manifest.recipes)) {
+                    if (typeof val === 'string') {
+                        const rpath = join(appDir, val);
+                        if (existsSync(rpath)) {
+                            try {
+                                recipes[rid] = JSON.parse(readFileSync(rpath, 'utf8'));
+                            }
+                            catch (err) {
+                                this.emit('error', new Error(`${manifest.name}: recipe "${rid}" parse failed: ${err.message}`));
+                            }
+                        }
+                    }
+                    else {
+                        recipes[rid] = val;
+                    }
+                }
+            }
+            const provides = manifest.buildings && typeof manifest.buildings === 'object'
+                ? Object.keys(manifest.buildings)
+                : [];
+            pending.push({
+                appDir,
+                manifest,
+                frontendAbs,
+                recipes,
+                provides,
+                depends: manifest.depends && typeof manifest.depends === 'object' ? manifest.depends : {},
+            });
+        }
+        // ── Pass 2: topo-sort + load ─────────────────────────────────────
+        // Deps can reference a BUILDING name (the common case — `ableton`)
+        // or an APP name. We resolve against the set of provides *and* app
+        // names so both work. Recipes-only apps that have no provides but
+        // depend on building X still resolve as long as X is available.
+        const alreadyHaveBuilding = (name) => name in this._buildings;
+        const providedByPending = {};
+        for (const p of pending) {
+            for (const b of p.provides)
+                providedByPending[b] = p;
+            providedByPending[p.manifest.name] = p; // allow depends-by-app-name
+        }
+        // Iterative load: repeatedly pick a pending app whose deps are all
+        // currently satisfied. Halts when the set stops shrinking.
+        const ordered = [];
+        const remaining = [...pending];
+        const depSatisfied = (dep) => alreadyHaveBuilding(dep) ||
+            ordered.some((o) => o.provides.includes(dep) || o.manifest.name === dep);
+        let progressed = true;
+        while (remaining.length > 0 && progressed) {
+            progressed = false;
+            for (let i = 0; i < remaining.length; i++) {
+                const p = remaining[i];
+                const deps = Object.keys(p.depends);
+                if (deps.every(depSatisfied)) {
+                    ordered.push(p);
+                    remaining.splice(i, 1);
+                    progressed = true;
+                    break;
+                }
+            }
+        }
+        // Anything still in `remaining` is stuck on an unmet dep.
+        for (const p of remaining) {
+            const unmet = Object.keys(p.depends).filter((d) => !depSatisfied(d));
+            this.emit('error', new Error(`${p.manifest.name}@${p.manifest.version}: unmet dependencies [${unmet.join(', ')}] — app skipped`));
+        }
+        // ── Pass 3: actually import + register ──────────────────────────
+        const out = [];
+        for (const p of ordered) {
+            const { manifest, appDir, frontendAbs, recipes } = p;
+            const registeredBuildings = [];
+            const cloudBuildings = [];
+            const browserBuildings = [];
+            if (manifest.buildings && typeof manifest.buildings === 'object') {
+                for (const [buildingName, bRaw] of Object.entries(manifest.buildings)) {
+                    const b = bRaw;
+                    // `runtime` is canonical; `hosted` is the deprecated alias kept
+                    // for backward compat with shipped hives. When both are set,
+                    // `runtime` wins (matches validator behavior).
+                    const runtime = b.runtime ?? b.hosted ?? 'local';
+                    // ── Cloud runtime ────────────────────────────────────────
+                    // Not instantiated locally — the daemon routes app-rpc
+                    // messages to the declared cloudUrl via the relay. The cloud
+                    // half (worker auto-registering hive cloud buildings as DO
+                    // siblings) is Sprint A4.
+                    if (runtime === 'cloud') {
+                        if (typeof b.cloudUrl !== 'string') {
+                            this.emit('error', new Error(`${manifest.name}: cloud building "${buildingName}" missing cloudUrl`));
+                            continue;
+                        }
+                        cloudBuildings.push({ name: buildingName, cloudUrl: b.cloudUrl });
+                        this.emit('info', `${manifest.name}: registered cloud building "${buildingName}" → ${b.cloudUrl}`);
+                        continue;
+                    }
+                    // ── Browser runtime ──────────────────────────────────────
+                    // Daemon doesn't instantiate — the file is served as a static
+                    // JS module under the dashboard's /apps/<name>/buildings/<key>.js
+                    // path. Frontend `hive.call()` fetches + dispatches when no
+                    // local equivalent is installed (per `fallbackFor` declaration).
+                    // Sprint A3 wires the browser-side runtime.
+                    if (runtime === 'browser') {
+                        if (typeof b.entry !== 'string') {
+                            this.emit('error', new Error(`${manifest.name}: browser building "${buildingName}" missing entry`));
+                            continue;
+                        }
+                        const entryAbs = join(appDir, b.entry);
+                        if (!existsSync(entryAbs)) {
+                            this.emit('error', new Error(`${manifest.name}: browser building "${buildingName}" entry not found: ${b.entry}`));
+                            continue;
+                        }
+                        const url = `http://127.0.0.1:9800/apps/${manifest.name}/buildings/${buildingName}.js`;
+                        browserBuildings.push({
+                            name: buildingName,
+                            entry: b.entry,
+                            url,
+                            fallbackFor: typeof b.fallbackFor === 'string' ? b.fallbackFor : undefined,
+                            handles: Array.isArray(b.handles) ? b.handles : undefined,
+                        });
+                        this.emit('info', `${manifest.name}: registered browser building "${buildingName}" → ${url}${b.fallbackFor ? ` (fallback for "${b.fallbackFor}")` : ''}`);
+                        continue;
+                    }
+                    // ── Local runtime (default) ──────────────────────────────
+                    // Conflict detection: if the same name is already registered
+                    // (e.g. from a linked dev project), skip this app's copy and
+                    // warn. First-registered wins.
+                    if (buildingName in this._buildings) {
+                        this.emit('info', `${manifest.name}@${manifest.version}: building "${buildingName}" skipped — already registered (first-registered wins)`);
+                        continue;
+                    }
+                    if (typeof b.entry !== 'string') {
+                        this.emit('error', new Error(`${manifest.name}: local building "${buildingName}" missing entry`));
+                        continue;
+                    }
+                    const entryPath = join(appDir, b.entry);
+                    if (!existsSync(entryPath)) {
+                        this.emit('error', new Error(`${manifest.name}: building "${buildingName}" entry not found: ${b.entry}`));
+                        continue;
+                    }
+                    try {
+                        const mod = await import(pathToFileURL(entryPath).href);
+                        const className = b.className;
+                        const BuildingClass = className
+                            ? mod[className]
+                            : (mod.default ?? Object.values(mod)[0]);
+                        if (typeof BuildingClass !== 'function') {
+                            this.emit('error', new Error(`${manifest.name}: building "${buildingName}" has no loadable class export`));
+                            continue;
+                        }
+                        this._buildings[buildingName] = BuildingClass;
+                        registeredBuildings.push(buildingName);
+                        this.emit('building-registered', buildingName);
+                    }
+                    catch (err) {
+                        this.emit('error', new Error(`${manifest.name}: failed to load building "${buildingName}": ${err.message}`));
+                    }
+                }
+            }
+            // Compute the frontend URL. Local frontends get the dashboard path;
+            // cloud frontends get their manifest cloudUrl. Hives with no frontend
+            // stay undefined — they're purely action surfaces, no UI.
+            let frontendUrl;
+            let frontendHosted;
+            if (manifest.frontend) {
+                const declared = manifest.frontend.hosted ??
+                    (manifest.frontend.dir ? 'local' : manifest.frontend.cloudUrl ? 'cloud' : 'local');
+                frontendHosted = declared;
+                if (declared === 'local' && frontendAbs) {
+                    frontendUrl = `http://127.0.0.1:9800/apps/${manifest.name}/`;
+                }
+                else if (declared === 'cloud' && typeof manifest.frontend.cloudUrl === 'string') {
+                    frontendUrl = manifest.frontend.cloudUrl;
+                }
+            }
+            const installed = {
+                name: manifest.name,
+                version: manifest.version,
+                appDir,
+                manifest,
+                frontendDir: frontendAbs,
+                frontendUrl,
+                frontendHosted,
+                buildings: registeredBuildings,
+                cloudBuildings,
+                browserBuildings,
+                recipes,
+                depends: p.depends,
+            };
+            out.push(installed);
+            this._installedApps.set(manifest.name, installed);
+            this.emit('info', `Loaded app ${manifest.name}@${manifest.version}${frontendUrl ? ' (' + frontendHosted + ' frontend)' : ''}${Object.keys(p.depends).length > 0 ? ' (deps: ' + Object.keys(p.depends).join(', ') + ')' : ''}`);
+        }
+        return out;
+    }
+    /** Return metadata for an installed app (or all). */
+    getInstalledApp(name) {
+        return this._installedApps.get(name);
+    }
+    listInstalledApps() {
+        return Array.from(this._installedApps.values());
+    }
+    /**
+     * Start the local app server.
+     * Dynamically imports @clearly-sh/beehaven-core to avoid hard dependency at module load time.
+     */
+    async start(port) {
+        if (this._running)
+            return;
+        if (Object.keys(this._buildings).length === 0) {
+            this.emit('info', 'No buildings registered — local app server not started.');
+            return;
+        }
+        try {
+            // Dynamic import — @clearly-sh/beehaven-core is a peer dependency
+            // @ts-ignore — optional peer dependency, resolved at runtime
+            const { LocalHive } = await import('@clearly-sh/beehaven-core/server/local');
+            mkdirSync(this._dataDir, { recursive: true });
+            this.localServer = new LocalHive({
+                buildings: this._buildings,
+                dataDir: this._dataDir,
+                env: this.config.env ?? {},
+                auth: this.config.auth,
+            });
+            // Try to set up better-sqlite3 database factory.
+            // If it's not bundled, fall through — LocalHive has its own in-memory
+            // fallback, and some buildings (e.g. Ableton) only need SQLite for
+            // non-critical history/snapshots. Returning early here used to skip
+            // the actual `listen()` call, silently breaking every local app.
+            try {
+                // @ts-ignore — optional dependency
+                const Database = (await import('better-sqlite3')).default;
+                this.localServer.setDatabaseFactory((path) => new Database(path));
+                this.emit('info', 'better-sqlite3 loaded — building state will persist to disk.');
+            }
+            catch (err) {
+                // better-sqlite3 not available — set up a no-op database factory.
+                // Buildings that need SQLite will get null and must handle it.
+                // Buildings like Avatar that don't use SQLite will work fine.
+                // Surface the actual reason so packaging issues (missing native
+                // binding, ABI mismatch, missing peer dep, wrong arch) are
+                // diagnosable instead of opaquely "not bundled".
+                const e = err;
+                this.localServer.setDatabaseFactory(() => null);
+                this.emit('info', `better-sqlite3 not bundled — buildings run without persistent SQLite. (${e?.code || 'no-code'}: ${e?.message?.slice(0, 200) || 'no-message'})`);
+            }
+            // Pre-create the per-building SQLite data directories with 0o755 so
+            // they have the execute bit. LocalHive.createDatabase uses plain
+            // mkdirSync with no explicit mode, which picks up whatever umask is
+            // currently active — and the ipc server sets a restrictive umask
+            // when binding the Unix socket. If a building is first touched
+            // during that window the dir gets 0o600 and SQLite can't enter it
+            // (errors out as "unable to open database file"). Doing the mkdir
+            // here, ourselves, with a known-good mode, eliminates that race.
+            try {
+                mkdirSync(this._dataDir, { recursive: true, mode: 0o755 });
+                chmodSync(this._dataDir, 0o755);
+                for (const type of Object.keys(this._buildings)) {
+                    const dir = join(this._dataDir, type);
+                    mkdirSync(dir, { recursive: true, mode: 0o755 });
+                    // chmodSync bypasses umask, so even if something else on the
+                    // daemon is holding a restrictive umask, the building data
+                    // dir ends up with the execute bit SQLite needs.
+                    chmodSync(dir, 0o755);
+                }
+            }
+            catch (err) {
+                this.emit('error', new Error(`Failed to create building data dirs: ${err?.message ?? err}`));
+            }
+            const actualPort = port ?? this.config.port ?? 9876;
+            const host = this.config.host ?? '127.0.0.1';
+            await this.localServer.listen(actualPort, { host });
+            this._running = true;
+            this._port = actualPort;
+            this.emit('started', { port: actualPort, host, buildings: Object.keys(this._buildings) });
+        }
+        catch (err) {
+            this.emit('error', new Error(`Failed to start local app: ${err.message}`));
+        }
+    }
+    /** Stop the local app server. */
+    async stop() {
+        if (!this._running || !this.localServer)
+            return;
+        try {
+            await this.localServer.close();
+        }
+        catch {
+            /* best effort */
+        }
+        this._running = false;
+        this._port = null;
+        this.localServer = null;
+        this.emit('stopped');
+    }
+    /**
+     * Route a fetch request to a local building.
+     * Used by the relay to forward cloud requests to local apps.
+     */
+    async routeFetch(type, id, request) {
+        if (!this.localServer) {
+            return new Response('Local app not running', { status: 503 });
+        }
+        try {
+            return await this.localServer.fetch(type, id, request);
+        }
+        catch (err) {
+            return new Response(err.message, { status: 500 });
+        }
+    }
+    /**
+     * Get a local building instance.
+     * Used for direct programmatic access from daemon code.
+     *
+     * Errors from LocalHive.building() (unknown type, createDatabase
+     * failure, constructor throw) are surfaced via the error event stream
+     * so they don't silently become "building not found" — that made
+     * debugging instantiation failures much harder than it had to be.
+     */
+    getBuilding(type, id) {
+        if (!this.localServer)
+            return null;
+        try {
+            return this.localServer.building(type, id);
+        }
+        catch (err) {
+            this.emit('error', new Error(`getBuilding("${type}","${id}") failed: ${err?.message ?? err}`));
+            return null;
+        }
+    }
+    /** Check if a building type is registered. */
+    hasBuilding(type) {
+        return type in this._buildings;
+    }
+    /** Get the data directory. */
+    get dataDir() {
+        return this._dataDir;
+    }
+    /** Check if the app server is running. */
+    get running() {
+        return this._running;
+    }
+    /** Get the port. */
+    get port() {
+        return this._port;
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// Helpers — template substitution for app URLs
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Substitute {foo} / {foo.bar} placeholders in a URL (or any string).
+ * Unknown placeholders are left untouched so apps don't silently break
+ * when the daemon runs before a user has signed in, before a store is
+ * picked, etc. The frontend typically handles the "not-yet-resolved"
+ * case itself (redirect to login, show store picker, etc).
+ */
+function resolveTemplateVars(input, vars) {
+    return input.replace(/\{([a-zA-Z_][\w.]*)\}/g, (match, key) => {
+        if (key in vars && vars[key])
+            return vars[key];
+        return match;
+    });
+}
+/**
+ * Read the daemon config without throwing. Used by templateVars() to pull
+ * `user.uid`, `user.email`, `activeStoreId`, etc. for template resolution.
+ * Reads on every call — the file is tiny and the user expects sign-in to
+ * reflect without a daemon restart.
+ */
+function readDaemonConfigSafe() {
+    try {
+        const configPath = join(homedir(), '.beehaven', 'config.json');
+        if (!existsSync(configPath))
+            return {};
+        return JSON.parse(readFileSync(configPath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}