@cluesmith/codev 2.0.0-rc.7 → 2.0.0-rc.71

package/dist/terminal/shepherd-client.js

@@ -0,0 +1,234 @@
+/**
+ * ShepherdClient: Tower's connection to a single shepherd process.
+ *
+ * Connects to a shepherd via Unix socket, performs HELLO/WELCOME handshake,
+ * and provides a typed API for sending/receiving frames. Emits events for
+ * data, exit, replay, and errors.
+ *
+ * Usage:
+ *   const client = new ShepherdClient('/path/to/shepherd.sock');
+ *   const welcome = await client.connect();
+ *   client.on('data', (buf) => { ... });
+ *   client.write('ls\n');
+ *   client.disconnect();
+ */
+import net from 'node:net';
+import { EventEmitter } from 'node:events';
+import { FrameType, PROTOCOL_VERSION, createFrameParser, encodeHello, encodeData, encodeResize, encodeSignal, encodeSpawn, encodePing, encodePong, parseJsonPayload, isKnownFrameType, } from './shepherd-protocol.js';
+export class ShepherdClient extends EventEmitter {
+    socketPath;
+    socket = null;
+    _connected = false;
+    replayData = null;
+    constructor(socketPath) {
+        super();
+        this.socketPath = socketPath;
+    }
+    /**
+     * Emit an 'error' event only if listeners are attached.
+     * Prevents Node.js from throwing on unhandled 'error' events,
+     * which would crash Tower.
+     */
+    safeEmitError(err) {
+        if (this.listenerCount('error') > 0) {
+            this.emit('error', err);
+        }
+    }
+    get connected() {
+        return this._connected;
+    }
+    /**
+     * Connect to the shepherd, perform HELLO/WELCOME handshake.
+     * Resolves with the WelcomeMessage on success.
+     * Rejects on connection error or handshake failure.
+     */
+    connect() {
+        return new Promise((resolve, reject) => {
+            if (this._connected) {
+                reject(new Error('Already connected'));
+                return;
+            }
+            const socket = net.createConnection(this.socketPath);
+            this.socket = socket;
+            let handshakeResolved = false;
+            const parser = createFrameParser();
+            const onError = (err) => {
+                if (!handshakeResolved) {
+                    handshakeResolved = true;
+                    reject(err);
+                }
+                else {
+                    this.safeEmitError(err);
+                }
+                this.cleanup();
+            };
+            socket.on('error', onError);
+            parser.on('error', (err) => {
+                this.safeEmitError(err);
+                this.cleanup();
+            });
+            socket.on('connect', () => {
+                socket.pipe(parser);
+                // Send HELLO to initiate handshake
+                socket.write(encodeHello({ version: PROTOCOL_VERSION }));
+            });
+            socket.on('close', () => {
+                const wasConnected = this._connected;
+                this.cleanup();
+                if (wasConnected) {
+                    this.emit('close');
+                }
+                if (!handshakeResolved) {
+                    handshakeResolved = true;
+                    reject(new Error('Connection closed during handshake'));
+                }
+            });
+            // Buffer frames that arrive before WELCOME (e.g., DATA from PTY output
+            // that the shepherd forwards immediately on connection)
+            const preWelcomeBuffer = [];
+            parser.on('data', (frame) => {
+                if (!handshakeResolved) {
+                    if (frame.type === FrameType.WELCOME) {
+                        try {
+                            const welcome = parseJsonPayload(frame.payload);
+                            // Version mismatch handling per spec:
+                            // - shepherd version < Tower version → disconnect (stale shepherd)
+                            // - shepherd version > Tower version → warn but continue
+                            const shepherdVersion = welcome.version ?? 0;
+                            if (shepherdVersion < PROTOCOL_VERSION) {
+                                handshakeResolved = true;
+                                reject(new Error(`Shepherd protocol version ${shepherdVersion} is older than Tower version ${PROTOCOL_VERSION}`));
+                                this.cleanup();
+                                return;
+                            }
+                            if (shepherdVersion > PROTOCOL_VERSION) {
+                                // Newer shepherd — log warning but continue (forward compatible)
+                                this.emit('version-warning', shepherdVersion, PROTOCOL_VERSION);
+                            }
+                            handshakeResolved = true;
+                            this._connected = true;
+                            // Replay any buffered frames received before WELCOME
+                            for (const buffered of preWelcomeBuffer) {
+                                this.handleFrame(buffered);
+                            }
+                            resolve(welcome);
+                        }
+                        catch {
+                            handshakeResolved = true;
+                            reject(new Error('Invalid WELCOME payload'));
+                            this.cleanup();
+                        }
+                    }
+                    else {
+                        // Buffer non-WELCOME frames for replay after handshake
+                        preWelcomeBuffer.push(frame);
+                    }
+                }
+                else {
+                    // Post-handshake: dispatch frames
+                    this.handleFrame(frame);
+                }
+            });
+        });
+    }
+    handleFrame(frame) {
+        if (!isKnownFrameType(frame.type)) {
+            // Unknown types silently ignored (forward compatibility)
+            return;
+        }
+        switch (frame.type) {
+            case FrameType.DATA:
+                this.emit('data', frame.payload);
+                break;
+            case FrameType.EXIT: {
+                try {
+                    const exit = parseJsonPayload(frame.payload);
+                    this.emit('exit', exit);
+                }
+                catch {
+                    this.safeEmitError(new Error('Invalid EXIT payload'));
+                }
+                break;
+            }
+            case FrameType.REPLAY:
+                this.replayData = frame.payload;
+                this.emit('replay', frame.payload);
+                break;
+            case FrameType.PING:
+                this.socket?.write(encodePong());
+                break;
+            case FrameType.PONG:
+                this.emit('pong');
+                break;
+            case FrameType.WELCOME:
+                // Duplicate WELCOME after handshake — ignore
+                break;
+            default:
+                // Other frame types (HELLO, RESIZE, SIGNAL, SPAWN) are shepherd-bound,
+                // not expected from shepherd → Tower
+                break;
+        }
+    }
+    disconnect() {
+        this.cleanup();
+    }
+    cleanup() {
+        this._connected = false;
+        if (this.socket && !this.socket.destroyed) {
+            this.socket.destroy();
+        }
+        this.socket = null;
+    }
+    write(data) {
+        if (!this._connected || !this.socket)
+            return;
+        this.socket.write(encodeData(data));
+    }
+    resize(cols, rows) {
+        if (!this._connected || !this.socket)
+            return;
+        this.socket.write(encodeResize({ cols, rows }));
+    }
+    signal(sig) {
+        if (!this._connected || !this.socket)
+            return;
+        this.socket.write(encodeSignal({ signal: sig }));
+    }
+    spawn(msg) {
+        if (!this._connected || !this.socket)
+            return;
+        this.socket.write(encodeSpawn(msg));
+    }
+    ping() {
+        if (!this._connected || !this.socket)
+            return;
+        this.socket.write(encodePing());
+    }
+    /** Get the last received replay data, or null if none. */
+    getReplayData() {
+        return this.replayData;
+    }
+    /**
+     * Wait for the REPLAY frame to arrive after connection.
+     * The shepherd sends REPLAY immediately after WELCOME, but they may
+     * arrive in separate reads. Returns the replay data, or empty Buffer
+     * if no REPLAY arrives within the timeout (shepherd had nothing to replay).
+     */
+    waitForReplay(timeoutMs = 500) {
+        if (this.replayData !== null) {
+            return Promise.resolve(this.replayData);
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.removeListener('replay', onReplay);
+                resolve(Buffer.alloc(0));
+            }, timeoutMs);
+            const onReplay = (data) => {
+                clearTimeout(timer);
+                resolve(data);
+            };
+            this.once('replay', onReplay);
+        });
+    }
+}
+//# sourceMappingURL=shepherd-client.js.map

package/dist/terminal/shepherd-client.js.map

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

package/dist/terminal/shepherd-main.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Shepherd main: standalone entry point spawned by Tower as a detached process.
+ *
+ * Usage:
+ *   node shepherd-main.js <json-config>
+ *
+ * Where json-config is a JSON string with:
+ *   { command, args, cwd, env, cols, rows, socketPath }
+ *
+ * On startup:
+ * 1. Creates socket directory with 0700 permissions
+ * 2. Spawns PTY with requested command
+ * 3. Writes { pid, startTime } to stdout as JSON, then closes stdout
+ * 4. Listens on Unix socket at socketPath
+ * 5. Handles SIGTERM gracefully
+ */
+export {};
+//# sourceMappingURL=shepherd-main.d.ts.map

package/dist/terminal/shepherd-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shepherd-main.d.ts","sourceRoot":"","sources":["../../src/terminal/shepherd-main.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;GAeG"}

package/dist/terminal/shepherd-main.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Shepherd main: standalone entry point spawned by Tower as a detached process.
+ *
+ * Usage:
+ *   node shepherd-main.js <json-config>
+ *
+ * Where json-config is a JSON string with:
+ *   { command, args, cwd, env, cols, rows, socketPath }
+ *
+ * On startup:
+ * 1. Creates socket directory with 0700 permissions
+ * 2. Spawns PTY with requested command
+ * 3. Writes { pid, startTime } to stdout as JSON, then closes stdout
+ * 4. Listens on Unix socket at socketPath
+ * 5. Handles SIGTERM gracefully
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { ShepherdProcess } from './shepherd-process.js';
+// createRequire enables importing native/CJS modules (like node-pty) from ESM.
+// The package uses "type": "module", so bare `require()` is not available.
+const require = createRequire(import.meta.url);
+function createRealPty() {
+    let ptyModule = null;
+    let ptyInstance = null;
+    let dataCallback = null;
+    let exitCallback = null;
+    return {
+        spawn(command, args, options) {
+            // Load node-pty at spawn time via createRequire (defined at module level).
+            // node-pty is a native CJS module; createRequire handles ESM→CJS interop.
+            ptyModule = require('node-pty');
+            ptyInstance = ptyModule.spawn(command, args, {
+                name: options.name ?? 'xterm-256color',
+                cols: options.cols,
+                rows: options.rows,
+                cwd: options.cwd,
+                env: options.env,
+            });
+            if (dataCallback) {
+                ptyInstance.onData(dataCallback);
+            }
+            if (exitCallback) {
+                ptyInstance.onExit(exitCallback);
+            }
+        },
+        write(data) {
+            ptyInstance?.write(data);
+        },
+        resize(cols, rows) {
+            ptyInstance?.resize(cols, rows);
+        },
+        kill(signal) {
+            if (ptyInstance) {
+                try {
+                    process.kill(ptyInstance.pid, signal ?? 15);
+                }
+                catch {
+                    // Process already dead
+                }
+            }
+        },
+        onData(callback) {
+            dataCallback = callback;
+            if (ptyInstance) {
+                ptyInstance.onData(callback);
+            }
+        },
+        onExit(callback) {
+            exitCallback = callback;
+            if (ptyInstance) {
+                ptyInstance.onExit(callback);
+            }
+        },
+        get pid() {
+            return ptyInstance?.pid ?? -1;
+        },
+    };
+}
+async function main() {
+    const configJson = process.argv[2];
+    if (!configJson) {
+        process.stderr.write('Usage: shepherd-main.js <json-config>\n');
+        process.exit(1);
+    }
+    let config;
+    try {
+        config = JSON.parse(configJson);
+    }
+    catch {
+        process.stderr.write('Invalid JSON config\n');
+        process.exit(1);
+    }
+    // Ensure socket directory exists with 0700 permissions
+    const socketDir = path.dirname(config.socketPath);
+    fs.mkdirSync(socketDir, { recursive: true, mode: 0o700 });
+    // Remove stale socket file if it exists
+    try {
+        const stat = fs.lstatSync(config.socketPath);
+        if (stat.isSocket()) {
+            fs.unlinkSync(config.socketPath);
+        }
+    }
+    catch {
+        // File doesn't exist — fine
+    }
+    const shepherd = new ShepherdProcess(createRealPty, config.socketPath, config.replayBufferLines ?? 10_000);
+    // Start the shepherd (spawns PTY and listens on socket)
+    await shepherd.start(config.command, config.args, config.cwd, config.env, config.cols, config.rows);
+    // Write PID and start time to stdout, then close stdout
+    const info = JSON.stringify({
+        pid: process.pid,
+        startTime: shepherd.getStartTime(),
+    });
+    process.stdout.write(info, () => {
+        // Close stdout after write completes (Tower reads this, then we detach)
+        try {
+            fs.closeSync(1);
+        }
+        catch {
+            // Already closed or not available
+        }
+    });
+    // Handle SIGTERM: graceful shutdown
+    process.on('SIGTERM', () => {
+        shepherd.shutdown();
+        // Clean up socket file
+        try {
+            fs.unlinkSync(config.socketPath);
+        }
+        catch {
+            // Already gone
+        }
+        process.exit(0);
+    });
+    // When the child process exits and no connection is active, exit the shepherd
+    shepherd.on('exit', () => {
+        // Don't exit immediately — Tower might send a SPAWN frame to restart.
+        // The shepherd stays alive as long as the socket server is running.
+        // If Tower never reconnects, the shepherd will be cleaned up by stale
+        // socket cleanup on next Tower startup.
+    });
+    shepherd.on('error', (err) => {
+        process.stderr.write(`Shepherd error: ${err.message}\n`);
+    });
+}
+main().catch((err) => {
+    process.stderr.write(`Shepherd fatal: ${err.message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=shepherd-main.js.map

package/dist/terminal/shepherd-main.js.map

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

package/dist/terminal/shepherd-process.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ShepherdProcess: the testable core logic of the shepherd daemon.
+ *
+ * Owns a single PTY via the IShepherdPty interface (injected for testability).
+ * Listens on a Unix socket for a single Tower connection. Handles the binary
+ * wire protocol: HELLO/WELCOME handshake, DATA forwarding, RESIZE, SIGNAL,
+ * SPAWN, PING/PONG, and EXIT lifecycle.
+ *
+ * The shepherd accepts only one Tower connection at a time. A new connection
+ * replaces the old one (handles rapid Tower restarts cleanly).
+ */
+import net from 'node:net';
+import { EventEmitter } from 'node:events';
+export interface PtyOptions {
+    name?: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: Record<string, string>;
+}
+export interface IShepherdPty {
+    spawn(command: string, args: string[], options: PtyOptions): void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: number): void;
+    onData(callback: (data: string) => void): void;
+    onExit(callback: (exitInfo: {
+        exitCode: number;
+        signal?: number;
+    }) => void): void;
+    pid: number;
+}
+export declare class ShepherdProcess extends EventEmitter {
+    private readonly ptyFactory;
+    private readonly socketPath;
+    private pty;
+    private server;
+    private currentConnection;
+    private replayBuffer;
+    private cols;
+    private rows;
+    private startTime;
+    private exited;
+    constructor(ptyFactory: () => IShepherdPty, socketPath: string, replayBufferLines?: number);
+    /**
+     * Start the shepherd: spawn the PTY and begin listening on the Unix socket.
+     */
+    start(command: string, args: string[], cwd: string, env: Record<string, string>, cols: number, rows: number): Promise<void>;
+    private spawnPty;
+    private listen;
+    /**
+     * Handle an incoming Tower connection. Only one connection is active at a
+     * time — a new connection closes the previous one.
+     */
+    handleConnection(socket: net.Socket): void;
+    private handleFrame;
+    private handleHello;
+    private handleData;
+    private handleResize;
+    private handleSignal;
+    private handleSpawn;
+    /** Get the current replay buffer data. */
+    getReplayData(): Buffer;
+    /** Get the process start time (epoch ms). */
+    getStartTime(): number;
+    /** Get the current PTY PID. */
+    getPid(): number;
+    /** Whether the child process has exited. */
+    get hasExited(): boolean;
+    /**
+     * Graceful shutdown: kill child process, close socket server, clean up.
+     */
+    shutdown(): void;
+}
+//# sourceMappingURL=shepherd-process.d.ts.map

package/dist/terminal/shepherd-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shepherd-process.d.ts","sourceRoot":"","sources":["../../src/terminal/shepherd-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,GAAG,MAAM,UAAU,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAwB3C,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAClE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC/C,MAAM,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAClF,GAAG,EAAE,MAAM,CAAC;CACb;AAID,qBAAa,eAAgB,SAAQ,YAAY;IAW7C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAX7B,OAAO,CAAC,GAAG,CAA6B;IACxC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,iBAAiB,CAA2B;IACpD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,MAAM,CAAS;gBAGJ,UAAU,EAAE,MAAM,YAAY,EAC9B,UAAU,EAAE,MAAM,EACnC,iBAAiB,GAAE,MAAe;IAMpC;;OAEG;IACG,KAAK,CACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAShB,OAAO,CAAC,QAAQ;IAmDhB,OAAO,CAAC,MAAM;IAwBd;;;OAGG;IACH,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,IAAI;IAiC1C,OAAO,CAAC,WAAW;IAkCnB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,WAAW;IAqBnB,0CAA0C;IAC1C,aAAa,IAAI,MAAM;IAIvB,6CAA6C;IAC7C,YAAY,IAAI,MAAM;IAItB,+BAA+B;IAC/B,MAAM,IAAI,MAAM;IAIhB,4CAA4C;IAC5C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED;;OAEG;IACH,QAAQ,IAAI,IAAI;CAiBjB"}