@2kw/ai 7.3.0-dev.1 → 7.3.0-dev.8

package/dist/bridge/hub.d.ts

@@ -0,0 +1,11 @@
+import type { KeyObject } from "node:crypto";
+import type { BridgeIdentity } from "./store.js";
+/**
+ * One long poll at `{baseUrl}/v1/mcp-relay/hub/poll`, the call that keeps a paired computer
+ * present (#1377, plan P14). The headers are the network relay's (relay/src/relay/hub-client.ts):
+ * a relay JWT for `<issuer>/v1/mcp-relay/hub`, the protocol version and a replica id. It asks for
+ * no work (`calls=0`): S1 only stays reachable. Resolves with the HTTP status; throws on a
+ * transport failure or the 35 s timeout, and a `ClockSkewError` for a 401 a wrong clock caused.
+ */
+export declare function pollHub(identity: BridgeIdentity, key: KeyObject, replicaId: string, signal: AbortSignal): Promise<number>;
+//# sourceMappingURL=hub.d.ts.map

package/dist/bridge/hub.js

@@ -0,0 +1,44 @@
+import { mintRelayJwt } from "../relay-protocol/jws.js";
+import { kidOf, rawPublicKey } from "../relay-protocol/keys.js";
+import { POLL_WAIT_SECONDS, PROTOCOL_VERSION } from "../relay-protocol/wire.js";
+import { BRIDGE_VERSION } from "./inventory.js";
+import { clockSkew } from "./pairing.js";
+/**
+ * One long poll at `{baseUrl}/v1/mcp-relay/hub/poll`, the call that keeps a paired computer
+ * present (#1377, plan P14). The headers are the network relay's (relay/src/relay/hub-client.ts):
+ * a relay JWT for `<issuer>/v1/mcp-relay/hub`, the protocol version and a replica id. It asks for
+ * no work (`calls=0`): S1 only stays reachable. Resolves with the HTTP status; throws on a
+ * transport failure or the 35 s timeout, and a `ClockSkewError` for a 401 a wrong clock caused.
+ */
+export async function pollHub(identity, key, replicaId, signal) {
+    const query = new URLSearchParams({ calls: "0", listen: "0", control: "0", wait: String(POLL_WAIT_SECONDS) });
+    const kid = kidOf(rawPublicKey(key));
+    const audience = `${identity.issuer}/v1/mcp-relay/hub`;
+    // AbortSignal.any needs Node 20; the cli still runs on 18.
+    const timeout = new AbortController();
+    const abort = () => timeout.abort();
+    const timer = setTimeout(abort, (POLL_WAIT_SECONDS + 10) * 1000);
+    signal.addEventListener("abort", abort, { once: true });
+    try {
+        const response = await fetch(`${identity.baseUrl}/v1/mcp-relay/hub/poll?${query}`, {
+            headers: {
+                authorization: `Bearer ${mintRelayJwt(key, kid, identity.relayId, audience, Math.floor(Date.now() / 1000))}`,
+                "mcprelay-protocol": String(PROTOCOL_VERSION),
+                "mcprelay-version": BRIDGE_VERSION,
+                "mcprelay-replica": replicaId,
+            },
+            redirect: "error",
+            signal: timeout.signal,
+        });
+        const skew = response.status === 401 ? clockSkew(response) : null;
+        await response.body?.cancel();
+        if (skew)
+            throw skew;
+        return response.status;
+    }
+    finally {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", abort);
+    }
+}
+//# sourceMappingURL=hub.js.map

package/dist/bridge/inventory.d.ts

@@ -0,0 +1,27 @@
+import type { BridgeConfig, Workspace } from "./toml.js";
+/** What `PUT /v1/local-bridge/inventory` takes (#1377, plan P10). */
+export interface DeviceInventory {
+    bridgeVersion: string;
+    protocolVersion: number;
+    os: string;
+    shell: {
+        path: string;
+        version: string | null;
+    } | null;
+    workspaces: Workspace[];
+    configHash: string;
+}
+export declare const BRIDGE_VERSION: string;
+/**
+ * What redeem takes as `name` and `os`: 1 to 64 characters, none of them a control, format
+ * (bidi, zero-width) or line/paragraph separator, the backend's `[^\p{C}\p{Zl}\p{Zp}]{1,64}`.
+ */
+export declare const LABEL: RegExp;
+/** `value` made into a {@link LABEL}, or `fallback` when nothing is left. */
+export declare function printable(value: string, fallback: string): string;
+export declare function deviceName(): string;
+/** "Windows 11 Pro" on Windows; the kernel name and release elsewhere. */
+export declare function deviceOs(): string;
+export declare function inventoryOf(input: Omit<DeviceInventory, "protocolVersion" | "configHash">): DeviceInventory;
+export declare function collectInventory(config: BridgeConfig): Promise<DeviceInventory>;
+//# sourceMappingURL=inventory.d.ts.map

package/dist/bridge/inventory.js

@@ -0,0 +1,41 @@
+import { createRequire } from "node:module";
+import { hostname, release, type, version } from "node:os";
+import { deviceConfigHash } from "../relay-protocol/pairing.js";
+import { PROTOCOL_VERSION } from "../relay-protocol/wire.js";
+import { bashVersion, findBash } from "./shell.js";
+export const BRIDGE_VERSION = createRequire(import.meta.url)("../../package.json").version;
+/**
+ * What redeem takes as `name` and `os`: 1 to 64 characters, none of them a control, format
+ * (bidi, zero-width) or line/paragraph separator, the backend's `[^\p{C}\p{Zl}\p{Zp}]{1,64}`.
+ */
+export const LABEL = /^[^\p{C}\p{Zl}\p{Zp}]{1,64}$/u;
+/** `value` made into a {@link LABEL}, or `fallback` when nothing is left. */
+export function printable(value, fallback) {
+    // Code points, not UTF-16 units: a cut surrogate pair would itself be a control character.
+    const clean = Array.from(value.replace(/[\p{C}\p{Zl}\p{Zp}]/gu, " ").trim()).slice(0, 64).join("");
+    return clean === "" ? fallback : clean;
+}
+export function deviceName() {
+    return printable(hostname(), "computer");
+}
+/** "Windows 11 Pro" on Windows; the kernel name and release elsewhere. */
+export function deviceOs() {
+    return printable(process.platform === "win32" ? version() : `${type()} ${release()}`, process.platform);
+}
+export function inventoryOf(input) {
+    return {
+        ...input,
+        protocolVersion: PROTOCOL_VERSION,
+        configHash: deviceConfigHash({ shell: input.shell?.path ?? null, workspaces: input.workspaces }),
+    };
+}
+export async function collectInventory(config) {
+    const shellPath = findBash(config.shell);
+    return inventoryOf({
+        bridgeVersion: BRIDGE_VERSION,
+        os: deviceOs(),
+        shell: shellPath === null ? null : { path: shellPath, version: await bashVersion(shellPath) },
+        workspaces: config.workspaces,
+    });
+}
+//# sourceMappingURL=inventory.js.map

package/dist/bridge/pairing.d.ts

@@ -0,0 +1,41 @@
+import type { KeyObject } from "node:crypto";
+import { type Jwk } from "../relay-protocol/keys.js";
+import type { DeviceInventory } from "./inventory.js";
+import type { BridgeIdentity } from "./store.js";
+/** The computer was revoked or is unknown to the backend: final, never retried. */
+export declare class DeviceGoneError extends Error {
+    constructor();
+}
+/** The 401 came from this computer's clock, not from a revocation: nothing is deleted. */
+export declare class ClockSkewError extends Error {
+    readonly offsetSeconds: number;
+    constructor(offsetSeconds: number, then?: string);
+}
+/** For a 401: the clock error when the response's `Date` and this computer's clock differ by more than 30 s. */
+export declare function clockSkew(response: Response, then?: string): ClockSkewError | null;
+export interface Redeemed {
+    pairingId: string;
+    expiresAt: string;
+    issuer: string;
+    fingerprint: string[];
+}
+/**
+ * Redeems a pairing code with a fresh key. Returns the words this key makes, checked against the
+ * backend's: those are the words the member compares with chat.
+ */
+export declare function redeem(baseUrl: string, key: KeyObject, code: string, name: string, os: string): Promise<Redeemed>;
+export type Confirmed = Pick<BridgeIdentity, "relayId" | "organizationId" | "ownerMemberId" | "issuer"> & {
+    jwks: {
+        keys: Jwk[];
+    };
+};
+/**
+ * Asks every 2 s whether the member confirmed the pairing in chat. Resolves with the device's
+ * identity, or null when the pairing expired. A failed request is asked again on the next tick.
+ */
+export declare function awaitConfirmation(baseUrl: string, key: KeyObject, redeemed: Redeemed): Promise<Confirmed | null>;
+/** A relay JWT for the backend's device endpoints. */
+export declare function relayAuthorization(identity: BridgeIdentity, key: KeyObject): string;
+export declare function reportInventory(identity: BridgeIdentity, key: KeyObject, inventory: DeviceInventory): Promise<void>;
+export declare function disconnectDevice(identity: BridgeIdentity, key: KeyObject): Promise<void>;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/bridge/pairing.js

@@ -0,0 +1,158 @@
+import { BackboneApiError } from "../lib/errors.js";
+import { b64url } from "../relay-protocol/b64.js";
+import { mintRelayJwt } from "../relay-protocol/jws.js";
+import { kidOf, rawPublicKey } from "../relay-protocol/keys.js";
+import { fingerprintWords, mintPairingJwt, signPairProof } from "../relay-protocol/pairing.js";
+/**
+ * The bridge's own calls to the backend (#1377, plan P3, P4, P10). None carries an account
+ * credential: redeem is open, the pairing poll signs with the new key, and once paired every call
+ * carries a relay JWT signed by the device key.
+ */
+const POLL_INTERVAL_MS = 2_000;
+/** The computer was revoked or is unknown to the backend: final, never retried. */
+export class DeviceGoneError extends Error {
+    constructor() {
+        super("This computer was disconnected. Run 2kw bridge connect to pair it again.");
+        this.name = "DeviceGoneError";
+    }
+}
+/** The skew the backend allows on a signed token's `iat`/`exp`; past it every signed call gets a 401. */
+const MAX_SKEW_S = 30;
+/** The 401 came from this computer's clock, not from a revocation: nothing is deleted. */
+export class ClockSkewError extends Error {
+    offsetSeconds;
+    constructor(offsetSeconds, then = "Set it to the right time, then run this again.") {
+        super(`This computer's clock is off by ${Math.abs(offsetSeconds)} s and must be corrected. ${then}`);
+        this.offsetSeconds = offsetSeconds;
+        this.name = "ClockSkewError";
+    }
+}
+/** For a 401: the clock error when the response's `Date` and this computer's clock differ by more than 30 s. */
+export function clockSkew(response, then) {
+    const server = Date.parse(response.headers.get("date") ?? "");
+    if (Number.isNaN(server))
+        return null;
+    const offset = Math.round((Date.now() - server) / 1000);
+    return Math.abs(offset) > MAX_SKEW_S ? new ClockSkewError(offset, then) : null;
+}
+const nowSec = () => Math.floor(Date.now() / 1000);
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+async function apiError(response) {
+    let body = {};
+    try {
+        body = (await response.json());
+    }
+    catch {
+        // Not JSON: the status line is all there is.
+    }
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    return new BackboneApiError({
+        status: response.status,
+        error: str(body.errorCode) ?? str(body.title) ?? str(body.error) ?? response.statusText,
+        message: str(body.detail) ?? str(body.message) ?? `HTTP ${response.status}: ${response.statusText}`,
+        timestamp: new Date().toISOString(),
+        errorCode: str(body.errorCode),
+    });
+}
+/**
+ * Redeems a pairing code with a fresh key. Returns the words this key makes, checked against the
+ * backend's: those are the words the member compares with chat.
+ */
+export async function redeem(baseUrl, key, code, name, os) {
+    const raw = rawPublicKey(key);
+    const publicKey = b64url(raw);
+    const kid = kidOf(raw);
+    const proof = signPairProof(key, code, kid, publicKey, name, os);
+    const response = await fetch(`${baseUrl}/v1/local-bridge/pairings/redeem`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ code, publicKey, kid, proof, name, os }),
+        redirect: "error",
+    });
+    if (!response.ok) {
+        const error = await apiError(response);
+        // Someone who saw the code may have used it first; chat would then show their computer.
+        if (error.errorCode === "PAIRING_CODE_INVALID") {
+            error.message += " If chat now asks you to confirm a computer, do not confirm it; start a new pairing in chat.";
+        }
+        throw error;
+    }
+    const redeemed = (await response.json());
+    const words = fingerprintWords(raw);
+    if (!Array.isArray(redeemed.fingerprint) || redeemed.fingerprint.join(" ") !== words.join(" ")) {
+        throw new Error("The server reported a different key for this computer. Nothing was connected.");
+    }
+    return { ...redeemed, fingerprint: words };
+}
+/**
+ * Asks every 2 s whether the member confirmed the pairing in chat. Resolves with the device's
+ * identity, or null when the pairing expired. A failed request is asked again on the next tick.
+ */
+export async function awaitConfirmation(baseUrl, key, redeemed) {
+    const kid = kidOf(rawPublicKey(key));
+    // Past this a failing backend cannot leave the command waiting forever.
+    const deadline = Date.parse(redeemed.expiresAt) + 60_000;
+    for (;;) {
+        if (Date.now() > deadline)
+            return null;
+        let response;
+        try {
+            response = await fetch(`${baseUrl}/v1/local-bridge/pairings/${encodeURIComponent(redeemed.pairingId)}`, {
+                headers: { authorization: `Bearer ${mintPairingJwt(key, kid, redeemed.pairingId, redeemed.issuer, nowSec())}` },
+                redirect: "error",
+            });
+        }
+        catch {
+            response = undefined;
+        }
+        if (response?.ok) {
+            const body = (await response.json());
+            if (body.status === "CONFIRMED") {
+                const { relayId, organizationId, ownerMemberId, issuer, jwks } = body;
+                return { relayId, organizationId, ownerMemberId, issuer, jwks };
+            }
+            if (body.status === "EXPIRED")
+                return null;
+        }
+        else if (response?.status === 401 || response?.status === 404) {
+            const skew = response.status === 401
+                ? clockSkew(response, "Do not confirm this computer in chat; set the clock right, then start a new pairing.")
+                : null;
+            if (skew)
+                throw skew;
+            // A newer pairing replaced this one, or it lapsed: the same outcome for this computer.
+            return null;
+        }
+        else if (response && response.status < 500) {
+            throw await apiError(response);
+        }
+        await sleep(POLL_INTERVAL_MS);
+    }
+}
+/** A relay JWT for the backend's device endpoints. */
+export function relayAuthorization(identity, key) {
+    return `Bearer ${mintRelayJwt(key, kidOf(rawPublicKey(key)), identity.relayId, `${identity.issuer}/v1/mcp-relay`, nowSec())}`;
+}
+async function deviceCall(identity, key, method, path, body) {
+    const response = await fetch(`${identity.baseUrl}${path}`, {
+        method,
+        headers: {
+            authorization: relayAuthorization(identity, key),
+            ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: "error",
+    });
+    if (response.status === 401)
+        throw clockSkew(response) ?? new DeviceGoneError();
+    if (!response.ok)
+        throw await apiError(response);
+    await response.body?.cancel();
+}
+export function reportInventory(identity, key, inventory) {
+    return deviceCall(identity, key, "PUT", "/v1/local-bridge/inventory", inventory);
+}
+export function disconnectDevice(identity, key) {
+    return deviceCall(identity, key, "POST", "/v1/local-bridge/device/disconnect");
+}
+//# sourceMappingURL=pairing.js.map

package/dist/bridge/paths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Where the local bridge keeps its key, identity and bridge.toml (#1377, plan P14):
+ * `%APPDATA%\2kw\bridge` on Windows, `~/.config/2kw/bridge` on Linux and macOS.
+ * `AI_2KW_BRIDGE_DIR` overrides it. Built here because `conf`'s own directories differ.
+ */
+export declare function bridgeDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, home?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/bridge/paths.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+/**
+ * Where the local bridge keeps its key, identity and bridge.toml (#1377, plan P14):
+ * `%APPDATA%\2kw\bridge` on Windows, `~/.config/2kw/bridge` on Linux and macOS.
+ * `AI_2KW_BRIDGE_DIR` overrides it. Built here because `conf`'s own directories differ.
+ */
+export function bridgeDir(env = process.env, platform = process.platform, home = homedir()) {
+    if (env.AI_2KW_BRIDGE_DIR)
+        return env.AI_2KW_BRIDGE_DIR;
+    if (platform === "win32") {
+        return win32.join(env.APPDATA ?? win32.join(home, "AppData", "Roaming"), "2kw", "bridge");
+    }
+    return posix.join(home, ".config", "2kw", "bridge");
+}
+//# sourceMappingURL=paths.js.map

package/dist/bridge/run.d.ts

@@ -0,0 +1,12 @@
+import type { KeyObject } from "node:crypto";
+import { type BridgeIdentity } from "./store.js";
+/**
+ * The foreground loop of `2kw bridge run` (#1377, plan P14). Reports the inventory at start, when
+ * bridge.toml (or the bash it names) changes, and every 10 minutes, and long-polls the hub so the
+ * computer shows as present. A 401 from either is final and rejects with {@link DeviceGoneError}:
+ * unlike the network relay, a device does not wait for its credential to come back. A 401 a wrong
+ * clock caused rejects with {@link ClockSkewError}, and a 426 from either with the update message.
+ * Resolves when `signal` aborts.
+ */
+export declare function runBridge(dir: string, identity: BridgeIdentity, key: KeyObject, signal: AbortSignal): Promise<void>;
+//# sourceMappingURL=run.d.ts.map

package/dist/bridge/run.js

@@ -0,0 +1,134 @@
+import { randomBytes } from "node:crypto";
+import chalk from "chalk";
+import { deviceConfigHash } from "../relay-protocol/pairing.js";
+import { pollHub } from "./hub.js";
+import { collectInventory } from "./inventory.js";
+import { BackboneApiError } from "../lib/errors.js";
+import { ClockSkewError, DeviceGoneError, reportInventory } from "./pairing.js";
+import { findBash } from "./shell.js";
+import { readConfig } from "./store.js";
+const REPORT_EVERY_MS = 10 * 60_000;
+const CONFIG_CHECK_MS = 2_000;
+const MIN_POLL_MS = 1_000;
+const MAX_BACKOFF_MS = 30_000;
+const OUTDATED = "This version of 2kw is too old for this server. Update with npm install -g @2kw/ai";
+function sleep(ms, signal) {
+    return new Promise((done) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            done();
+        };
+        const timer = setTimeout(finish, ms);
+        signal.addEventListener("abort", finish, { once: true });
+    });
+}
+/**
+ * The foreground loop of `2kw bridge run` (#1377, plan P14). Reports the inventory at start, when
+ * bridge.toml (or the bash it names) changes, and every 10 minutes, and long-polls the hub so the
+ * computer shows as present. A 401 from either is final and rejects with {@link DeviceGoneError}:
+ * unlike the network relay, a device does not wait for its credential to come back. A 401 a wrong
+ * clock caused rejects with {@link ClockSkewError}, and a 426 from either with the update message.
+ * Resolves when `signal` aborts.
+ */
+export async function runBridge(dir, identity, key, signal) {
+    const stop = new AbortController();
+    const onAbort = () => stop.abort();
+    signal.addEventListener("abort", onAbort, { once: true });
+    let fatal;
+    // The hash of what was last sent, so an unchanged bridge.toml is not re-sent and a failed send
+    // waits for the 10-minute report instead of retrying every check.
+    let attempted;
+    let reporting;
+    const report = async () => {
+        try {
+            const inventory = await collectInventory(readConfig(dir));
+            attempted = inventory.configHash;
+            await reportInventory(identity, key, inventory);
+        }
+        catch (error) {
+            if (error instanceof DeviceGoneError || error instanceof ClockSkewError) {
+                fatal ??= error;
+                stop.abort();
+            }
+            else if (error instanceof BackboneApiError && error.status === 426) {
+                fatal ??= new Error(OUTDATED);
+                stop.abort();
+            }
+            else {
+                console.error(chalk.yellow(`Could not send this computer's folders: ${String(error)}`));
+            }
+        }
+    };
+    const trigger = () => {
+        reporting ??= report().finally(() => {
+            reporting = undefined;
+        });
+        return reporting;
+    };
+    const timers = [];
+    try {
+        await trigger();
+        timers.push(setInterval(trigger, REPORT_EVERY_MS));
+        timers.push(setInterval(() => {
+            try {
+                const config = readConfig(dir);
+                const hash = deviceConfigHash({ shell: findBash(config.shell), workspaces: config.workspaces });
+                if (hash !== attempted)
+                    void trigger();
+            }
+            catch {
+                // A half-saved bridge.toml: the next check reads it again.
+            }
+        }, CONFIG_CHECK_MS));
+        const replicaId = randomBytes(8).toString("hex");
+        let backoff = MIN_POLL_MS;
+        let toldInUse = false;
+        while (!stop.signal.aborted) {
+            const started = Date.now();
+            let status;
+            try {
+                status = await pollHub(identity, key, replicaId, stop.signal);
+            }
+            catch (error) {
+                if (error instanceof ClockSkewError) {
+                    fatal ??= error;
+                    break;
+                }
+                status = undefined;
+            }
+            if (stop.signal.aborted)
+                break;
+            if (status === 401) {
+                fatal ??= new DeviceGoneError();
+                break;
+            }
+            if (status === 426) {
+                fatal ??= new Error(OUTDATED);
+                break;
+            }
+            if (status === 409 && !toldInUse) {
+                toldInUse = true;
+                console.error(chalk.yellow("Another 2kw bridge run keeps this computer reachable, or one stopped moments ago. This one takes over when it stops."));
+            }
+            if (status === 200 || status === 204) {
+                backoff = MIN_POLL_MS;
+                // A poll that comes back at once is not held by the server; never spin on it.
+                if (Date.now() - started < MIN_POLL_MS)
+                    await sleep(MIN_POLL_MS, stop.signal);
+                continue;
+            }
+            await sleep(backoff, stop.signal);
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+        }
+    }
+    finally {
+        timers.forEach(clearInterval);
+        signal.removeEventListener("abort", onAbort);
+        stop.abort();
+        await reporting;
+    }
+    if (fatal !== undefined)
+        throw fatal;
+}
+//# sourceMappingURL=run.js.map

package/dist/bridge/shell.d.ts

@@ -0,0 +1,17 @@
+/** The seams of the bash lookup: the platform, its environment, and which files exist. */
+export interface ShellLookup {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+    isFile: (path: string) => boolean;
+}
+/**
+ * Finds the POSIX `bash` device commands run in (#1377, plan P15, spec D7). The `shell` from
+ * bridge.toml wins, and when it does not exist nothing else is taken. Otherwise: on Windows, Git
+ * for Windows in its usual places, then next to the `git` on PATH, then a `bash.exe` on PATH; on
+ * Linux and macOS, `bash` on PATH. The WSL launcher in System32 is never taken: it runs commands
+ * in a Linux distribution, not on this computer's files.
+ */
+export declare function findBash(override: string | undefined, lookup?: ShellLookup): string | null;
+/** The first line of `bash --version`, or null when it does not answer within 2 s. */
+export declare function bashVersion(path: string): Promise<string | null>;
+//# sourceMappingURL=shell.d.ts.map

package/dist/bridge/shell.js

@@ -0,0 +1,48 @@
+import { execFile } from "node:child_process";
+import { statSync } from "node:fs";
+import { posix, win32 } from "node:path";
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+const defaultLookup = () => ({ platform: process.platform, env: process.env, isFile });
+/**
+ * Finds the POSIX `bash` device commands run in (#1377, plan P15, spec D7). The `shell` from
+ * bridge.toml wins, and when it does not exist nothing else is taken. Otherwise: on Windows, Git
+ * for Windows in its usual places, then next to the `git` on PATH, then a `bash.exe` on PATH; on
+ * Linux and macOS, `bash` on PATH. The WSL launcher in System32 is never taken: it runs commands
+ * in a Linux distribution, not on this computer's files.
+ */
+export function findBash(override, lookup = defaultLookup()) {
+    if (override !== undefined)
+        return lookup.isFile(override) ? override : null;
+    const { platform, env } = lookup;
+    const path = platform === "win32" ? win32 : posix;
+    const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter((d) => d !== "");
+    const onPath = (file) => dirs.map((d) => path.join(d, file)).filter(lookup.isFile);
+    if (platform !== "win32")
+        return onPath("bash")[0] ?? null;
+    const wsl = path.join(env.SystemRoot ?? "C:\\Windows", "System32", "bash.exe").toLowerCase();
+    const candidates = [
+        env.ProgramFiles && path.join(env.ProgramFiles, "Git", "bin", "bash.exe"),
+        env["ProgramFiles(x86)"] && path.join(env["ProgramFiles(x86)"], "Git", "bin", "bash.exe"),
+        env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, "Programs", "Git", "bin", "bash.exe"),
+        // git.exe sits in <root>\cmd or <root>\bin; bash.exe in <root>\bin.
+        ...onPath("git.exe").map((git) => path.join(path.dirname(path.dirname(git)), "bin", "bash.exe")),
+        ...onPath("bash.exe"),
+    ];
+    return (candidates.find((candidate) => !!candidate && candidate.toLowerCase() !== wsl && lookup.isFile(candidate)) ?? null);
+}
+/** The first line of `bash --version`, or null when it does not answer within 2 s. */
+export function bashVersion(path) {
+    return new Promise((done) => {
+        execFile(path, ["--version"], { timeout: 2_000, windowsHide: true }, (error, stdout) => {
+            done(error ? null : (stdout.split(/\r?\n/)[0]?.trim() ?? null) || null);
+        });
+    });
+}
+//# sourceMappingURL=shell.js.map

package/dist/bridge/store.d.ts

@@ -0,0 +1,33 @@
+import type { KeyObject } from "node:crypto";
+import { CliUsageError } from "../lib/errors.js";
+import type { Jwk } from "../relay-protocol/keys.js";
+import { type BridgeConfig, type Workspace } from "./toml.js";
+/** What a confirmed pairing hands the bridge, plus where it was paired. Never an account token. */
+export interface BridgeIdentity {
+    relayId: string;
+    organizationId: string;
+    ownerMemberId: string;
+    issuer: string;
+    jwks: {
+        keys: Jwk[];
+    };
+    baseUrl: string;
+    name: string;
+    pairedAt: string;
+}
+export declare function writeKey(dir: string, key: KeyObject): void;
+export declare function readKey(dir: string): KeyObject;
+export declare function writeIdentity(dir: string, identity: BridgeIdentity): void;
+/** identity.json is not JSON: `connect` pairs over it, every other command names the file to delete. */
+export declare class UnreadableIdentityError extends CliUsageError {
+    readonly path: string;
+    constructor(path: string);
+}
+/** null when this computer is not connected. */
+export declare function readIdentity(dir: string): BridgeIdentity | null;
+export declare function deleteIdentity(dir: string): void;
+export declare function configPath(dir: string): string;
+export declare function readConfig(dir: string): BridgeConfig;
+export declare function addWorkspace(dir: string, path: string, name?: string): Workspace;
+export declare function removeWorkspace(dir: string, name: string): void;
+//# sourceMappingURL=store.d.ts.map