brane 0.1.1 → 0.3.1

package/dist/commands/doctor.js

@@ -0,0 +1,262 @@
+import { defineCommand } from "citty";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { openDatabase, getDaemonAddress, getTokenFilePath } from "../db/schema.js";
+import { ACCOUNT_HASH_PREFIX, readTokenFile, tokenFileStanding } from "../db/tokens.js";
+import { readDaemonSocket } from "../daemon/client.js";
+import { accountDirTrust } from "../daemon/local-socket.js";
+import { resolveTmux } from "../tmux.js";
+import { getTailscaleHost } from "../tailscale.js";
+/**
+ * `brane doctor` — is this install sound, on the machine it landed on?
+ *
+ * Two halves. The first is a handful of environment checks that are cheap to
+ * run and expensive to discover by surprise: the Node this CLI runs under
+ * against `engines`, whether tmux and Tailscale are reachable, and whether a
+ * daemon is running — and if so, whether it is running *this* install's code
+ * or some other checkout's. The second is the shipped test suite: `dist/test`
+ * is in the tarball on purpose, so an install can prove itself. It runs under
+ * the same `node` binary as this process, streams the reporter, and the
+ * command exits with the suite's status. Neither half needs a daemon,
+ * network, or the embedding model.
+ */
+const INSTALL_DIR = resolve(join(dirname(fileURLToPath(import.meta.url)), "..", ".."));
+const require = createRequire(import.meta.url);
+const pkg = require("../../package.json");
+const MARK = { ok: "✓", warn: "–", fail: "✗" };
+function checkNode() {
+    const want = pkg.engines?.node ?? ">=20";
+    const min = Number(/(\d+)/.exec(want)?.[1] ?? "20");
+    const major = Number(process.versions.node.split(".")[0]);
+    return {
+        name: "node",
+        status: major >= min ? "ok" : "fail",
+        detail: `${process.version} at ${process.execPath} (engines ${want})`,
+    };
+}
+function checkTmux() {
+    try {
+        return { name: "tmux", status: "ok", detail: resolveTmux() };
+    }
+    catch {
+        return {
+            name: "tmux",
+            status: "warn",
+            detail: "not found — spawn will try to download a static binary into ~/.brane/bin; otherwise `brew install tmux`",
+        };
+    }
+}
+function checkTailscale() {
+    const host = getTailscaleHost();
+    return host
+        ? { name: "tailscale", status: "ok", detail: host }
+        : {
+            name: "tailscale",
+            status: "warn",
+            detail: "not detected — `brane meld` will only advertise 127.0.0.1 (same machine)",
+        };
+}
+/** The daemon's argv[1], so we can say which checkout it is actually running. */
+function daemonScript(pid) {
+    const res = spawnSync("ps", ["-p", String(pid), "-o", "command="], { encoding: "utf8" });
+    if (res.status !== 0)
+        return undefined;
+    const parts = res.stdout.trim().split(/\s+/);
+    return parts[1];
+}
+/** Why this shell could not talk to a running daemon, or null if it can.
+ *  Running is one question and reach is another: an agent session presents
+ *  its own token; anything else presents nothing at all over the daemon's
+ *  socket, which the daemon lets in only while the brane dir keeps other
+ *  accounts out. Pure, for src/test/socket-account.test.ts. */
+export function shellReachProblem(opts) {
+    if (opts.secret)
+        return null;
+    if (!opts.socketPath) {
+        return ("it is not listening on its socket (daemon.sock), the only way this shell reaches it; " +
+            "`brane daemon logs` says why (`[socket]`), and `brane daemon restart` retries");
+    }
+    const trust = accountDirTrust(opts.braneDir);
+    if (!trust.ok) {
+        return `it will refuse this shell without a token: ${trust.reason}; run \`chmod 700 ${opts.braneDir}\``;
+    }
+    return null;
+}
+function checkDaemon() {
+    let db;
+    try {
+        db = openDatabase();
+    }
+    catch (err) {
+        return { name: "daemon", status: "fail", detail: `could not open ~/.brane/brane.db: ${String(err)}` };
+    }
+    try {
+        const info = getDaemonAddress(db);
+        if (!info)
+            return { name: "daemon", status: "warn", detail: "not running (any command that needs it will start one)" };
+        const unreachable = shellReachProblem({
+            secret: process.env.BRANE_NARRATIVE_SECRET,
+            socketPath: readDaemonSocket(db),
+            braneDir: dirname(db.name),
+        });
+        if (unreachable)
+            return { name: "daemon", status: "fail", detail: `running, but ${unreachable}` };
+        const pidRow = db.prepare("SELECT value FROM meta WHERE key = 'daemon_pid'").get();
+        const pid = pidRow ? Number(pidRow.value) : NaN;
+        // Which checkout is the daemon actually running? Its argv[1] is a
+        // `dist/cli.js` — behind the `/opt/homebrew/bin/brane` symlink, usually —
+        // and that checkout's package.json says which version, which the meta
+        // table does not (it records a coarse compatibility version).
+        let where = "";
+        let status = "ok";
+        const script = Number.isFinite(pid) ? daemonScript(pid) : undefined;
+        if (script) {
+            let real = script;
+            try {
+                real = realpathSync(script);
+            }
+            catch { }
+            const theirs = dirname(dirname(resolve(real)));
+            if (theirs === INSTALL_DIR) {
+                where = " — this install";
+            }
+            else {
+                let theirVersion = "unknown version";
+                try {
+                    theirVersion = JSON.parse(readFileSync(join(theirs, "package.json"), "utf8")).version ?? theirVersion;
+                }
+                catch { }
+                where = ` — a different checkout: ${theirs} (${theirVersion}; this install is ${pkg.version})`;
+                status = "warn";
+            }
+        }
+        return {
+            name: "daemon",
+            status,
+            detail: `running, pid ${pid}, port ${info.port}${where}`,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/** What to say about a `.daemon_token` left by an older brane, which kept
+ *  this machine's local token there. The daemon empties it at its first
+ *  start and nothing presents it; removing the file is the operator's to do.
+ *  `standing` is `empty` for that normal leftover, else how a token still in
+ *  it stands (`tokenFileStanding`): the daemon could not empty it. Pure, for
+ *  src/test/socket-account.test.ts. */
+export function leftoverTokenFile(path, standing) {
+    const remove = `rm ${path}`;
+    return {
+        name: "token file",
+        status: "warn",
+        detail: standing === "empty"
+            ? `${path} is an empty leftover from an older brane; nothing uses it. Remove it: ${remove}`
+            : standing === "dead"
+                ? `${path} still holds a token from an older brane, which the daemon could not empty; the token no longer works. Remove it: ${remove}`
+                : `${path} still holds a token that works (the one every device shared before tokens were hashed), which the daemon could not empty. Remove it: ${remove}`,
+    };
+}
+/** The `token file` check for the `.daemon_token` at `path`, or null when
+ *  there is nothing to say: no file, or one that still holds a token before
+ *  this version's daemon has started once — nothing has retired it yet, and
+ *  the daemon's first start will. Takes the database, for
+ *  src/test/socket-account.test.ts. */
+export function tokenFileCheck(db, path) {
+    if (!existsSync(path))
+        return null;
+    const token = readTokenFile(path);
+    if (!token)
+        return leftoverTokenFile(path, "empty");
+    const hasAccountRow = db
+        .prepare(`SELECT 1 FROM tokens WHERE kind = 'local' AND revoked_at IS NULL AND hash LIKE '${ACCOUNT_HASH_PREFIX}%'`)
+        .get();
+    if (!hasAccountRow)
+        return null;
+    return leftoverTokenFile(path, tokenFileStanding(db, token));
+}
+function checkTokenFile() {
+    let db;
+    try {
+        db = openDatabase();
+    }
+    catch {
+        return null; // checkDaemon already reports a database that will not open
+    }
+    try {
+        return tokenFileCheck(db, getTokenFilePath(db));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db.close();
+    }
+}
+function printChecks(checks) {
+    const width = Math.max(...checks.map((c) => c.name.length));
+    for (const c of checks) {
+        console.log(`${MARK[c.status]} ${c.name.padEnd(width)}  ${c.detail}`);
+    }
+}
+/** Run the shipped suite under this process's node; returns its exit status. */
+function runSuite() {
+    const dir = join(INSTALL_DIR, "dist", "test");
+    if (!existsSync(dir)) {
+        console.error(`✗ suite  dist/test not found under ${INSTALL_DIR} — run \`npm run build\` in a checkout, or reinstall the package`);
+        return 1;
+    }
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith(".test.js"))
+        .sort()
+        .map((f) => join(dir, f));
+    if (files.length === 0) {
+        console.error(`✗ suite  no test files in ${dir}`);
+        return 1;
+    }
+    console.log(`\nRunning the shipped test suite: ${files.length} files under ${dir}\n`);
+    const res = spawnSync(process.execPath, ["--test", ...files], { stdio: "inherit" });
+    if (res.error) {
+        console.error(`✗ suite  could not start node --test: ${res.error.message}`);
+        return 1;
+    }
+    return res.status ?? 1;
+}
+export const doctorCommand = defineCommand({
+    meta: {
+        name: "doctor",
+        description: "Check this install (node, tmux, Tailscale, daemon) and run the shipped test suite against it",
+    },
+    args: {
+        suite: {
+            type: "boolean",
+            description: "Run the shipped test suite (default: yes; --no-suite for checks only)",
+            default: true,
+        },
+        "suite-only": {
+            type: "boolean",
+            description: "Skip the environment checks and only run the test suite",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        let failed = false;
+        if (!args["suite-only"]) {
+            console.log(`brane ${pkg.version} at ${INSTALL_DIR}\n`);
+            const checks = [checkNode(), checkTmux(), checkTailscale(), checkDaemon(), checkTokenFile()].filter((c) => c !== null);
+            printChecks(checks);
+            failed = checks.some((c) => c.status === "fail");
+        }
+        if (args.suite) {
+            const status = runSuite();
+            if (status !== 0)
+                failed = true;
+        }
+        process.exit(failed ? 1 : 0);
+    },
+});
+//# sourceMappingURL=doctor.js.map

package/dist/commands/fold.js

@@ -0,0 +1,95 @@
+import { defineCommand } from "citty";
+import { resolve } from "node:path";
+import { resolveDaemonEndpoint, daemonRequest, warnIfVersionMismatch } from "../daemon/client.js";
+function describeFold(fold) {
+    const created = new Date(fold.created_at).toLocaleDateString();
+    const spawned = fold.last_spawned
+        ? new Date(fold.last_spawned).toLocaleDateString()
+        : "never";
+    return [
+        `Fold: ${fold.path}${fold.archived ? "  (archived)" : ""}`,
+        `  created: ${created}  last spawned: ${spawned}${fold.brane_id ? `  brane: ${fold.brane_id}` : ""}`,
+    ];
+}
+/** The fold's line plus the narratives spawned from it — the listing the
+ *  daemon already serves, filtered to this fold. */
+export function formatFoldInfo(fold, narratives) {
+    const lines = describeFold(fold);
+    const mine = narratives.filter((n) => n.fold_path === fold.path).slice(0, 10);
+    if (mine.length > 0) {
+        lines.push("", "  Narratives:");
+        for (const n of mine) {
+            const icon = n.status === "active" ? "●" : "○";
+            lines.push(`    ${icon} ${n.id} (${n.agent_type}, ${n.role})`);
+        }
+    }
+    return lines.join("\n");
+}
+export function formatFoldList(folds) {
+    if (folds.length === 0) {
+        return "No folds registered. Run `brane fold` in a directory to register it.";
+    }
+    const lines = ["Registered folds:", ""];
+    for (const fold of folds) {
+        const created = new Date(fold.created_at).toLocaleDateString();
+        const spawned = fold.last_spawned
+            ? new Date(fold.last_spawned).toLocaleDateString()
+            : "never";
+        const braneTag = fold.brane_id ? `  brane: ${fold.brane_id}` : "";
+        lines.push(`  ${fold.path}${fold.archived ? "  (archived)" : ""}`);
+        lines.push(`    created: ${created}  last spawned: ${spawned}${braneTag}`, "");
+    }
+    return lines.join("\n");
+}
+export const foldCommand = defineCommand({
+    meta: {
+        name: "fold",
+        description: "Register the current directory as a fold (spawn point)",
+    },
+    args: {
+        directory: {
+            type: "positional",
+            description: "Directory to fold (default: current directory)",
+            required: false,
+        },
+        list: {
+            type: "boolean",
+            description: "List all registered folds",
+        },
+        brane: {
+            type: "string",
+            description: "Associate this fold with a brane ID",
+        },
+    },
+    async run({ args }) {
+        try {
+            // Registration is `POST /api/folds`, the same route the app's "add a
+            // spawn point" uses. The daemon recognizes this CLI as a loopback
+            // caller and grants it the reach the operator's shell always had;
+            // a remote client is confined to $HOME.
+            const endpoint = await resolveDaemonEndpoint();
+            warnIfVersionMismatch(endpoint);
+            if (args.list) {
+                const { folds } = await daemonRequest(endpoint, "/api/folds?archived=1");
+                console.log(formatFoldList(folds));
+                return;
+            }
+            const absolute = resolve(args.directory ?? process.cwd());
+            const { fold, created } = await daemonRequest(endpoint, "/api/folds", { method: "POST", body: { path: absolute, ...(args.brane ? { brane_id: args.brane } : {}) } });
+            if (created) {
+                console.log(`Folded: ${fold.path} (brane: ${fold.brane_id})`);
+                return;
+            }
+            // Already registered: the brane may have been rebound; show the fold.
+            if (args.brane)
+                console.log(`Updated brane: ${args.brane}`);
+            const { narratives } = await daemonRequest(endpoint, "/api/narratives");
+            console.log(formatFoldInfo(fold, narratives));
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+});
+//# sourceMappingURL=fold.js.map

package/dist/commands/list.js

@@ -0,0 +1,89 @@
+import { defineCommand } from "citty";
+import { resolveDaemonEndpoint, daemonRequest, warnIfVersionMismatch } from "../daemon/client.js";
+import { timeSince } from "./memory.js";
+export const listCommand = defineCommand({
+    meta: {
+        name: "list",
+        description: "List narratives grouped by brane",
+    },
+    args: {
+        brane: {
+            type: "string",
+            description: "Filter to a specific brane ID",
+        },
+        archived: {
+            type: "boolean",
+            description: "Include archived narratives",
+            default: false,
+        },
+        limit: {
+            type: "string",
+            description: "Max narratives per brane (0 = unlimited, default: 10)",
+            default: "10",
+        },
+    },
+    async run({ args }) {
+        try {
+            const endpoint = await resolveDaemonEndpoint();
+            warnIfVersionMismatch(endpoint);
+            const query = new URLSearchParams();
+            if (args.archived)
+                query.set("archived", "1");
+            if (args.brane)
+                query.set("brane_ids", args.brane);
+            const qs = query.toString();
+            const [{ narratives }, { branes }] = await Promise.all([
+                daemonRequest(endpoint, `/api/narratives${qs ? `?${qs}` : ""}`),
+                daemonRequest(endpoint, "/api/branes"),
+            ]);
+            console.log(formatNarrativeList(narratives, branes, { limit: parseInt(args.limit, 10) }));
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    },
+});
+/** Group by brane in first-seen order (the API lists newest first, so the
+ *  brane with the newest narrative leads), home brane marked. */
+export function formatNarrativeList(narratives, branes, opts) {
+    if (narratives.length === 0) {
+        return "No narratives. Use `brane spawn <agent>` to start one.";
+    }
+    const homeBraneId = branes.find((b) => b.is_home)?.brane_id;
+    const byBrane = new Map();
+    for (const n of narratives) {
+        let group = byBrane.get(n.brane_id);
+        if (!group) {
+            group = [];
+            byBrane.set(n.brane_id, group);
+        }
+        group.push(n);
+    }
+    const out = [];
+    for (const [braneId, narrs] of byBrane) {
+        const isHome = braneId === homeBraneId;
+        const activeCount = narrs.filter((n) => n.status === "active").length;
+        const label = isHome ? `${braneId} (home)` : braneId;
+        const counts = `${activeCount} active, ${narrs.length} total`;
+        out.push(`\n  ${isHome ? "●" : "○"} ${label}  [${counts}]`);
+        const shown = opts.limit > 0 ? narrs.slice(0, opts.limit) : narrs;
+        for (const n of shown) {
+            const age = timeSince(n.created_at, opts.now);
+            const statusIcon = n.status === "active" ? "●" : "○";
+            const desc = n.summary
+                ? n.summary.length > 50
+                    ? n.summary.slice(0, 47) + "..."
+                    : n.summary
+                : `${n.agent_type}/${n.role}`;
+            out.push(`    ${statusIcon} ${n.id}  ${desc}  ${age}`);
+        }
+        const remaining = narrs.length - shown.length;
+        if (remaining > 0) {
+            out.push(`    ... and ${remaining} more (--limit 0 to show all)`);
+        }
+    }
+    out.push("");
+    return out.join("\n");
+}
+//# sourceMappingURL=list.js.map

package/dist/commands/mcp.js

@@ -0,0 +1,84 @@
+import { defineCommand } from "citty";
+import { openDatabase, getDaemonAddress, getPackageVersion } from "../db/schema.js";
+import { startMcpBridge } from "../mcp/server.js";
+import { connect as netConnect } from "node:net";
+import { readDaemonSocket, resolveCredential } from "../daemon/client.js";
+import { ensureDaemonRunning } from "./daemon.js";
+/** Resolve daemon WebSocket URL, auto-starting daemon if needed */
+async function resolveDaemonUrl() {
+    let db = openDatabase();
+    let info = getDaemonAddress(db);
+    db.close();
+    if (!info) {
+        process.stderr.write("MCP bridge: daemon not running, starting it...\n");
+        try {
+            info = await ensureDaemonRunning();
+        }
+        catch {
+            return null;
+        }
+    }
+    // Check if daemon is running with TLS, and settle what to present: a
+    // spawned agent's own token, or nothing — an unspawned client dials the
+    // daemon's socket as this account, and `welcome` hands it a token.
+    db = openDatabase();
+    const tlsRow = db.prepare("SELECT value FROM meta WHERE key = 'daemon_tls'").get();
+    let token;
+    let socketPath;
+    try {
+        token = resolveCredential();
+        socketPath = readDaemonSocket(db);
+    }
+    finally {
+        db.close();
+    }
+    // Warn on version mismatch between this CLI and the running daemon
+    if (info.version) {
+        const myVersion = getPackageVersion();
+        if (info.version !== myVersion) {
+            process.stderr.write(`MCP bridge: version mismatch — daemon is v${info.version}, this CLI is v${myVersion}\n` +
+                `  Consider: npm i -g brane (and check $PATH priority)\n`);
+        }
+    }
+    const tls = tlsRow?.value === "true";
+    // The socket only if it answers now: the bridge re-resolves on every
+    // reconnect, so a socket that stops answering falls back to TCP next time.
+    const reachable = socketPath && (await socketAnswers(socketPath)) ? socketPath : undefined;
+    if (token === null && !reachable) {
+        // Over TCP a dial with no token is refused, so there is nothing to dial:
+        // the first resolve exits ("daemon not available"), a reconnect retries.
+        process.stderr.write("MCP bridge: the daemon's socket is not answering, and there is no token for TCP\n");
+        return null;
+    }
+    return mcpDialTarget({ port: info.port, tls, token, socketPath: reachable });
+}
+/** Where `brane mcp` dials. Over the daemon's Unix socket when it has one —
+ *  only this account can reach it, and there is no certificate to skip
+ *  verifying — else TCP on loopback. A null token presents none. Pure, for src/test/daemon-socket.test.ts. */
+export function mcpDialTarget(opts) {
+    // No token is only ever meant for the socket, where it acts as this account.
+    const query = opts.token === null ? "/ws/mcp?" : `/ws/mcp?token=${encodeURIComponent(opts.token)}`;
+    if (opts.socketPath)
+        return { url: `ws://localhost${query}`, socketPath: opts.socketPath };
+    return { url: `${opts.tls ? "wss" : "ws"}://localhost:${opts.port}${query}` };
+}
+function socketAnswers(path) {
+    return new Promise((resolve) => {
+        const probe = netConnect(path);
+        probe.once("connect", () => {
+            probe.destroy();
+            resolve(true);
+        });
+        probe.once("error", () => resolve(false));
+    });
+}
+export const mcpCommand = defineCommand({
+    meta: {
+        name: "mcp",
+        description: "Run as MCP stdio server (for agent processes)",
+    },
+    async run() {
+        startMcpBridge(resolveDaemonUrl);
+    },
+});
+//# sourceMappingURL=mcp.js.map