@kdonev/termscape 0.1.0

package/dist/remote/join-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join-script.js","sourceRoot":"","sources":["../../src/remote/join-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,kFAAkF;AAClF,SAAS,EAAE,CAAC,CAAS;IACnB,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AACzC,CAAC;AAED,uEAAuE;AACvE,MAAM,SAAS,GAAG,sCAAsC,CAAC;AAEzD,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,KAAa;IAC3D,OAAO;kDACyC,MAAM;;;UAG9C,EAAE,CAAC,MAAM,CAAC;aACP,EAAE,CAAC,KAAK,CAAC;;YAEV,EAAE,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqSxB,CAAC;AACF,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,MAAc,EAAE,KAAa;IAChE,OAAO,mDAAmD,MAAM;;;;eAInD,EAAE,CAAC,MAAM,CAAC;eACV,EAAE,CAAC,KAAK,CAAC;;eAET,EAAE,CAAC,SAAS,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2W3B,CAAC;AACF,CAAC"}

package/dist/remote/join.d.ts

@@ -0,0 +1,19 @@
+import type { Hub } from '../hub.js';
+import type { PeerServer } from './peer-serve.js';
+export interface JoinOptions {
+    hub: Hub;
+    peerServer: PeerServer;
+    /** The canvas hub's origin, e.g. http://192.168.1.40:7333 */
+    hubUrl: string;
+    /** Single-use enrollment token; ignored once we hold a durable host token. */
+    joinToken?: string;
+    label?: string;
+    /** Where to keep the durable host token. Defaults to the hub home. */
+    tokenFile?: string;
+    log?: (line: string) => void;
+}
+export interface JoinLink {
+    stop(): void;
+}
+export declare function joinCanvas(opts: JoinOptions): JoinLink;
+//# sourceMappingURL=join.d.ts.map

package/dist/remote/join.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/remote/join.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAGrC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAuBlD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,GAAG,CAAC;IACT,UAAU,EAAE,UAAU,CAAC;IACvB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,IAAI,IAAI,CAAC;CACd;AAkCD,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,CAgJtD"}

package/dist/remote/join.js

@@ -0,0 +1,195 @@
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { hostname, platform, arch, homedir } from 'node:os';
+import { dirname } from 'node:path';
+import { WebSocket } from 'ws';
+import { PEER_SCHEMA_VERSION, PeerResponse } from '../protocol/index.js';
+import { HUB_VERSION } from '../hub.js';
+import { paths } from '../paths.js';
+/**
+ * The joining machine's side of enrollment.
+ *
+ * It dials the canvas hub and then answers its requests — the same role a hub
+ * deployed over SSH plays on its `/peer` endpoint, just over a socket opened
+ * from this end. That is why this file is thin: `peer-serve.ts` does the work,
+ * and all that is left here is getting a socket to hand it and keeping one.
+ *
+ * The enrollment token is spent once. What comes back in `welcome` is a
+ * durable host token written to disk, so every later start — a reboot, a
+ * crash, a dropped link — rejoins silently with no second trip to the
+ * download page.
+ *
+ * The two TERMSCAPE_JOIN* markers below exist for the installer to grep. A hub
+ * that has started is not a hub that has joined, and reporting success on the
+ * former is how you end up telling someone they are connected when the canvas
+ * refused them.
+ */
+const MAX_BACKOFF_MS = 15_000;
+function readHostToken(file) {
+    try {
+        const t = readFileSync(file, 'utf8').trim();
+        return t || null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeHostToken(file, token) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, token, { mode: 0o600 });
+}
+/** Drop a credential the canvas has told us it does not recognise. */
+function clearHostToken(file) {
+    try {
+        rmSync(file, { force: true });
+    }
+    catch {
+        // Nothing here depends on it being gone; the retry ignores it anyway.
+    }
+}
+/** http://host:port -> ws://host:port/peer-in */
+function peerInUrl(hubUrl) {
+    const u = new URL(hubUrl);
+    u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+    u.pathname = '/peer-in';
+    u.search = '';
+    return u.toString();
+}
+export function joinCanvas(opts) {
+    const log = opts.log ?? ((line) => console.log(`[join] ${line}`));
+    /**
+     * A refusal we cannot retry our way out of. The hub was started only to
+     * join, so there is nothing left for it to do; whoever owns the process
+     * listens for this and stops, which also frees the install for a re-run.
+     */
+    const fatal = (message) => {
+        stopped = true;
+        log(`TERMSCAPE_JOIN_FAILED=${message}`);
+        opts.hub.emit('joinFailed', message);
+    };
+    const tokenFile = opts.tokenFile ?? paths.hostTokenFile();
+    const url = peerInUrl(opts.hubUrl);
+    let backoff = 500;
+    let stopped = false;
+    let socket = null;
+    let timer = null;
+    /**
+     * Whether the stored host token has already been tried and rejected. Once
+     * it has, the enrollment key the installer supplied is the only thing left
+     * worth trying, and it is tried exactly once.
+     */
+    let hostTokenSpent = false;
+    function dial() {
+        if (stopped)
+            return;
+        const hostToken = hostTokenSpent ? null : readHostToken(tokenFile);
+        if (!hostToken && !opts.joinToken) {
+            fatal('no enrollment token and no stored host token; nothing to join with');
+            return;
+        }
+        const ws = new WebSocket(url);
+        socket = ws;
+        const usedHostToken = hostToken !== null;
+        // Set once the canvas hub accepts us, so a rejection is not retried
+        // forever as if it were a network blip.
+        let welcomed = false;
+        ws.on('open', () => {
+            const hello = {
+                t: 'hello',
+                token: hostToken ?? opts.joinToken,
+                hubVersion: HUB_VERSION,
+                schemaVersion: PEER_SCHEMA_VERSION,
+                // Only on first contact: after that the host token identifies us and
+                // the canvas hub already has a row describing this machine.
+                ...(hostToken
+                    ? {}
+                    : {
+                        enroll: {
+                            label: opts.label || hostname(),
+                            platform: platform(),
+                            arch: arch(),
+                            homeDir: homedir(),
+                        },
+                    }),
+            };
+            ws.send(JSON.stringify(hello));
+        });
+        const onHandshake = (raw) => {
+            if (welcomed)
+                return;
+            let parsed;
+            try {
+                parsed = PeerResponse.safeParse(JSON.parse(raw.toString('utf8')));
+            }
+            catch {
+                return;
+            }
+            if (!parsed.success)
+                return;
+            const msg = parsed.data;
+            if (msg.t === 'err') {
+                // A stored host token that the canvas no longer knows means this
+                // machine was removed from it — the common case being someone
+                // dropping the host and then re-running the join command. The fresh
+                // key they were just handed is exactly the answer, so use it rather
+                // than failing while holding an unused one.
+                if (usedHostToken && opts.joinToken && !hostTokenSpent) {
+                    hostTokenSpent = true;
+                    clearHostToken(tokenFile);
+                    log('this canvas no longer knows this machine; enrolling again');
+                    ws.close(); // The close handler redials, now without a host token.
+                    return;
+                }
+                // Otherwise a bad token or a version gap, which retrying will not fix.
+                fatal(msg.message);
+                ws.close();
+                return;
+            }
+            if (msg.t !== 'welcome')
+                return;
+            if (msg.schemaVersion !== PEER_SCHEMA_VERSION) {
+                fatal(`schema mismatch: the canvas hub ${msg.hubVersion} speaks v${msg.schemaVersion}, ` +
+                    `this hub speaks v${PEER_SCHEMA_VERSION}. Update whichever is older.`);
+                ws.close();
+                return;
+            }
+            if (msg.hostToken) {
+                writeHostToken(tokenFile, msg.hostToken);
+                log('enrolled; this machine will rejoin on its own from now on');
+            }
+            welcomed = true;
+            backoff = 500;
+            ws.off('message', onHandshake);
+            // Hand the socket to the same code that serves an accepted /peer link.
+            // The canvas hub drives from here; we answer.
+            opts.peerServer.serve(ws, { preAuthed: true });
+            // Machine-readable: the installer waits for this, not for the port.
+            log(`TERMSCAPE_JOINED=1 joined ${opts.hubUrl}`);
+        };
+        ws.on('message', onHandshake);
+        ws.on('error', (err) => {
+            if (!welcomed)
+                log(`cannot reach ${opts.hubUrl}: ${err.message}`);
+        });
+        ws.on('close', () => {
+            socket = null;
+            if (stopped)
+                return;
+            if (welcomed)
+                log('link dropped; reconnecting');
+            timer = setTimeout(dial, backoff);
+            timer.unref?.();
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+        });
+    }
+    dial();
+    return {
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            socket?.close();
+            socket = null;
+        },
+    };
+}
+//# sourceMappingURL=join.js.map

package/dist/remote/join.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"join.js","sourceRoot":"","sources":["../../src/remote/join.ts"],"names":[],"mappings":"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"}

package/dist/remote/lan.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Picking the address another machine can reach us on.
+ *
+ * `--listen lan` exists because the alternative is asking someone to work out
+ * their own IPv4 address before they can attach a second machine, which is
+ * exactly the kind of step that makes a feature go unused.
+ */
+/** First non-internal IPv4 address, preferring real NICs over virtual ones. */
+export declare function lanAddress(): string | null;
+/**
+ * Turn a `--listen` value into a bind address.
+ *
+ * `lan` binds the wildcard rather than the LAN address alone, because a
+ * process can only bind one address and loopback has to keep working: it is
+ * where the browser opens the canvas, and where every agent's generated MCP
+ * config points. Binding the LAN address by itself would take the hub off
+ * 127.0.0.1 and break both. The LAN address is still what gets *advertised* —
+ * see advertisedHost.
+ */
+export declare function resolveBindHost(spec: string): string;
+/** Whether a bind on this address also answers on 127.0.0.1. */
+export declare function coversLoopback(host: string): boolean;
+/** Bracket a bare IPv6 literal so it can sit in a URL. */
+export declare function urlHost(host: string): string;
+/** Whether a bound address is reachable from anywhere but this machine. */
+export declare function isLoopback(host: string): boolean;
+/**
+ * The address to advertise for a given bind. A wildcard bind is reachable on
+ * every interface, so advertise the LAN one; anything else advertises itself.
+ */
+export declare function advertisedHost(host: string): string | null;
+/**
+ * The machine's own name, when it is actually usable as a URL host.
+ *
+ * `http://studio:7777/join` is far easier to carry to another machine than
+ * `http://192.168.88.79:7777/join`, but only if that machine can resolve it —
+ * Windows does it over LLMNR/NetBIOS, macOS and Linux over mDNS, and neither
+ * is guaranteed. So the name is only offered when it resolves *here* to the
+ * very address we bound. That is a proxy, not a promise, which is why the
+ * caller keeps the numeric URL as a stated fallback rather than dropping it.
+ *
+ * Returns null when nothing resolves, and the caller falls back to the IP.
+ */
+export declare function preferredHostname(ip: string, resolve?: (name: string) => Promise<string[]>): Promise<string | null>;
+//# sourceMappingURL=lan.d.ts.map

package/dist/remote/lan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lan.d.ts","sourceRoot":"","sources":["../../src/remote/lan.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,+EAA+E;AAC/E,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAa1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWpD;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED,0DAA0D;AAC1D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAkB,GAC5D,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBxB"}

package/dist/remote/lan.js

@@ -0,0 +1,105 @@
+import { hostname, networkInterfaces } from 'node:os';
+import { lookup } from 'node:dns/promises';
+/**
+ * Picking the address another machine can reach us on.
+ *
+ * `--listen lan` exists because the alternative is asking someone to work out
+ * their own IPv4 address before they can attach a second machine, which is
+ * exactly the kind of step that makes a feature go unused.
+ */
+/** First non-internal IPv4 address, preferring real NICs over virtual ones. */
+export function lanAddress() {
+    const candidates = [];
+    for (const [name, addrs] of Object.entries(networkInterfaces())) {
+        for (const a of addrs ?? []) {
+            if (a.family !== 'IPv4' || a.internal)
+                continue;
+            // Docker bridges, WSL adapters and VM host-only networks are reachable
+            // from almost nothing, so they lose to a real interface.
+            const virtual = /^(docker|br-|veth|vEthernet|virbr|utun|tailscale)/i.test(name);
+            if (virtual)
+                candidates.push(a.address);
+            else
+                candidates.unshift(a.address);
+        }
+    }
+    return candidates[0] ?? null;
+}
+/**
+ * Turn a `--listen` value into a bind address.
+ *
+ * `lan` binds the wildcard rather than the LAN address alone, because a
+ * process can only bind one address and loopback has to keep working: it is
+ * where the browser opens the canvas, and where every agent's generated MCP
+ * config points. Binding the LAN address by itself would take the hub off
+ * 127.0.0.1 and break both. The LAN address is still what gets *advertised* —
+ * see advertisedHost.
+ */
+export function resolveBindHost(spec) {
+    if (spec === 'lan') {
+        if (!lanAddress()) {
+            throw new Error('--listen lan: no non-loopback IPv4 address on this machine. ' +
+                'Pass an explicit address instead.');
+        }
+        return '0.0.0.0';
+    }
+    return spec;
+}
+/** Whether a bind on this address also answers on 127.0.0.1. */
+export function coversLoopback(host) {
+    return host === '0.0.0.0' || host === '::' || isLoopback(host);
+}
+/** Bracket a bare IPv6 literal so it can sit in a URL. */
+export function urlHost(host) {
+    return host.includes(':') ? `[${host}]` : host;
+}
+/** Whether a bound address is reachable from anywhere but this machine. */
+export function isLoopback(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}
+/**
+ * The address to advertise for a given bind. A wildcard bind is reachable on
+ * every interface, so advertise the LAN one; anything else advertises itself.
+ */
+export function advertisedHost(host) {
+    if (host === '0.0.0.0' || host === '::')
+        return lanAddress();
+    if (isLoopback(host))
+        return null;
+    return host.includes(':') ? `[${host}]` : host;
+}
+/**
+ * The machine's own name, when it is actually usable as a URL host.
+ *
+ * `http://studio:7777/join` is far easier to carry to another machine than
+ * `http://192.168.88.79:7777/join`, but only if that machine can resolve it —
+ * Windows does it over LLMNR/NetBIOS, macOS and Linux over mDNS, and neither
+ * is guaranteed. So the name is only offered when it resolves *here* to the
+ * very address we bound. That is a proxy, not a promise, which is why the
+ * caller keeps the numeric URL as a stated fallback rather than dropping it.
+ *
+ * Returns null when nothing resolves, and the caller falls back to the IP.
+ */
+export async function preferredHostname(ip, resolve = defaultResolve) {
+    const name = hostname().trim();
+    if (!name || isLoopback(name))
+        return null;
+    // Plain name first: a bare host is nicer to type than one with a suffix.
+    // `.local` is the mDNS form, which is what a Mac or a Linux box will answer.
+    const candidates = name.endsWith('.local') ? [name] : [name, `${name}.local`];
+    for (const candidate of candidates) {
+        try {
+            if ((await resolve(candidate)).includes(ip))
+                return candidate;
+        }
+        catch {
+            // Does not resolve here; try the next shape.
+        }
+    }
+    return null;
+}
+async function defaultResolve(name) {
+    const found = await lookup(name, { all: true, family: 4 });
+    return found.map((a) => a.address);
+}
+//# sourceMappingURL=lan.js.map

package/dist/remote/lan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lan.js","sourceRoot":"","sources":["../../src/remote/lan.ts"],"names":[],"mappings":"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"}

package/dist/remote/peer-serve.d.ts

@@ -0,0 +1,27 @@
+import { type PeerAgent, type PeerRelayAsk } from '../protocol/index.js';
+import type { WebSocket } from 'ws';
+import type { Hub } from '../hub.js';
+/**
+ * The link back to the canvas, as the rest of this hub needs it. Separated
+ * from the serving machinery because a hub that owns a canvas has no uplink at
+ * all, and the difference should be a null check rather than a special case.
+ */
+export interface Uplink {
+    /** True while a canvas is attached to this hub. */
+    readonly attached: boolean;
+    /** Agents the canvas has told us about. Never this hub's own. */
+    agents(): PeerAgent[];
+    /** Ask the canvas to act on an address we cannot resolve ourselves. */
+    ask<T>(ask: PeerRelayAsk): Promise<T>;
+}
+export interface PeerServer extends Uplink {
+    /** Wire one accepted or dialled socket into this hub. */
+    serve(socket: WebSocket, opts?: {
+        preAuthed?: boolean;
+    }): void;
+    /** Number of peers currently attached. */
+    readonly size: number;
+    closeAll(): void;
+}
+export declare function createPeerServer(hub: Hub, clientToken: string): PeerServer;
+//# sourceMappingURL=peer-serve.d.ts.map

package/dist/remote/peer-serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer-serve.d.ts","sourceRoot":"","sources":["../../src/remote/peer-serve.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,YAAY,EAGlB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAuBrC;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,iEAAiE;IACjE,MAAM,IAAI,SAAS,EAAE,CAAC;IACtB,uEAAuE;IACvE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,UAAW,SAAQ,MAAM;IACxC,yDAAyD;IACzD,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC/D,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAgQ1E"}