@clearlysh/beehaven 0.8.16

package/dist/commands/app.js

@@ -0,0 +1,1123 @@
+/**
+ * beehaven app — pack / install / list / uninstall apps.
+ *
+ * Apps are zip archives with an app.json manifest at the root. Once
+ * installed they live under ~/.beehaven/apps/<name>@<version>/ and are
+ * picked up by the daemon on its next launch (or on a hot-reload, when
+ * that lands).
+ *
+ * Usage:
+ *   beehaven app pack <dir> [-o out.hive]
+ *   beehaven app install <path-or-url>
+ *   beehaven app list
+ *   beehaven app uninstall <name>[@<version>]
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'fs';
+import { join, relative, resolve } from 'path';
+import { homedir } from 'os';
+import { execSync, execFileSync, spawnSync } from 'child_process';
+import { parseAppManifest, validateAppManifest } from '../app-manifest.js';
+import { verifyAppSignature, loadSignatureEnvelope, TRUSTED_SIGNERS } from '../app-signing.js';
+import { isPubliclyVisibleApp, isPubliclyVisibleAppAction } from '../public-surface.js';
+const APPS_DIR = join(homedir(), '.beehaven', 'apps');
+// ──────────────────────────────────────────────────────────────────────
+// Shared helpers
+// ──────────────────────────────────────────────────────────────────────
+function ensureAppsDir() {
+    mkdirSync(APPS_DIR, { recursive: true, mode: 0o755 });
+}
+/** Enumerate files under dir, relative paths, skipping common cruft. */
+function walkFiles(root) {
+    const results = [];
+    const skip = new Set(['node_modules', '.git', '.DS_Store', 'dist.map', '.turbo', '.cache']);
+    const walk = (p) => {
+        for (const entry of readdirSync(p)) {
+            if (skip.has(entry))
+                continue;
+            const full = join(p, entry);
+            const stat = statSync(full);
+            if (stat.isDirectory())
+                walk(full);
+            else if (stat.isFile())
+                results.push(relative(root, full));
+        }
+    };
+    walk(root);
+    return results;
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app pack
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppPack(args, opts = {}) {
+    const dir = resolve(args[0] ?? process.cwd());
+    const manifestPath = join(dir, 'app.json');
+    if (!existsSync(manifestPath)) {
+        console.error(`  ✗ No app.json at ${manifestPath}`);
+        process.exit(1);
+    }
+    // Validate before packing — catching errors here is always cheaper than
+    // catching them on install.
+    const raw = readFileSync(manifestPath, 'utf8');
+    const { manifest, error } = parseAppManifest(raw);
+    if (error || !manifest) {
+        console.error(`  ✗ ${error ?? 'invalid manifest'}`);
+        process.exit(1);
+    }
+    // Default output: ./<name>-<version>.hive
+    const outPath = resolve(opts.output ?? join(process.cwd(), `${manifest.name}-${manifest.version}.hive`));
+    // Build the archive. zip is ubiquitous on macOS/Linux; on Windows we'd
+    // reach for an npm zip lib, but the CLI is macOS-first today.
+    const files = walkFiles(dir);
+    if (!files.includes('app.json')) {
+        console.error('  ✗ app.json must be at the archive root');
+        process.exit(1);
+    }
+    // Ensure entries referenced by the manifest actually exist on disk —
+    // catches typos in building.entry and frontend.dir before they become
+    // runtime errors at install time. Cloud-hosted buildings/frontends
+    // are exempt because they don't ship on-disk assets.
+    for (const [key, bRaw] of Object.entries(manifest.buildings ?? {})) {
+        const b = bRaw;
+        const hosted = b.hosted ?? 'local';
+        if (hosted !== 'local')
+            continue; // cloud buildings → nothing to check
+        if (typeof b.entry !== 'string') {
+            console.error(`  ✗ buildings["${key}"].entry must be a string for hosted="local"`);
+            process.exit(1);
+        }
+        const p = join(dir, b.entry);
+        if (!existsSync(p)) {
+            console.error(`  ✗ buildings["${key}"].entry not found: ${b.entry}`);
+            process.exit(1);
+        }
+    }
+    if (manifest.frontend) {
+        const fhosted = manifest.frontend.hosted ??
+            (manifest.frontend.dir ? 'local' : manifest.frontend.cloudUrl ? 'cloud' : 'local');
+        if (fhosted === 'local') {
+            if (typeof manifest.frontend.dir !== 'string') {
+                console.error('  ✗ frontend.dir must be a string for hosted="local"');
+                process.exit(1);
+            }
+            const p = join(dir, manifest.frontend.dir);
+            if (!existsSync(p) || !statSync(p).isDirectory()) {
+                console.error(`  ✗ frontend.dir not found: ${manifest.frontend.dir}`);
+                process.exit(1);
+            }
+        }
+    }
+    // Remove any previous archive at the same path
+    try {
+        if (existsSync(outPath))
+            rmSync(outPath);
+    }
+    catch { }
+    // Shell to `zip` — reliable on macOS, no native-module hell. The `-@`
+    // flag reads file names from stdin, so we pipe the list in directly
+    // via spawnSync's `input` option. No shell, no argv-length limits,
+    // no injection risk from file names containing metacharacters.
+    try {
+        const result = spawnSync('zip', ['-q', outPath, '-@'], {
+            cwd: dir,
+            input: files.join('\n'),
+            stdio: ['pipe', 'inherit', 'inherit'],
+        });
+        if (result.status !== 0) {
+            throw new Error(`zip exited with status ${result.status}`);
+        }
+    }
+    catch (err) {
+        console.error(`  ✗ zip failed: ${err?.message ?? err}`);
+        process.exit(1);
+    }
+    // Optional signing: --key <path-to-ed25519-private-key> --signer <id>
+    // Writes a detached <outPath>.sig file that `beehaven app install`
+    // verifies against pinned trusted public keys.
+    if (opts.signKey) {
+        try {
+            const signerId = opts.signerId ?? 'clearly-release';
+            const { signAppArchive } = await import('../app-signer.js');
+            const sigEnvelope = await signAppArchive(outPath, opts.signKey, signerId);
+            writeFileSync(outPath + '.sig', JSON.stringify(sigEnvelope, null, 2));
+            console.log(`  ✓ Signed (${signerId})`);
+        }
+        catch (err) {
+            console.error(`  ✗ signing failed: ${err?.message ?? err}`);
+            process.exit(1);
+        }
+    }
+    const stat = statSync(outPath);
+    console.log('');
+    console.log(`  ✓ Packed ${manifest.name}@${manifest.version}`);
+    console.log(`    ${files.length} files, ${(stat.size / 1024).toFixed(1)} KB`);
+    console.log(`    → ${outPath}`);
+    if (opts.signKey)
+        console.log(`    → ${outPath}.sig  (signature)`);
+    console.log('');
+    console.log(`  Install locally:   beehaven app install ${outPath}`);
+    console.log('');
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app install
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppInstall(args, opts = {}) {
+    const src = args[0];
+    if (!src) {
+        console.error('  usage: beehaven app install <name|path|url> [--allow-unsigned] [--with-skills|--no-skills]');
+        console.error('');
+        console.error('  By name (from catalog):');
+        console.error('    beehaven app install mwah');
+        console.error('    beehaven app install ableton');
+        console.error('    beehaven app install memory-cloud');
+        console.error('');
+        console.error('  By path or URL (archive must be signed unless --allow-unsigned):');
+        console.error('    beehaven app install ./my-app.hive');
+        console.error('    beehaven app install https://example.com/my-app.hive');
+        process.exit(1);
+    }
+    // If the source looks like a plain name (no path separators, no URL scheme,
+    // no .hive extension), route through the daemon which resolves from the
+    // catalog and syncs to the user's Clearly account.
+    const isName = !src.includes('/') && !src.includes('\\') && !src.startsWith('http') && !src.endsWith('.hive');
+    if (isName) {
+        const { isDaemonRunning } = await import('../daemon-client.js');
+        if (await isDaemonRunning()) {
+            const { rpcOnce } = await import('../ipc-client.js');
+            try {
+                const result = await rpcOnce('daemon:app-install', { name: src }, 300_000);
+                console.log(`  ✓ Installed ${result.installed}`);
+                if (result.buildings?.length)
+                    console.log(`    Buildings: ${result.buildings.join(', ')}`);
+                // Skill install runs CLI-side after the daemon writes the app dir.
+                // The daemon returned just {installed, buildings} — re-read the
+                // manifest from disk to find agentDocs.claudeCode.
+                await maybeInstallPairedSkill(src, opts);
+                console.log('');
+                console.log('  Restart the daemon to pick it up: quit and relaunch the Clearly Dev Mac app.');
+                console.log('');
+            }
+            catch (err) {
+                console.error(`  ✗ ${err.message}`);
+                process.exit(1);
+            }
+            return;
+        }
+        else {
+            console.error('  ✗ Daemon not running. Start it:  beehaven start --headless\n    (or open the Hive Mac app, which runs one for you.)');
+            console.error('    (Install by name requires the daemon for catalog + account sync)');
+            process.exit(1);
+        }
+    }
+    ensureAppsDir();
+    // Download if it's a URL. Otherwise resolve to an absolute path.
+    //
+    // Security: use execFileSync so curl's arguments are passed as argv,
+    // not through /bin/sh. A malicious src that contained shell
+    // metacharacters would otherwise inject commands — e.g.
+    // `"; rm -rf ~ #` baked into a README download link. Also pin curl to
+    // its known path so a PATH-poisoning `curl` shim can't run.
+    let archivePath;
+    let sigPath = null;
+    let cleanupArchive = false;
+    if (/^https?:\/\//.test(src)) {
+        archivePath = join('/tmp', `bh-app-dl-${process.pid}.hive`);
+        cleanupArchive = true;
+        try {
+            execFileSync('curl', ['-fsSL', src, '-o', archivePath], { stdio: 'inherit' });
+        }
+        catch {
+            console.error(`  ✗ failed to download ${src}`);
+            process.exit(1);
+        }
+        // Best-effort fetch of <src>.sig alongside the archive. If the server
+        // doesn't have it we record sigPath=null and let the unsigned-install
+        // policy below decide whether to continue.
+        const sigUrl = src + '.sig';
+        const sigDownload = join('/tmp', `bh-app-dl-${process.pid}.app.sig`);
+        const sigResult = spawnSync('curl', ['-fsSL', sigUrl, '-o', sigDownload], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+        });
+        if (sigResult.status === 0) {
+            sigPath = sigDownload;
+        }
+        else {
+            // Clean up partial file if curl wrote anything
+            try {
+                if (existsSync(sigDownload))
+                    rmSync(sigDownload);
+            }
+            catch { }
+        }
+    }
+    else {
+        archivePath = resolve(src);
+        if (!existsSync(archivePath)) {
+            console.error(`  ✗ not found: ${archivePath}`);
+            process.exit(1);
+        }
+        // Local install: check for a sibling .sig file
+        const localSig = archivePath + '.sig';
+        if (existsSync(localSig))
+            sigPath = localSig;
+    }
+    // ── Signature check ───────────────────────────────────────────────
+    //
+    // Default-deny: no signature → refuse unless user passes --allow-unsigned.
+    // The `.sig` bundles a SHA-256 of the archive plus an Ed25519 signature
+    // over that digest by a pinned trusted key. A MITM or mirror compromise
+    // cannot swap the archive while keeping a valid signature.
+    if (!sigPath) {
+        // ONLY an explicit --allow-unsigned continues. This used to also
+        // auto-continue whenever `TRUSTED_SIGNERS.length === 0` — and since
+        // that list ships EMPTY (app-signing.ts pins no production key yet),
+        // the condition was true in every published build. So the default
+        // path for `beehaven install <url>` was: download unverified bytes,
+        // print a warning, install them as a building that runs inside the
+        // daemon — which holds the user's Firebase token and keychain access.
+        // That is precisely the threat app-signing.ts was written to stop,
+        // and its own header claims the empty list makes us "fail closed".
+        // It did the opposite. An unpinned build must refuse, not shrug.
+        if (opts.allowUnsigned) {
+            console.warn(`  ⚠ installing unsigned app (user passed --allow-unsigned)`);
+            console.warn(`    This is safe for local dev but insecure for production downloads.`);
+        }
+        else {
+            console.error(`  ✗ archive has no signature (${archivePath}.sig not found)`);
+            if (TRUSTED_SIGNERS.length === 0) {
+                // Name the real reason. Otherwise a maintainer who DOES ship a
+                // .sig hits "verification failed" and hunts the wrong problem.
+                console.error(`    This CLI build pins no trusted signing keys, so no`);
+                console.error(`    signature could be verified even if one were present.`);
+                console.error(`    Fix properly: add the release key to TRUSTED_SIGNERS`);
+                console.error(`    in app-signing.ts and sign releases with 'beehaven app pack --key'.`);
+            }
+            console.error(`    To install anyway (DEV USE ONLY — runs unverified code`);
+            console.error(`    inside your daemon): re-run with --allow-unsigned.`);
+            if (cleanupArchive)
+                try {
+                    rmSync(archivePath);
+                }
+                catch { }
+            process.exit(1);
+        }
+    }
+    else {
+        const envelope = loadSignatureEnvelope(sigPath);
+        if (!envelope) {
+            console.error(`  ✗ signature file is malformed: ${sigPath}`);
+            if (cleanupArchive) {
+                try {
+                    rmSync(archivePath);
+                }
+                catch { }
+                try {
+                    rmSync(sigPath);
+                }
+                catch { }
+            }
+            process.exit(1);
+        }
+        const verification = verifyAppSignature(archivePath, envelope);
+        if (!verification.ok) {
+            console.error(`  ✗ signature verification failed: ${verification.reason}`);
+            console.error(`    archive: ${archivePath}`);
+            console.error(`    signer:  ${envelope.signer}`);
+            if (cleanupArchive) {
+                try {
+                    rmSync(archivePath);
+                }
+                catch { }
+                try {
+                    rmSync(sigPath);
+                }
+                catch { }
+            }
+            process.exit(1);
+        }
+        console.log(`  ✓ signature verified (signer: ${verification.signerId})`);
+        // Clean up the sig file once verified; nothing below needs it.
+        if (cleanupArchive)
+            try {
+                rmSync(sigPath);
+            }
+            catch { }
+    }
+    // Peek at the manifest inside the archive before committing to install.
+    //
+    // Security: execFileSync avoids shell interpolation of archivePath. The
+    // path is either our /tmp/bh-app-dl-<pid>.app (safe) or user-supplied
+    // via resolve(src) — a path containing `; rm -rf ~` would previously
+    // have executed. Now each arg is its own argv slot.
+    let peekManifest;
+    try {
+        const out = execFileSync('unzip', ['-p', archivePath, 'app.json'], { encoding: 'utf8' });
+        const parsed = parseAppManifest(out);
+        if (!parsed.manifest)
+            throw new Error(parsed.error ?? 'invalid manifest');
+        peekManifest = parsed.manifest;
+    }
+    catch (err) {
+        console.error(`  ✗ archive does not contain a valid app.json: ${err?.message ?? err}`);
+        if (cleanupArchive)
+            try {
+                rmSync(archivePath);
+            }
+            catch { }
+        process.exit(1);
+    }
+    // Target install dir: ~/.beehaven/apps/<name>@<version>/
+    //
+    // The manifest name/version came from the signed archive (or unsigned
+    // with explicit opt-in), so the install dir is authoritative. Still,
+    // we sanitize against traversal in case a malicious unsigned package
+    // declared name="../../etc" — such a path would have already failed
+    // manifest validation, but belt-and-suspenders.
+    if (!/^[a-zA-Z0-9._-]+$/.test(peekManifest.name) ||
+        !/^[a-zA-Z0-9._+-]+$/.test(peekManifest.version)) {
+        console.error(`  ✗ manifest name/version contain disallowed characters`);
+        if (cleanupArchive)
+            try {
+                rmSync(archivePath);
+            }
+            catch { }
+        process.exit(1);
+    }
+    const installDir = join(APPS_DIR, `${peekManifest.name}@${peekManifest.version}`);
+    if (existsSync(installDir)) {
+        console.log(`  (reinstalling over existing ${peekManifest.name}@${peekManifest.version})`);
+        try {
+            rmSync(installDir, { recursive: true, force: true });
+        }
+        catch { }
+    }
+    mkdirSync(installDir, { recursive: true, mode: 0o755 });
+    // Extract — execFileSync, same injection-free path handling.
+    try {
+        execFileSync('unzip', ['-q', archivePath, '-d', installDir], { stdio: 'inherit' });
+    }
+    catch (err) {
+        console.error(`  ✗ unzip failed: ${err?.message ?? err}`);
+        try {
+            rmSync(installDir, { recursive: true, force: true });
+        }
+        catch { }
+        if (cleanupArchive)
+            try {
+                rmSync(archivePath);
+            }
+            catch { }
+        process.exit(1);
+    }
+    if (cleanupArchive)
+        try {
+            rmSync(archivePath);
+        }
+        catch { }
+    // Final readback — paranoia. The extracted manifest should match what we peeked.
+    const installedManifest = readFileSync(join(installDir, 'app.json'), 'utf8');
+    const finalValidation = validateAppManifest(JSON.parse(installedManifest));
+    if (!finalValidation.valid) {
+        console.error(`  ✗ extracted app failed validation: ${finalValidation.errors.join('; ')}`);
+        try {
+            rmSync(installDir, { recursive: true, force: true });
+        }
+        catch { }
+        process.exit(1);
+    }
+    for (const w of finalValidation.warnings)
+        console.warn(`  ⚠ ${w}`);
+    console.log('');
+    console.log(`  ✓ Installed ${peekManifest.name}@${peekManifest.version}`);
+    console.log(`    → ${installDir}`);
+    if (peekManifest.frontend) {
+        console.log(`    Frontend: http://127.0.0.1:9800/apps/${peekManifest.name}/`);
+    }
+    if (peekManifest.buildings) {
+        console.log(`    Buildings: ${Object.keys(peekManifest.buildings).join(', ')}`);
+    }
+    if (peekManifest.recipes) {
+        console.log(`    Recipes:   ${Object.keys(peekManifest.recipes).join(', ')}`);
+    }
+    // Run setup script if the manifest declares one
+    const setupResult = await runAppSetup(installDir, peekManifest);
+    if (setupResult === 'skipped') {
+        // No setup script — nothing to report
+    }
+    else if (setupResult === 'ok') {
+        console.log(`  ✓ Setup complete`);
+    }
+    // Errors are printed inside runAppSetup
+    // Offer to install the paired Claude Code skill if the manifest ships one.
+    // Wrapped in try/catch — skill install is opportunistic; a bad SKILL.md
+    // or unreadable file shouldn't fail the whole hive install, which has
+    // already succeeded at this point.
+    try {
+        const { installPairedSkill } = await import('./skills.js');
+        await installPairedSkill(installDir, peekManifest, {
+            withSkills: opts.withSkills,
+            noSkills: opts.noSkills,
+        });
+    }
+    catch (err) {
+        console.warn(`  ⚠ Skill install skipped: ${err?.message ?? err}`);
+    }
+    console.log('');
+    console.log('  Restart the daemon to pick it up: quit and relaunch the Clearly Dev Mac app.');
+    console.log('  (or quit + relaunch the Clearly Mac app)');
+    console.log('');
+}
+/**
+ * Catalog-install helper: the daemon writes the app to ~/.beehaven/apps/
+ * but the skill prompt + install lives CLI-side. Find the freshly-installed
+ * app dir (latest version of `name`), read its manifest, and call
+ * installPairedSkill if there's one.
+ */
+async function maybeInstallPairedSkill(name, opts) {
+    try {
+        if (!existsSync(APPS_DIR))
+            return;
+        const entries = readdirSync(APPS_DIR).filter((e) => e.startsWith(`${name}@`));
+        if (entries.length === 0)
+            return;
+        // Pick the highest version dir for `name`. Cheap string sort is fine —
+        // names are validated to a-zA-Z0-9._- and versions are semver-shaped.
+        entries.sort();
+        const installDir = join(APPS_DIR, entries[entries.length - 1]);
+        const manifestPath = join(installDir, 'app.json');
+        if (!existsSync(manifestPath))
+            return;
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        if (!manifest?.agentDocs?.claudeCode)
+            return;
+        const { installPairedSkill } = await import('./skills.js');
+        await installPairedSkill(installDir, manifest, opts);
+    }
+    catch (err) {
+        // Skill install is opportunistic — never fail the whole install
+        // because we couldn't drop a SKILL.md.
+        console.warn(`  ⚠ Skill install skipped: ${err?.message ?? err}`);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// Setup script support
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * Run an app's setup script if the manifest declares one.
+ * The setup script runs with cwd = installDir and gets APP_DIR in env.
+ * Returns 'ok', 'skipped', or 'error'.
+ */
+async function runAppSetup(installDir, manifest) {
+    const setupPath = manifest.setup;
+    if (!setupPath)
+        return 'skipped';
+    const scriptPath = join(installDir, setupPath);
+    if (!existsSync(scriptPath)) {
+        console.warn(`  ⚠ Setup script not found: ${setupPath}`);
+        return 'error';
+    }
+    console.log(`  Running setup...`);
+    try {
+        // Make executable
+        try {
+            execSync(`chmod +x "${scriptPath}"`);
+        }
+        catch { }
+        execSync(`"${scriptPath}"`, {
+            cwd: installDir,
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                APP_DIR: installDir,
+                APP_NAME: manifest.name,
+                APP_VERSION: manifest.version,
+            },
+            timeout: 300_000, // 5 min max for model downloads
+        });
+        return 'ok';
+    }
+    catch (err) {
+        console.error(`  ✗ Setup failed: ${err?.message ?? err}`);
+        console.error(`    You can re-run: beehaven app setup ${manifest.name}`);
+        return 'error';
+    }
+}
+/**
+ * beehaven app setup <name> — re-run an installed app's setup script.
+ */
+export async function cmdAppSetup(appName) {
+    ensureAppsDir();
+    const entry = readdirSync(APPS_DIR).find((e) => e.startsWith(`${appName}@`));
+    if (!entry) {
+        console.error(`  ✗ App "${appName}" not installed.`);
+        process.exit(1);
+    }
+    const installDir = join(APPS_DIR, entry);
+    const manifestPath = join(installDir, 'app.json');
+    if (!existsSync(manifestPath)) {
+        console.error(`  ✗ No app.json in ${installDir}`);
+        process.exit(1);
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const result = await runAppSetup(installDir, manifest);
+    if (result === 'skipped') {
+        console.log(`  ${appName} has no setup script.`);
+    }
+    else if (result === 'ok') {
+        console.log(`  ✓ Setup complete for ${appName}`);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app list
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppList() {
+    // Try daemon first — returns installed + available from catalog + cloud
+    const { isDaemonRunning } = await import('../daemon-client.js');
+    if (await isDaemonRunning()) {
+        const { rpcOnce } = await import('../ipc-client.js');
+        try {
+            const { installed, available } = await rpcOnce('daemon:app-list', {}, 10_000);
+            console.log('');
+            console.log('  Installed');
+            console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+            if (installed.length === 0) {
+                console.log('  (none)');
+            }
+            for (const app of installed) {
+                console.log(`  ${app.name}@${app.version}  [${app.tier}]  buildings: ${app.buildings.join(', ') || '—'}`);
+                console.log(`    ${app.description}`);
+            }
+            if (available.length > 0) {
+                console.log('');
+                console.log('  Available');
+                console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+                for (const app of available) {
+                    console.log(`  ${app.name}@${app.version}  [${app.tier}]  ${app.kind}`);
+                    console.log(`    ${app.description}`);
+                }
+                console.log('');
+                console.log('  Install: beehaven app install <name>');
+            }
+            console.log('');
+            return;
+        }
+        catch {
+            /* fall through to local-only list */
+        }
+    }
+    // Fallback: local-only list
+    ensureAppsDir();
+    const entries = readdirSync(APPS_DIR).filter((e) => !e.startsWith('.'));
+    if (entries.length === 0) {
+        console.log('');
+        console.log('  No apps installed.');
+        console.log('  Install one: beehaven app install <name>');
+        console.log('');
+        return;
+    }
+    console.log('');
+    console.log('  Installed apps');
+    console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    for (const entry of entries) {
+        const manifestPath = join(APPS_DIR, entry, 'app.json');
+        if (!existsSync(manifestPath))
+            continue;
+        let m;
+        try {
+            m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!m)
+            continue;
+        if (!isPubliclyVisibleApp(m))
+            continue;
+        console.log(`  ${m.name}@${m.version}  [${m.license?.tier ?? 'free'}]  buildings: ${Object.keys(m.buildings ?? {}).join(', ') || '—'}`);
+        console.log(`    ${m.description ?? '(no description)'}`);
+    }
+    console.log('');
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app uninstall
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppUninstall(args) {
+    const nameWithVersion = args[0];
+    if (!nameWithVersion) {
+        console.error('  usage: beehaven app uninstall <name>');
+        process.exit(1);
+    }
+    // Strip @version if provided — daemon resolves by name
+    const name = nameWithVersion.split('@')[0];
+    // Route through daemon so it syncs to the Clearly account.
+    // Paired Claude Code skill removal only happens AFTER the uninstall
+    // succeeds — otherwise a failed uninstall (daemon error, app not
+    // found) would still wipe the user's SKILL.md.
+    const { isDaemonRunning } = await import('../daemon-client.js');
+    const { removePairedSkill } = await import('./skills.js');
+    if (await isDaemonRunning()) {
+        const { rpcOnce } = await import('../ipc-client.js');
+        try {
+            const result = await rpcOnce('daemon:app-uninstall', { name }, 30_000);
+            for (const r of result.removed) {
+                console.log(`  ✓ removed ${r}`);
+            }
+            // Uninstall succeeded — now safe to remove the paired skill.
+            // No-op when the hive didn't ship one.
+            removePairedSkill(name);
+            console.log('');
+            console.log('  Restart the daemon to drop the in-memory building instance.');
+            console.log('');
+        }
+        catch (err) {
+            console.error(`  ✗ ${err.message}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // Fallback: direct filesystem removal (no daemon = no cloud sync)
+    ensureAppsDir();
+    const entries = readdirSync(APPS_DIR);
+    const matches = [];
+    for (const e of entries) {
+        if (e.startsWith(`${name}@`))
+            matches.push(e);
+    }
+    if (matches.length === 0) {
+        console.error(`  ✗ not installed: ${name}`);
+        process.exit(1);
+    }
+    let anyRemoved = false;
+    for (const m of matches) {
+        try {
+            rmSync(join(APPS_DIR, m), { recursive: true, force: true });
+            console.log(`  ✓ removed ${m}`);
+            anyRemoved = true;
+        }
+        catch (err) {
+            console.error(`  ✗ failed to remove ${m}: ${err?.message ?? err}`);
+        }
+    }
+    // Same rule applies to the FS fallback — only remove the skill if at
+    // least one matching hive directory was actually deleted.
+    if (anyRemoved)
+        removePairedSkill(name);
+    console.log('');
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app actions [building] — query a building's available actions
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppActions(args, opts) {
+    const building = args[0] ?? opts.building;
+    const instanceId = opts.instance ?? 'live';
+    const category = opts.category;
+    const search = opts.search;
+    const json = !!opts.json;
+    const { appRpcOnce } = await import('../ipc-client.js');
+    // If no building specified, list all buildings and their action counts
+    if (!building) {
+        await cmdAppListBuildings(opts);
+        return;
+    }
+    try {
+        const result = await appRpcOnce('manifest', {}, { building, instanceId });
+        const visibleCategories = Object.fromEntries(Object.entries((result.categories ?? {}))
+            .map(([cat, actions]) => [
+            cat,
+            actions.filter((a) => isPubliclyVisibleAppAction(building, a.name)),
+        ])
+            .filter(([, actions]) => actions.length > 0));
+        const visibleTotal = Object.values(visibleCategories).reduce((sum, actions) => sum + actions.length, 0);
+        if (json) {
+            console.log(JSON.stringify({ ...result, categories: visibleCategories, actionCount: visibleTotal }, null, 2));
+            return;
+        }
+        const categories = visibleCategories;
+        const total = visibleTotal;
+        console.log('');
+        console.log(`  ${building} — ${total} actions`);
+        console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        for (const [cat, actions] of Object.entries(categories)) {
+            if (category && cat !== category)
+                continue;
+            const filtered = search
+                ? actions.filter((a) => a.name.includes(search) || a.description?.includes(search))
+                : actions;
+            if (filtered.length === 0)
+                continue;
+            console.log('');
+            console.log(`  ${cat}`);
+            for (const a of filtered) {
+                const paramStr = a.params
+                    ? Object.entries(a.params)
+                        .map(([k, v]) => `${k}: ${v}`)
+                        .join(', ')
+                    : '';
+                console.log(`    ${a.name.padEnd(28)} ${a.description ?? ''}`);
+                if (paramStr) {
+                    console.log(`      ${paramStr}`);
+                }
+            }
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`  ✗ ${err.message}`);
+        process.exit(1);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app buildings — list all registered buildings across apps
+// ──────────────────────────────────────────────────────────────────────
+async function cmdAppListBuildings(opts) {
+    const json = !!opts.json;
+    const { appRpcOnce } = await import('../ipc-client.js');
+    ensureAppsDir();
+    const entries = readdirSync(APPS_DIR).filter((e) => !e.startsWith('.'));
+    // Collect building → app mapping from installed manifests
+    const buildings = [];
+    for (const entry of entries) {
+        const manifestPath = join(APPS_DIR, entry, 'app.json');
+        if (!existsSync(manifestPath))
+            continue;
+        let m;
+        try {
+            m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!m?.buildings)
+            continue;
+        for (const [bName, bDef] of Object.entries(m.buildings)) {
+            const info = {
+                building: bName,
+                app: m.name,
+                version: m.version,
+                description: bDef.description ?? m.description ?? '',
+            };
+            // Try to get action count from the live building
+            try {
+                const manifest = await appRpcOnce('manifest', {}, { building: bName, timeout: 5_000 });
+                info.actionCount = manifest.actionCount ?? manifest.totalActions ?? 0;
+            }
+            catch {
+                /* building may not be running */
+            }
+            buildings.push(info);
+        }
+    }
+    if (json) {
+        console.log(JSON.stringify(buildings, null, 2));
+        return;
+    }
+    if (buildings.length === 0) {
+        console.log('');
+        console.log('  No buildings registered. Install an app: beehaven app install <path-or-url>');
+        console.log('');
+        return;
+    }
+    console.log('');
+    console.log('  Registered Buildings');
+    console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    for (const b of buildings) {
+        const actions = b.actionCount != null ? `${b.actionCount} actions` : 'offline';
+        console.log('');
+        console.log(`  ${b.building}  (${b.app}@${b.version})  [${actions}]`);
+        console.log(`    ${b.description}`);
+        console.log(`    → beehaven app actions ${b.building}`);
+    }
+    console.log('');
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app call <building> <action> [json] — call a building action
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppCall(args, opts) {
+    let building = args[0];
+    let action = args[1];
+    let rawInput = args[2];
+    let instanceId = opts.instance ?? 'live';
+    const timeout = opts.timeout ? parseInt(opts.timeout, 10) : 30_000;
+    // Support building/id syntax: `beehaven app call ableton/live getSession`
+    if (building?.includes('/')) {
+        const slashIdx = building.indexOf('/');
+        instanceId = building.slice(slashIdx + 1);
+        building = building.slice(0, slashIdx);
+    }
+    // Disambiguate the 3-arg case `beehaven app call <building> <instance> <action>`
+    // from the 3-arg case `beehaven app call <building> <action> <json>`. The
+    // signal is what args[2] looks like — JSON payloads start with `{`/`[`/`"`,
+    // bare action names don't. The earlier heuristic checked whether args[1]
+    // included `-` or `:`, which incorrectly rejected legit instance IDs like
+    // `clearly-demo` and made the 3-arg form unusable.
+    const looksLikeJson = (s) => /^\s*[\{\[\"]/.test(s);
+    if (building &&
+        action &&
+        args[2] !== undefined &&
+        args[3] === undefined &&
+        !looksLikeJson(args[2])) {
+        // 3-arg form: building instance action (no JSON input)
+        instanceId = args[1];
+        action = args[2];
+        rawInput = undefined;
+    }
+    else if (building && args[1] && args[2] && args[3]) {
+        // 4-arg form: building instance action json
+        instanceId = args[1];
+        action = args[2];
+        rawInput = args[3];
+    }
+    if (!building || !action) {
+        console.error('  Usage: beehaven app call <building>[/<id>] <action> [json-input]');
+        console.error('  Example: beehaven app call ableton getSession');
+        console.error('  Example: beehaven app call ableton/live createTrack \'{"type":"midi","name":"Strings"}\'');
+        process.exit(1);
+    }
+    if (!isPubliclyVisibleAppAction(building, action)) {
+        console.error(`  ✗ avatar action "${action}" is temporarily unavailable.`);
+        process.exit(1);
+    }
+    let input = {};
+    if (rawInput) {
+        try {
+            input = JSON.parse(rawInput);
+        }
+        catch {
+            console.error(`  ✗ Invalid JSON: ${rawInput}`);
+            process.exit(1);
+        }
+    }
+    const { appRpcOnce } = await import('../ipc-client.js');
+    const { resolveActiveAgent } = await import('../agent-state.js');
+    // When an agent identity is active (--agent or $BEEHAVEN_AGENT), attach
+    // its signed token so the daemon tags the call with a CallerContext and
+    // routes avatar-directed calls to that agent's own avatar instance.
+    const active = resolveActiveAgent(opts);
+    if (active) {
+        if (active.expired) {
+            console.error(`\x1b[2m  agent "${active.name}" identity expired — run: beehaven agent login ${active.name}\x1b[0m`);
+        }
+        console.error(`\x1b[2m→ as ${active.agentId} (avatar ${active.avatarId})\x1b[0m`);
+    }
+    try {
+        const result = await appRpcOnce(action, input, {
+            building,
+            instanceId,
+            timeout,
+            // Local app buildings are verified by the daemon's device-local signing secret. A cloud
+            // AgentIdentity token is for workspace RPCs and cannot be verified by that local daemon, so
+            // agent login stores both and this path deliberately uses the local credential.
+            agent: active?.localToken ?? active?.token,
+        });
+        if (result && typeof result === 'object') {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(result);
+        }
+    }
+    catch (err) {
+        console.error(JSON.stringify({ error: err.message }, null, 2));
+        process.exit(1);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// beehaven app run <recipe> — run a pipeline recipe from an installed app
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppRun(args, opts) {
+    const recipeName = args[0];
+    const instanceId = opts.instance ?? 'live';
+    const timeout = opts.timeout ? parseInt(opts.timeout, 10) : 120_000;
+    if (!recipeName) {
+        // List all available recipes across installed apps
+        ensureAppsDir();
+        const entries = readdirSync(APPS_DIR).filter((e) => !e.startsWith('.'));
+        const recipes = [];
+        for (const entry of entries) {
+            const manifestPath = join(APPS_DIR, entry, 'app.json');
+            if (!existsSync(manifestPath))
+                continue;
+            let m;
+            try {
+                m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            if (!m?.recipes)
+                continue;
+            for (const [rName, rPath] of Object.entries(m.recipes)) {
+                let title = rName;
+                const rFile = typeof rPath === 'string' ? join(APPS_DIR, entry, rPath) : null;
+                if (rFile && existsSync(rFile)) {
+                    try {
+                        const recipe = JSON.parse(readFileSync(rFile, 'utf8'));
+                        title = recipe.title ?? rName;
+                    }
+                    catch { }
+                }
+                recipes.push({ app: m.name, recipe: rName, title });
+            }
+        }
+        if (recipes.length === 0) {
+            console.log('');
+            console.log('  No recipes found. Install an app with recipes.');
+            console.log('');
+            return;
+        }
+        console.log('');
+        console.log('  Available Recipes');
+        console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        for (const r of recipes) {
+            console.log(`  ${r.app}/${r.recipe}`.padEnd(36) + r.title);
+        }
+        console.log('');
+        console.log('  Run: beehaven app run <app>/<recipe>');
+        console.log('');
+        return;
+    }
+    // Parse app/recipe format
+    let appName;
+    let rKey;
+    if (recipeName.includes('/')) {
+        [appName, rKey] = recipeName.split('/', 2);
+    }
+    else {
+        // Search all apps for a matching recipe name
+        ensureAppsDir();
+        const entries = readdirSync(APPS_DIR).filter((e) => !e.startsWith('.'));
+        let found = null;
+        for (const entry of entries) {
+            const manifestPath = join(APPS_DIR, entry, 'app.json');
+            if (!existsSync(manifestPath))
+                continue;
+            let m;
+            try {
+                m = JSON.parse(readFileSync(manifestPath, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            if (m?.recipes?.[recipeName]) {
+                found = { app: m.name, entry, recipe: recipeName };
+                break;
+            }
+        }
+        if (!found) {
+            console.error(`  ✗ Recipe "${recipeName}" not found. Run "beehaven app run" to list recipes.`);
+            process.exit(1);
+        }
+        appName = found.app;
+        rKey = found.recipe;
+    }
+    // Find the app directory and load the recipe
+    const appDir = readdirSync(APPS_DIR).find((e) => e.startsWith(`${appName}@`));
+    if (!appDir) {
+        console.error(`  ✗ App "${appName}" not installed.`);
+        process.exit(1);
+    }
+    const manifestPath = join(APPS_DIR, appDir, 'app.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        console.error(`  ✗ Could not read manifest for ${appName}`);
+        process.exit(1);
+    }
+    const recipePath = manifest.recipes?.[rKey];
+    if (!recipePath) {
+        console.error(`  ✗ Recipe "${rKey}" not found in ${appName}`);
+        process.exit(1);
+    }
+    const recipeFile = typeof recipePath === 'string' ? join(APPS_DIR, appDir, recipePath) : null;
+    if (!recipeFile || !existsSync(recipeFile)) {
+        console.error(`  ✗ Recipe file not found: ${recipePath}`);
+        process.exit(1);
+    }
+    let recipe;
+    try {
+        recipe = JSON.parse(readFileSync(recipeFile, 'utf8'));
+    }
+    catch (err) {
+        console.error(`  ✗ Invalid recipe JSON: ${err.message}`);
+        process.exit(1);
+    }
+    const steps = recipe.steps;
+    if (!Array.isArray(steps) || steps.length === 0) {
+        console.error('  ✗ Recipe has no steps.');
+        process.exit(1);
+    }
+    console.log('');
+    console.log(`  Running: ${recipe.title ?? recipeName}`);
+    console.log(`  Steps: ${steps.length}`);
+    console.log('  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    const { pipelineOnce } = await import('../ipc-client.js');
+    try {
+        const result = await pipelineOnce(steps, {
+            title: recipe.title ?? recipeName,
+            instanceId,
+            timeout,
+        });
+        if (result.ok) {
+            for (const step of result.steps) {
+                const icon = step.ok ? '✓' : '✗';
+                console.log(`  ${icon} ${step.id ?? step.action}`);
+            }
+            console.log('');
+            console.log(`  ✓ Done — ${result.steps.length} steps completed.`);
+        }
+        else {
+            console.error(`  ✗ Pipeline failed`);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`  ✗ ${err.message}`);
+        process.exit(1);
+    }
+}
+// ──────────────────────────────────────────────────────────────────────
+// Dispatcher
+// ──────────────────────────────────────────────────────────────────────
+export async function cmdAppSubcommand(subcommand, args, opts) {
+    switch (subcommand) {
+        case 'pack':
+            await cmdAppPack(args, opts);
+            break;
+        case 'install':
+            await cmdAppInstall(args, {
+                allowUnsigned: !!opts.allowUnsigned,
+                withSkills: !!opts.withSkills,
+                noSkills: !!opts.noSkills,
+            });
+            break;
+        case 'list':
+        case 'ls':
+            await cmdAppList();
+            break;
+        case 'uninstall':
+        case 'remove':
+        case 'rm':
+            await cmdAppUninstall(args);
+            break;
+        case 'actions':
+            await cmdAppActions(args, opts);
+            break;
+        case 'call':
+            await cmdAppCall(args, opts);
+            break;
+        case 'run':
+            await cmdAppRun(args, opts);
+            break;
+        case 'setup':
+            await cmdAppSetup(args[0]);
+            break;
+        default:
+            console.error(`  Unknown: beehaven app ${subcommand}`);
+            console.error('  Commands: pack, install, list, uninstall, actions, call, run, setup');
+            process.exit(1);
+    }
+}