@clearlysh/beehaven 0.8.16

package/dist/cli-state.js

@@ -0,0 +1,334 @@
+/**
+ * cli-state — CLI-side session state.
+ *
+ * Where we are (the "connected target") lives in `~/.beehaven/target.json` — or
+ * `target-<agent>.json` when $BEEHAVEN_AGENT is set, so concurrent agents don't
+ * clobber each other (see targetFileFor). Not daemon RAM: that makes the daemon
+ * stateless for navigation, so daemon restarts can't lose your target and
+ * `beehaven pwd` works without the daemon running at all.
+ *
+ * Contract:
+ *   - `beehaven cd <addr>`    → setTarget(...) writes the file
+ *   - `beehaven cd home`      → clearTarget() removes it (home is the default)
+ *   - `beehaven disconnect`   → clearTarget()
+ *   - `beehaven pwd`          → getTarget() reads it
+ *   - any `beehaven call`     → getTarget() reads it before falling back to daemon
+ *
+ * Why this shape instead of daemon-owned state:
+ *   - Daemon restart used to silently lose your target, misrouting the
+ *     next command to home. File-based state survives anything short of
+ *     `rm -rf ~/.beehaven`.
+ *   - `pwd` becomes infinitely cheap — no IPC round-trip.
+ *   - The CLI can be used during Mac-app startup before the daemon's
+ *     fully up.
+ *
+ * Why NOT put it in the daemon even as a sync'd cache:
+ *   - Two sources of truth is always worse than one. Either side could
+ *     diverge. Single source of truth is the file.
+ *
+ * The daemon's own `connectedBuilding` is mostly a focus/relay-routing
+ * optimization (it needs to know what to pre-warm) — but it IS still
+ * authoritative in one case, and this used to claim otherwise ("no longer
+ * authoritative for 'where is the user'"). It isn't true: when NO target file
+ * exists, `case 'call'` in cli.ts falls back to `daemonGetConnection()` and routes
+ * there (it calls itself a legacy fallback).
+ *
+ * That matters most for AGENTS. The fallback is machine-global — set by any other
+ * process, another room, the Mac app, a human's terminal — so an agent that never
+ * runs `connect` doesn't get "home", it inherits someone else's cursor, silently.
+ * Which is why the canvas skill tells agents to `beehaven connect home` FIRST: it
+ * looks redundant (home is the address-grammar default) and it is not. Pinning the
+ * target is what stops the inheritance. Pin it, or pass `--building` per call.
+ */
+import { deriveAgentScope } from './agent-scope.js';
+import { agentForScope } from './agent-state.js';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, renameSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+const STATE_DIR = join(homedir(), '.beehaven');
+/**
+ * PER-AGENT target scoping — one `target.json` per identity, not one per machine.
+ *
+ * This file's own docs have always promised it ("it rides with the identity-bound
+ * session: each terminal ($BEEHAVEN_AGENT) keeps its own target.json cwd") and the
+ * path never delivered it: `target.json`, one file, shared by every process on the
+ * box. `BEEHAVEN_AGENT` appeared exactly once in this module — in that sentence.
+ *
+ * It matters because AI AGENTS RUN CONCURRENTLY. The desktop hosts four rooms
+ * (claude/codex/gemini/pi) that can each shell out at the same time, and the
+ * documented workflow is `connect` then `call` — so room B's `connect team/x`
+ * silently re-pointed room A's next `call`, with no error and no way for A to
+ * know. A human types `connect` in one terminal and notices; a fleet of agents
+ * does not. Low blast radius today (every room connects to `home`, the same
+ * value), unbounded the moment one connects to a team or a store.
+ *
+ * Unscoped stays `target.json` — a human shell with no BEEHAVEN_AGENT set keeps
+ * the exact file it has today, so nothing migrates and nothing breaks.
+ *
+ * SANITISED because this lands in a filesystem path: `BEEHAVEN_AGENT=../../..`
+ * would otherwise escape STATE_DIR. Anything but [A-Za-z0-9_-] is dropped, and a
+ * name that sanitises to nothing falls back to the shared file rather than
+ * silently writing `target-.json`.
+ */
+/**
+ * ⚠⚠ A LOGGED-IN AGENT'S CURSOR FOLLOWS THE AGENT, NOT THE PROCESS.
+ *
+ * `deriveAgentScope()` returns a per-SESSION handle (`claude-<sessionId>`), which isolates
+ * concurrent agents but resets every conversation — so a durable agent would start at home
+ * each time and lose the workspace it had chosen.
+ *
+ * Once `agent login` has bound this scope to a named agent, key the cursor on the AGENT
+ * instead. That is what unifies the three handles: identity, workspace session and cursor
+ * all resolve from one name.
+ *
+ * ⚠ REVERSE LOOKUP, NOT A STORED POINTER. A pointer would be one more machine-global file to
+ * clobber — the exact bug this whole area exists to fix. The binding lives on the agent
+ * record, and `agentForScope` refuses when two agents claim one scope rather than picking.
+ *
+ * ⚠ LAZY + GUARDED: `agent-state` reads `~/.beehaven/agents/*`, which may not exist, and this
+ * runs at module load for TARGET_FILE. A throw here would break `pwd` for everyone.
+ */
+export function effectiveScope() {
+    const raw = deriveAgentScope();
+    if (!raw)
+        return ''; // a human — the shared file
+    try {
+        const bound = agentForScope(raw);
+        if (bound)
+            return bound;
+    }
+    catch { /* no agents dir, or a bad record — fall back to the process scope */ }
+    return raw;
+}
+function targetFileFor(agent = effectiveScope()) {
+    const safe = (agent || '').trim().replace(/[^A-Za-z0-9_-]/g, '');
+    return join(STATE_DIR, safe ? `target-${safe}.json` : 'target.json');
+}
+const TARGET_FILE = targetFileFor();
+/** Exported for the scoping test — the path rule is security-relevant (it takes an env var into a filesystem path), so it gets asserted rather than eyeballed. */
+export const __targetFileFor = targetFileFor;
+/**
+ * Every address that means "the user's default workspace".
+ *
+ * `beehaven cd home` accepts `home` / `me` / `workspace` and PERSISTS the
+ * canonical `workspace`. Readers that only compared against the literal
+ * `'home'` therefore failed on a target the `cd` had just written — `sql`,
+ * `ls`, `cat`, `grep` and `tree` all answered "Cannot determine target"
+ * directly after a successful `cd home`, and suggested running it again.
+ * Writer and readers now share THIS set; extend it here or nowhere.
+ */
+export const HOME_ADDRESSES = new Set(['workspace', 'home', 'me']);
+/** The address `cd` writes for the default workspace. */
+export const CANONICAL_HOME_ADDRESS = 'workspace';
+/** Re-exported so callers keep one import site; the derivation lives in agent-scope.ts. */
+export { deriveAgentScope };
+/** True when an address refers to the default workspace. */
+export function isHomeAddress(address) {
+    return !!address && HOME_ADDRESSES.has(address);
+}
+/**
+ * Read the current target. Returns null when no target is set — which
+ * means "use home" per the address grammar.
+ *
+ * Never throws: bad JSON, missing file, unreadable permissions all
+ * return null. Defensive because this runs on every `beehaven call`.
+ */
+export function getTarget() {
+    try {
+        if (!existsSync(TARGET_FILE))
+            return null;
+        const raw = readFileSync(TARGET_FILE, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.address !== 'string' || !parsed.address)
+            return null;
+        if (typeof parsed?.connectedAt !== 'number')
+            return null;
+        return {
+            address: parsed.address,
+            connectedAt: parsed.connectedAt,
+            kind: parsed.kind,
+            cwd: typeof parsed.cwd === 'string' && parsed.cwd ? parsed.cwd : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Current working directory within the target DO. Returns "/" (root) when
+ * unset. Read by `ask` (routes to the cwd-layer Librarian), `pwd`, and the
+ * default `ls`/`tree`.
+ */
+export function getCwd() {
+    const t = getTarget();
+    return t?.cwd && t.cwd.trim() ? t.cwd : '/';
+}
+/**
+ * Resolve a `cd` argument against the current cwd to an absolute DO path —
+ * the pure core of `beehaven cd`. Mirrors shell semantics:
+ *   - "/", "~"     → root
+ *   - "."          → unchanged
+ *   - "/abs/path"  → resolved from root (leading slash resets the base)
+ *   - "rel/path"   → resolved against `current`
+ *   - ".." segments pop a level (never past root); "." / empty segments skip
+ * Always returns a normalized absolute path with no trailing slash (except "/").
+ * Kept side-effect-free so the navigation rules are unit-testable.
+ */
+export function resolveCwd(current, input) {
+    const cur = current && current.trim() ? current : '/';
+    let next;
+    if (input === '~' || input === '/') {
+        next = '/';
+    }
+    else if (input === '.') {
+        next = cur;
+    }
+    else {
+        const base = input.startsWith('/') ? [] : cur === '/' ? [] : cur.split('/').filter(Boolean);
+        const rel = input.replace(/^\//, '');
+        for (const seg of rel.split('/')) {
+            if (seg === '..')
+                base.pop();
+            else if (seg && seg !== '.')
+                base.push(seg);
+        }
+        next = '/' + base.join('/');
+    }
+    if (next.length > 1)
+        next = next.replace(/\/+$/, '');
+    return next;
+}
+/**
+ * Set the cwd cursor within the CURRENT target DO, preserving the target. When
+ * no target is set (home), writes an explicit `home` target carrying the cwd so
+ * navigation persists. Pass "/" (or empty) to return to root.
+ */
+export function setCwd(cwd) {
+    const cur = getTarget();
+    const address = cur?.address ?? 'home';
+    const kind = cur?.kind ?? inferKind(address);
+    const normalized = !cwd || cwd === '/' ? undefined : cwd;
+    const target = {
+        address,
+        connectedAt: cur?.connectedAt ?? Date.now(),
+        kind,
+        ...(normalized ? { cwd: normalized } : {}),
+    };
+    ensureStateDir();
+    const tmp = `${TARGET_FILE}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(target, null, 2), { mode: 0o600 });
+    try {
+        renameSync(tmp, TARGET_FILE);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+    return target;
+}
+/**
+ * Write a new target. Overwrites any existing target (last-write-wins;
+ * concurrent `cd` from two shells is user error, not something we try
+ * to reconcile).
+ *
+ * `kind` defaults to inferring from the address:
+ *   - contains slash → 'cloud'
+ *   - bare name      → 'local'
+ *   - 'home' / 'me'  → 'home' (but callers should prefer clearTarget for home)
+ */
+export function setTarget(address, kind) {
+    if (!address || typeof address !== 'string') {
+        throw new Error('setTarget: address must be a non-empty string');
+    }
+    const resolvedKind = kind ?? inferKind(address);
+    const target = {
+        address,
+        connectedAt: Date.now(),
+        kind: resolvedKind,
+    };
+    ensureStateDir();
+    // Atomic write — tmp file then rename — so a crash mid-write can't
+    // leave a partial target.json that subsequent reads fail to parse.
+    const tmp = `${TARGET_FILE}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(target, null, 2), { mode: 0o600 });
+    try {
+        // renameSync is atomic on POSIX
+        renameSync(tmp, TARGET_FILE);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+    return target;
+}
+/**
+ * Clear the current target. `beehaven cd home` and `beehaven disconnect`
+ * both call this; home is represented by the ABSENCE of a target file
+ * (not a target with address='home'), so downstream code has a single
+ * condition to check.
+ */
+export function clearTarget() {
+    try {
+        if (existsSync(TARGET_FILE))
+            unlinkSync(TARGET_FILE);
+    }
+    catch {
+        // Unlink can fail if the file just stopped existing between the
+        // check and the call. That's fine.
+    }
+}
+/**
+ * Age of the current target in ms. Returns -1 when no target is set.
+ * Used by `pwd` to surface session freshness.
+ */
+export function getTargetAgeMs() {
+    const t = getTarget();
+    if (!t)
+        return -1;
+    return Math.max(0, Date.now() - t.connectedAt);
+}
+/**
+ * Split an address into `{buildingType, buildingId}`. Returns null for
+ * bare names (local apps) and for 'home'/'me'.
+ */
+export function parseAddress(address) {
+    // 'workspace' is the canonical default (direct over the relay); 'home'/'me' are silent
+    // aliases. A bare 'workspace' has no id → not a type/id address → null (default routing).
+    if (!address || address === 'workspace' || address === 'home' || address === 'me')
+        return null;
+    const slash = address.indexOf('/');
+    if (slash <= 0 || slash === address.length - 1)
+        return null;
+    return {
+        buildingType: address.slice(0, slash),
+        buildingId: address.slice(slash + 1),
+    };
+}
+// ── Internal ────────────────────────────────────────────────────────────
+function ensureStateDir() {
+    try {
+        if (!existsSync(STATE_DIR)) {
+            mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+        }
+    }
+    catch {
+        // If this fails we'll see the error on writeFileSync — no point
+        // pre-throwing here.
+    }
+}
+function inferKind(address) {
+    if (address === 'workspace' || address === 'home' || address === 'me')
+        return 'home';
+    return address.includes('/') ? 'cloud' : 'local';
+}
+// Exposed for tests.
+export const __testing = {
+    TARGET_FILE,
+    STATE_DIR,
+};