@clearlysh/beehaven 0.8.16

package/dist/min-version-copy.js

@@ -0,0 +1,51 @@
+/**
+ * WHY a minimum was published — a closed set, with the wording written in advance.
+ *
+ * ⚠⚠ THE PUBLISHED FILE CARRIES A KEY, NEVER A SENTENCE. Two reasons, and the second is the one
+ * that decides it:
+ *
+ *   · `minimum.json` is served from a PUBLIC CDN. A free-text reason typed while arming a lockout
+ *     during a security incident publishes the vulnerability to everyone who has not yet updated —
+ *     the exact population the block exists to protect. A category cannot leak what it does not
+ *     contain.
+ *   · The copy is then written calmly, once, and can be improved without republishing a minimum.
+ *     The alternative is composing user-facing prose at 2am while people are locked out.
+ *
+ * ⚠ THE FLOOR IS WHAT THIS RAISES. `reason` was optional, so the realistic blocked message was the
+ * bare "no longer supported" — true, and the least actionable sentence available. A category is
+ * REQUIRED when arming, so there is always a second line saying what kind of thing happened.
+ *
+ * ⚠⚠ AND IT MUST NOT BECOME A LABEL PEOPLE STOP BELIEVING. "Security update" on a protocol change
+ * is a false claim, and two of those teach everyone to discount the word on the day it is true.
+ * Each key below means only what it says; if a block does not fit one, that is a signal the block
+ * needs more thought, not a new synonym for `security`.
+ *
+ * ⚠ AN UNKNOWN KEY RENDERS NOTHING, never the raw key. A client older than a category still shows
+ * the base message and the upgrade command, which is the whole cure — `security` printed as a bare
+ * word would read like a bug at the worst possible moment.
+ */
+export const MIN_VERSION_CATEGORIES = ['security', 'compatibility', 'data-safety'];
+/**
+ * One sentence per category, addressed to the person who is blocked.
+ *
+ * ⚠ IT SAYS WHAT TO DO OR WHY IT IS URGENT — never what the flaw was. See the leak note above.
+ */
+const COPY = {
+    security: 'This is a security update. Please upgrade now.',
+    compatibility: 'This version can no longer talk to the service.',
+    'data-safety': 'This version can corrupt or lose your work.',
+};
+/** Is this a category we publish? Used by the arming tool to refuse anything else. */
+export function isMinVersionCategory(v) {
+    return typeof v === 'string' && MIN_VERSION_CATEGORIES.includes(v);
+}
+/**
+ * The line to show, or `''` when there is nothing trustworthy to say.
+ *
+ * ⚠ TOTAL AND SILENT ON ANYTHING UNRECOGNISED — an absent key, a key from a newer publisher, junk
+ * in the field. Every one of those means "this client cannot explain the block", and the honest
+ * response is to say nothing extra rather than to guess or to echo.
+ */
+export function minVersionMessage(category) {
+    return isMinVersionCategory(category) ? COPY[category] : '';
+}

package/dist/min-version.js

@@ -0,0 +1,214 @@
+/**
+ * min-version — refuse to run a beehaven CLI below the minimum the server names.
+ *
+ * The CLI half of the mechanism documented in `docs/FORCE_UPDATE.md`. Same contract as the Mac
+ * app — a small JSON beside the published artifact — and the same governing rule:
+ *
+ *     BLOCK ONLY ON POSITIVE, COHERENT, ACTIONABLE EVIDENCE.
+ *
+ *     https://downloads.clearly.sh/cli/minimum.json
+ *     { "minVersion": "0.8.0", "reason": "The relay protocol changed." }
+ *
+ * ## ⚠ A CLI IS NOT AN APP, AND THREE THINGS CHANGE
+ *
+ *  1. NO BLOCKING FETCH ON THE COMMAND PATH. The desktop app checks at launch and every four
+ *     hours across a session that lasts all day; a CLI process lives for milliseconds, and a
+ *     network round trip on every invocation would put ~100ms of latency on `beehaven status`
+ *     forever. The verdict is CACHED on disk and refreshed at most once every six hours, in the
+ *     BACKGROUND — the current command is never delayed by the check it triggers.
+ *
+ *  2. THE REPAIR DEPENDS ON THE INSTALL. A curl install runs `beehaven update`; a bundled CLI
+ *     updates with the Mac app. The block must name the right path and allow the update verb.
+ *
+ *  3. THE ESCAPE HATCHES MUST STAY OPEN. `--version`, `--help` and anything that could upgrade or
+ *     diagnose the install keep working while blocked. Blocking `beehaven --version` would hide
+ *     the single fact a person needs to understand what just happened to them.
+ *
+ * Everything else is the app's design, for the app's reasons: fail open on any uncertainty, and
+ * never demand a version that is not actually published (see `shouldBlock`).
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { minVersionMessage } from './min-version-copy.js';
+import { homedir } from 'os';
+import { join } from 'path';
+// ⚠ ESM: there is no `__filename` here, and the detached refresh needs this module's own path.
+// Using the CommonJS global would throw inside the try and silently disable the refresh for ever
+// — the cache would stay empty and the gate would never fire at all.
+import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
+/**
+ * ⚠ THE CLI'S EXISTING COMPARATOR, not a second one. A private copy here would be the third
+ * implementation of "which version is newer" in this codebase, and the failure mode of two that
+ * disagree is telling a user on a NEWER build to downgrade. One comparator, one answer.
+ */
+import { compareVersions } from './version-utils.js';
+import { installKind, updateHint } from './commands/self-update.js';
+const FEED = process.env.BEEHAVEN_CLI_FEED || 'https://downloads.clearly.sh/cli/';
+const CACHE_FILE = join(homedir(), '.beehaven', 'min-version.json');
+const CACHE_TTL_MS = 6 * 60 * 60_000;
+const FETCH_TIMEOUT_MS = 4000;
+/** How a blocked user fixes it. The single most important string in this file. */
+export const UPGRADE_COMMAND = 'beehaven update';
+/**
+ * Commands that must NEVER be blocked.
+ *
+ * ⚠ `--version` ABOVE ALL. A person told "you are too old" needs to be able to ask what they
+ * have; blocking that turns a clear message into a mystery. `upgrade`/`install`/`doctor` are the
+ * repair verbs, and blocking a repair verb is how a recoverable state becomes a stuck one.
+ */
+const ALWAYS_ALLOWED = new Set([
+    '--version', '-v', 'version', '--help', '-h', 'help', 'update', 'upgrade', 'install', 'doctor',
+]);
+const isVersion = (v) => typeof v === 'string' && /^\d+\.\d+\.\d+([-+].*)?$/.test(v.trim());
+/**
+ * THE DECISION, pure and identical in spirit to the app's.
+ *
+ * ⚠ `latest` IS THE INTERLOCK THAT MATTERS. Requiring a version that is not published means
+ * telling every user to install something that does not exist — an unfixable lockout produced by
+ * a typo. If the feed cannot confirm a satisfying build exists, nobody is blocked.
+ */
+export function shouldBlock(input) {
+    const { current, minimum, latest } = input;
+    if (!isVersion(current))
+        return { block: false, why: 'current-version-unreadable' };
+    if (!minimum)
+        return { block: false, why: 'no-minimum-published' };
+    if (!isVersion(minimum))
+        return { block: false, why: 'minimum-unparseable' };
+    if (compareVersions(current, minimum) >= 0)
+        return { block: false, why: 'already-current' };
+    if (!isVersion(latest))
+        return { block: false, why: 'feed-unreadable' };
+    if (compareVersions(latest, minimum) < 0)
+        return { block: false, why: 'minimum-exceeds-published-version' };
+    return { block: true, why: 'below-minimum', minVersion: minimum };
+}
+function readCache() {
+    try {
+        const c = JSON.parse(readFileSync(CACHE_FILE, 'utf8'));
+        return typeof c?.checkedAt === 'number' ? c : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(c) {
+    try {
+        mkdirSync(join(homedir(), '.beehaven'), { recursive: true });
+        writeFileSync(CACHE_FILE, JSON.stringify(c), { mode: 0o600 });
+    }
+    catch { /* cache is an optimisation, never a requirement */ }
+}
+async function getText(url) {
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const r = await fetch(`${url}?_=${Date.now()}`, { signal: ctl.signal, cache: 'no-store' });
+        return r.ok ? await r.text() : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+/** Fetch the minimum + the newest published version, and cache the pair. */
+export async function refreshMinVersion() {
+    const [minBody, latestBody] = await Promise.all([
+        getText(`${FEED}minimum.json`),
+        getText(`${FEED}latest.json`),
+    ]);
+    let minVersion = null;
+    let reason = '';
+    let category = '';
+    try {
+        const j = JSON.parse(minBody || '{}');
+        if (isVersion(j?.minVersion))
+            minVersion = String(j.minVersion).trim();
+        if (typeof j?.reason === 'string')
+            reason = j.reason.slice(0, 300);
+        // ⚠ Stored raw and resolved at RENDER time, so an unrecognised key prints nothing rather than
+        //   itself — a cache written by a newer publisher must not make an older client echo a word.
+        if (typeof j?.category === 'string')
+            category = j.category.slice(0, 40);
+    }
+    catch { /* absent or malformed ⇒ no minimum */ }
+    let latest = null;
+    try {
+        const j = JSON.parse(latestBody || '{}');
+        if (isVersion(j?.version))
+            latest = String(j.version).trim();
+    }
+    catch { /* no manifest ⇒ cannot confirm ⇒ never blocks */ }
+    const c = { checkedAt: Date.now(), minVersion, latest, category, reason };
+    writeCache(c);
+    return c;
+}
+/**
+ * Gate the CLI. Returns true when the process should stop.
+ *
+ * ⚠ SYNCHRONOUS AND CHEAP. It reads a cached verdict and — when that is stale — spawns a
+ * DETACHED refresh that outlives this process. The current command never waits: at worst it runs
+ * once more on an old verdict, which is exactly the trade a millisecond-scale process should
+ * make. The alternative, awaiting a network call before every command, is a tax on thousands of
+ * invocations to catch a condition that arises once.
+ */
+export function enforceMinVersion(argv, currentVersion) {
+    try {
+        if (process.env.BEEHAVEN_SKIP_VERSION_CHECK === '1')
+            return false;
+        // The repair verbs and the diagnostic ones always run.
+        if (argv.some((a) => ALWAYS_ALLOWED.has(a)))
+            return false;
+        const cache = readCache();
+        const stale = !cache || Date.now() - cache.checkedAt > CACHE_TTL_MS;
+        if (stale)
+            refreshInBackground();
+        if (!cache)
+            return false; // never seen the server ⇒ never block
+        const verdict = shouldBlock({ current: currentVersion, minimum: cache.minVersion, latest: cache.latest });
+        if (!verdict.block)
+            return false;
+        const line = (s = '') => process.stderr.write(`${s}\n`);
+        line();
+        line(`  beehaven ${currentVersion} is no longer supported.`);
+        /**
+         * ⚠ THE CATEGORY FIRST, THE LEGACY REASON ONLY IF THERE IS NO CATEGORY. Both would print two
+         * explanations of one block, and the older one is the free text this design removed.
+         */
+        const why = minVersionMessage(cache.category) || cache.reason;
+        if (why)
+            line(`  ${why}`);
+        line();
+        line(`  Version ${verdict.minVersion} or later is required. To update:`);
+        line();
+        line(`      ${installKind() === 'user' ? UPGRADE_COMMAND : updateHint(installKind())}`);
+        line();
+        return true;
+    }
+    catch {
+        return false; // ⚠ A THROW HERE MUST NOT BLOCK. Nothing about this check is worth an outage.
+    }
+}
+/**
+ * Refresh without delaying anything.
+ *
+ * ⚠ DETACHED AND UNREF'D. Doing it in-process would either block the command (defeating the
+ * point) or be killed the moment the command exits, so the cache would never populate and the
+ * gate would never fire at all.
+ */
+function refreshInBackground() {
+    try {
+        const self = fileURLToPath(import.meta.url);
+        const child = spawn(process.execPath, [self, '--refresh-min-version'], {
+            detached: true, stdio: 'ignore',
+        });
+        child.unref();
+    }
+    catch { /* best-effort */ }
+}
+// Entry point for the detached refresh above.
+if (process.argv[2] === '--refresh-min-version') {
+    void refreshMinVersion().finally(() => process.exit(0));
+}

package/dist/public-surface.js

@@ -0,0 +1,23 @@
+/** Public app/command policy shared by the CLI and daemon catalog surfaces. */
+export const PUBLICLY_HIDDEN_APP_NAMES = new Set([
+    'mwah', 'clearly-voice', 'recorder', 'claude-code', 'memory-cloud',
+    'ableton', 'blender', 'logic-pro', 'hue', 'nitepunk-piano',
+    'shopify', 'figma', 'jira', 'gsc', 'marketing', 'backlinks',
+    'vector', 'image', 'bee-canvas',
+]);
+/** Voice/TTS commands are retained in source but withheld from the public CLI for now. */
+export const HIDDEN_PUBLIC_COMMANDS = new Set(['speak', 'voice', 'tts']);
+/** Avatar actions whose public CLI surface is paused with voice/TTS. */
+export const HIDDEN_PUBLIC_APP_ACTIONS = new Set([
+    'speak', 'stream', 'setTts', 'voices', 'transcribe', 'transcribeCancel', 'transcribeStats',
+]);
+export function isPubliclyVisibleAppAction(building, action) {
+    return String(building ?? '').split('/')[0].toLowerCase() !== 'avatar'
+        || !HIDDEN_PUBLIC_APP_ACTIONS.has(String(action ?? ''));
+}
+export function isPubliclyVisibleApp(app) {
+    if (process.env.HIVE_DEV_MODE === '1')
+        return true;
+    const name = String(app?.name ?? '').trim().toLowerCase();
+    return !!name && !PUBLICLY_HIDDEN_APP_NAMES.has(name) && app?.internal !== true;
+}

package/dist/relay-presets.js

@@ -0,0 +1,89 @@
+/**
+ * Pure relay-selection helpers — the single READ-side source of truth for
+ * "which relay / which env" from a loaded ~/.beehaven/config.json.
+ *
+ * Kept in its own dependency-free module (no disk, no daemon imports) so EVERY
+ * surface that reports the relay — `beehaven env`, `whoami`/status, the admin
+ * console URL, auth-origin selection, the daemon spawn path — can import it
+ * WITHOUT pulling in the heavy daemon module graph.
+ *
+ * `endpoint` is the load-bearing key: the relay client (`Relay.loadConfig`)
+ * returns null without it and dials `config.endpoint`. `relayUrl` / `envName`
+ * are back-compat ALIASES — never trust them over the derived value, or the
+ * report drifts from what the daemon actually dials (the bug this fixes: a
+ * fresh login / Mac-app install writes only `endpoint`, leaving the aliases
+ * stale or unset).
+ */
+/** Map env name → relay URL. Used by `beehaven env <name>`. */
+export const RELAY_PRESETS = {
+    prod: 'wss://relay.clearly.sh',
+    staging: 'wss://bee-relay-staging.throbbing-unit-1b3f.workers.dev',
+    dev: 'ws://localhost:8787',
+};
+/**
+ * The canonical dial target from a config:
+ *   1. `endpoint` — what the relay client actually connects to
+ *   2. `relayUrl` — legacy alias, kept in sync for back-compat
+ * Returns undefined when neither is set so each caller picks its own default
+ * (the daemon falls back to prod; admin commands error instead).
+ */
+export function relayUrlFromConfig(cfg) {
+    if (cfg && typeof cfg.endpoint === 'string' && cfg.endpoint.length > 0)
+        return cfg.endpoint;
+    if (cfg && typeof cfg.relayUrl === 'string' && cfg.relayUrl.length > 0)
+        return cfg.relayUrl;
+    return undefined;
+}
+/**
+ * Resolve BOTH the relay URL and the env NAME from a config, keying off the
+ * canonical endpoint. The name is derived FROM the resolved URL (reverse
+ * RELAY_PRESETS lookup, else 'custom') so a stale `envName` alias can never
+ * mislabel the connection. This is the one helper every "which env" surface
+ * must use instead of reading cfg.envName / cfg.relayUrl directly.
+ */
+export function resolveRelaySelection(cfg) {
+    const url = relayUrlFromConfig(cfg) ?? RELAY_PRESETS.prod;
+    const envName = Object.keys(RELAY_PRESETS).find((k) => RELAY_PRESETS[k] === url) ?? 'custom';
+    return { url, envName };
+}
+/**
+ * ⚠⚠ THE ONE ORIGIN RESOLVER ON THIS SIDE — where the WEB APP lives for the env this daemon dials.
+ *
+ * ── WHY IT EXISTS (CBH-45) ────────────────────────────────────────────────────────────────────
+ *
+ * `beehaven open <uuid>` printed `https://localhost:3000/documents/…` on one run and
+ * `https://www.clearly.sh/documents/…` on the next, same workspace, seconds apart. The server
+ * preferred `_uiClientOrigin` — ONE workspace-global slot any browser overwrites on mount — so
+ * whichever of ten connected surfaces reported last decided the URL for every caller, and a
+ * developer's dev tab made this CLI print a link to a server it has never run. The printed URL is
+ * the only thing a CLI user can act on, so that is a dead link that reads as a broken document.
+ *
+ * The server now prefers the origin the CALLER declares. This is what the CLI declares, and it is
+ * derived from the env the daemon is actually dialling — so the answer is a property of THIS
+ * machine's configuration and cannot be moved by anyone else's tab.
+ *
+ * ⚠ THERE WERE AT LEAST THREE SPELLINGS IN THE TREE and this is now the only one:
+ *   `https://www.clearly.sh` (open), `https://clearly.sh` (canvas.ts — apex, no www) and
+ *   `https://localhost:3000` (canvas.ts's `--dev` branch). They are not interchangeable: the apex
+ *   301s to www, so the apex spelling handed people a link with a redirect in it.
+ *
+ * ⚠ STAGING RETURNS THE PRODUCTION SITE, AND THAT IS CORRECT. The frontend is prod-only — the
+ * `staging.clearly-sh.pages.dev` alias is retired (CLAUDE.md) — so the staging worker's app really
+ * is `www.clearly.sh`. Inventing a `staging.clearly.sh` here would be the dead-link bug again.
+ *
+ * ⚠ `custom` RETURNS undefined, DELIBERATELY. A custom relay says nothing about where its frontend
+ * is, and guessing production for it is how you hand someone a link into the wrong deployment.
+ * The caller then declares nothing and the server falls back to its own env — which knows.
+ */
+export function appOriginForEnv(envName) {
+    switch (envName) {
+        case 'prod':
+        case 'staging':
+            return 'https://www.clearly.sh';
+        // `npm run dev` is `next dev --experimental-https`, so the local app is HTTPS, not HTTP.
+        case 'dev':
+            return 'https://localhost:3000';
+        default:
+            return undefined;
+    }
+}