almostnode 0.2.6 → 0.2.8

package/src/shims/http.ts

@@ -6,6 +6,13 @@
 import { EventEmitter, type EventListener } from './events';
 import { Readable, Writable, Buffer } from './stream';
 import { Socket, Server as NetServer, AddressInfo } from './net';
+import { createHash } from './crypto';
+
+// Save the browser's native WebSocket at module load time, BEFORE any CLI bundle
+// can overwrite it (e.g. Convex CLI does `globalThis.WebSocket = bundledWs`).
+// This ensures our WebSocket bridge always uses the real browser implementation.
+const _BrowserWebSocket: typeof globalThis.WebSocket | null =
+  typeof globalThis.WebSocket === 'function' ? globalThis.WebSocket : null;
 
 export type RequestListener = (req: IncomingMessage, res: ServerResponse) => void;
 
@@ -14,6 +21,7 @@ export interface RequestOptions {
   path?: string;
   headers?: Record<string, string | string[]>;
   hostname?: string;
+  host?: string;
   port?: number;
 }
 
@@ -604,13 +612,29 @@ export class ClientRequest extends Writable {
     if (this._aborted) return;
 
     try {
-      // Build URL
+      // Build URL — Node.js supports both `hostname` and `host` (host may include port)
       const protocol = this._protocol === 'https' ? 'https:' : 'http:';
-      const hostname = this._options.hostname || 'localhost';
-      const port = this._options.port ? `:${this._options.port}` : '';
+      let hostname = this._options.hostname || '';
+      let port = this._options.port ? `:${this._options.port}` : '';
+      if (!hostname && this._options.host) {
+        // host can be "domain.com" or "domain.com:8080"
+        const hostParts = this._options.host.split(':');
+        hostname = hostParts[0];
+        if (!port && hostParts[1]) {
+          port = `:${hostParts[1]}`;
+        }
+      }
+      if (!hostname) hostname = 'localhost';
       const path = this._options.path || '/';
       const url = `${protocol}//${hostname}${port}${path}`;
 
+      // WebSocket upgrade requests can't use fetch() — browsers strip
+      // Connection/Upgrade headers. Bridge to the browser's native WebSocket.
+      if (this.headers['upgrade']?.toLowerCase() === 'websocket') {
+        this._handleWebSocketUpgrade(url);
+        return;
+      }
+
       // Use CORS proxy if configured
       const corsProxy = getCorsProxy();
       const fetchUrl = corsProxy
@@ -691,6 +715,181 @@ export class ClientRequest extends Writable {
 
     return msg;
   }
+
+  /**
+   * Bridge a WebSocket upgrade request to the browser's native WebSocket.
+   *
+   * The bundled ws library (inside the Convex CLI) creates WebSocket connections
+   * via http.request() with Upgrade headers. It expects frame-level I/O on the
+   * socket from the 'upgrade' event. This method bridges between:
+   *   - ws library ↔ frame-level I/O on a mock Socket
+   *   - browser native WebSocket ↔ message-level I/O
+   */
+  private _handleWebSocketUpgrade(url: string): void {
+    // Convert http(s):// to ws(s)://
+    const wsUrl = url.replace(/^https:/, 'wss:').replace(/^http:/, 'ws:');
+
+    // Get Sec-WebSocket-Key from request headers (sent by ws library)
+    const wsKey = this.headers['sec-websocket-key'] || '';
+
+    // Use the saved browser WebSocket (captured at module load time before CLI overrides)
+    const NativeWS = _BrowserWebSocket;
+
+    if (!NativeWS) {
+      // No native WebSocket (test env / Node.js) — emit TypeError like fetch would
+      setTimeout(() => {
+        this.emit('error', new TypeError('Failed to fetch'));
+      }, 0);
+      return;
+    }
+
+    // Compute Sec-WebSocket-Accept using the same hash as the ws library.
+    // The ws library (bundled in the Convex CLI) uses require("crypto") which
+    // resolves to our crypto shim's createHash (syncHash). We must use the same
+    // GUID as the bundled ws@8.18.0 (which differs from the standard RFC 6455 GUID).
+    const GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+    const acceptValue = createHash('sha1')
+      .update(wsKey + GUID)
+      .digest('base64') as string;
+
+    let nativeWs: globalThis.WebSocket;
+    try {
+      nativeWs = new NativeWS(wsUrl);
+      nativeWs.binaryType = 'arraybuffer';
+    } catch (e) {
+      setTimeout(() => {
+        this.emit('error', e instanceof Error ? e : new Error(String(e)));
+      }, 0);
+      return;
+    }
+
+    // Create mock socket for the ws library's frame-level I/O
+    const socket = new Socket();
+    // ws library calls cork/uncork for batching — add as no-ops if missing
+    if (typeof (socket as any).cork !== 'function') (socket as any).cork = () => {};
+    if (typeof (socket as any).uncork !== 'function') (socket as any).uncork = () => {};
+    // ws library checks _readableState and _writableState on socket close
+    (socket as any)._readableState = { endEmitted: false };
+    (socket as any)._writableState = { finished: false, errorEmitted: false };
+
+    // Buffer for partial frame writes from ws library
+    let writeBuffer = new Uint8Array(0);
+
+    // Override socket.write to intercept outgoing frames from ws library
+    socket.write = ((
+      chunk: Uint8Array | string,
+      encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
+      callback?: (error?: Error | null) => void
+    ): boolean => {
+      const data = typeof chunk === 'string' ? Buffer.from(chunk) : new Uint8Array(chunk);
+      const cb = typeof encodingOrCallback === 'function' ? encodingOrCallback : callback;
+
+      // Append to write buffer
+      const newBuf = new Uint8Array(writeBuffer.length + data.length);
+      newBuf.set(writeBuffer, 0);
+      newBuf.set(data, writeBuffer.length);
+      writeBuffer = newBuf;
+
+      // Parse and forward complete frames
+      while (writeBuffer.length >= 2) {
+        const parsed = _parseWsFrame(writeBuffer);
+        if (!parsed) break; // incomplete frame — wait for more data
+
+        const { opcode, payload, totalLength } = parsed;
+        writeBuffer = writeBuffer.slice(totalLength);
+
+        if (nativeWs.readyState !== NativeWS.OPEN) continue;
+
+        if (opcode === 0x08) {
+          // Close frame
+          nativeWs.close();
+        } else if (opcode === 0x09) {
+          // Ping — respond with pong (shouldn't happen from client but handle it)
+          nativeWs.send(payload);
+        } else if (opcode === 0x0A) {
+          // Pong — ignore
+        } else if (opcode === 0x01) {
+          // Text frame
+          const text = new TextDecoder().decode(payload);
+          nativeWs.send(text);
+        } else if (opcode === 0x02) {
+          // Binary frame
+          nativeWs.send(payload);
+        }
+      }
+
+      if (cb) queueMicrotask(() => cb(null));
+      return true;
+    }) as any;
+
+    nativeWs.onopen = () => {
+      // Create HTTP 101 response
+      const response = new IncomingMessage(socket);
+      response.statusCode = 101;
+      response.statusMessage = 'Switching Protocols';
+      response.headers = {
+        'upgrade': 'websocket',
+        'connection': 'Upgrade',
+        'sec-websocket-accept': acceptValue,
+      };
+      // Mark as complete so ws library doesn't wait for body
+      response.complete = true;
+      response.push(null);
+
+      // Emit upgrade event — ws library listens for this
+      this.emit('upgrade', response, socket, Buffer.alloc(0));
+    };
+
+    nativeWs.onmessage = (event: MessageEvent) => {
+      // Create unmasked WebSocket frame and push to mock socket
+      let payload: Uint8Array;
+      let opcode: number;
+
+      if (typeof event.data === 'string') {
+        payload = new TextEncoder().encode(event.data);
+        opcode = 0x01; // text
+      } else if (event.data instanceof ArrayBuffer) {
+        payload = new Uint8Array(event.data);
+        opcode = 0x02; // binary
+      } else {
+        return;
+      }
+
+      const frame = _createWsFrame(opcode, payload, false); // unmasked (server → client)
+      socket._receiveData(Buffer.from(frame));
+    };
+
+    nativeWs.onclose = (event: CloseEvent) => {
+      // Send close frame to ws library
+      const code = event.code || 1000;
+      const closePayload = new Uint8Array(2);
+      closePayload[0] = (code >> 8) & 0xFF;
+      closePayload[1] = code & 0xFF;
+      const frame = _createWsFrame(0x08, closePayload, false);
+      socket._receiveData(Buffer.from(frame));
+
+      setTimeout(() => {
+        (socket as any)._readableState.endEmitted = true;
+        socket._receiveEnd();
+        socket.emit('close', false);
+      }, 10);
+    };
+
+    nativeWs.onerror = () => {
+      socket.emit('error', new Error('WebSocket connection error'));
+      socket.destroy();
+    };
+
+    // Clean up native WS when socket is destroyed
+    const origDestroy = socket.destroy.bind(socket);
+    socket.destroy = ((error?: Error): Socket => {
+      if (nativeWs.readyState === NativeWS.OPEN || nativeWs.readyState === NativeWS.CONNECTING) {
+        nativeWs.close();
+      }
+      return origDestroy(error);
+    }) as any;
+  }
+
 }
 
 /**
@@ -884,6 +1083,111 @@ export class Agent extends EventEmitter {
 // Global agent instance
 export const globalAgent = new Agent();
 
+/**
+ * Parse a WebSocket frame from raw bytes.
+ * Returns null if the buffer doesn't contain a complete frame.
+ */
+export function _parseWsFrame(data: Uint8Array): {
+  opcode: number;
+  payload: Uint8Array;
+  totalLength: number;
+} | null {
+  if (data.length < 2) return null;
+
+  const opcode = data[0] & 0x0F;
+  const masked = (data[1] & 0x80) !== 0;
+  let payloadLength = data[1] & 0x7F;
+  let offset = 2;
+
+  if (payloadLength === 126) {
+    if (data.length < 4) return null;
+    payloadLength = (data[2] << 8) | data[3];
+    offset = 4;
+  } else if (payloadLength === 127) {
+    if (data.length < 10) return null;
+    // Use lower 32 bits (sufficient for WebSocket messages)
+    payloadLength = (data[6] << 24) | (data[7] << 16) | (data[8] << 8) | data[9];
+    offset = 10;
+  }
+
+  if (masked) {
+    if (data.length < offset + 4 + payloadLength) return null;
+    const maskKey = data.slice(offset, offset + 4);
+    offset += 4;
+
+    const payload = new Uint8Array(payloadLength);
+    for (let i = 0; i < payloadLength; i++) {
+      payload[i] = data[offset + i] ^ maskKey[i % 4];
+    }
+
+    return { opcode, payload, totalLength: offset + payloadLength };
+  } else {
+    if (data.length < offset + payloadLength) return null;
+    const payload = data.slice(offset, offset + payloadLength);
+    return { opcode, payload, totalLength: offset + payloadLength };
+  }
+}
+
+/**
+ * Create a WebSocket frame.
+ * @param opcode - Frame opcode (0x01=text, 0x02=binary, 0x08=close, 0x09=ping, 0x0A=pong)
+ * @param payload - Frame payload
+ * @param masked - Whether to mask the payload (client→server frames are masked)
+ */
+export function _createWsFrame(opcode: number, payload: Uint8Array, masked: boolean): Uint8Array {
+  const length = payload.length;
+  let headerSize = 2;
+
+  if (length > 125 && length <= 65535) {
+    headerSize += 2;
+  } else if (length > 65535) {
+    headerSize += 8;
+  }
+
+  if (masked) {
+    headerSize += 4;
+  }
+
+  const frame = new Uint8Array(headerSize + length);
+  frame[0] = 0x80 | opcode; // FIN + opcode
+
+  let offset = 2;
+  if (length <= 125) {
+    frame[1] = (masked ? 0x80 : 0) | length;
+  } else if (length <= 65535) {
+    frame[1] = (masked ? 0x80 : 0) | 126;
+    frame[2] = (length >> 8) & 0xFF;
+    frame[3] = length & 0xFF;
+    offset = 4;
+  } else {
+    frame[1] = (masked ? 0x80 : 0) | 127;
+    frame[2] = 0; frame[3] = 0; frame[4] = 0; frame[5] = 0;
+    frame[6] = (length >> 24) & 0xFF;
+    frame[7] = (length >> 16) & 0xFF;
+    frame[8] = (length >> 8) & 0xFF;
+    frame[9] = length & 0xFF;
+    offset = 10;
+  }
+
+  if (masked) {
+    const maskKey = new Uint8Array(4);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+      crypto.getRandomValues(maskKey);
+    } else {
+      for (let i = 0; i < 4; i++) maskKey[i] = Math.floor(Math.random() * 256);
+    }
+    frame.set(maskKey, offset);
+    offset += 4;
+    for (let i = 0; i < length; i++) {
+      frame[offset + i] = payload[i] ^ maskKey[i % 4];
+    }
+  } else {
+    frame.set(payload, offset);
+  }
+
+  return frame;
+}
+
 export default {
   Server,
   IncomingMessage,
@@ -901,4 +1205,6 @@ export default {
   _createClientRequest,
   Agent,
   globalAgent,
+  _parseWsFrame,
+  _createWsFrame,
 };

package/src/shims/path.ts

@@ -33,20 +33,9 @@ export function normalize(path: string): string {
   return result || '.';
 }
 
-// Track join calls to debug infinite recursion
-let joinCallCount = 0;
-
 export function join(...paths: string[]): string {
   if (paths.length === 0) return '.';
-  const result = normalize(paths.filter(Boolean).join('/'));
-  // Debug: Log _generated path joins
-  if (paths.some(p => p && p.includes('_generated'))) {
-    joinCallCount++;
-    if (joinCallCount <= 20) {
-      console.log(`[path.join] (${paths.join(', ')}) -> ${result}`);
-    }
-  }
-  return result;
+  return normalize(paths.filter(Boolean).join('/'));
 }
 
 export function resolve(...paths: string[]): string {
@@ -59,7 +48,11 @@ export function resolve(...paths: string[]): string {
   }
 
   if (!resolvedPath.startsWith('/')) {
-    resolvedPath = '/' + resolvedPath;
+    // Use process.cwd() if available, matching Node.js behavior
+    const cwd = typeof globalThis !== 'undefined' && globalThis.process && typeof globalThis.process.cwd === 'function'
+      ? globalThis.process.cwd()
+      : '/';
+    resolvedPath = cwd + (resolvedPath ? '/' + resolvedPath : '');
   }
 
   return normalize(resolvedPath);

package/src/shims/stream.ts

@@ -4,6 +4,10 @@
  */
 
 import { EventEmitter } from './events';
+import { uint8ToBase64, uint8ToHex, uint8ToBinaryString } from '../utils/binary-encoding';
+
+const _encoder = new TextEncoder();
+const _decoder = new TextDecoder('utf-8');
 
 export class Readable extends EventEmitter {
   private _buffer: Uint8Array[] = [];
@@ -547,8 +551,7 @@ class BufferPolyfill extends Uint8Array {
       }
 
       // Default: utf8
-      const encoder = new TextEncoder();
-      const bytes = encoder.encode(data);
+      const bytes = _encoder.encode(data);
       return new BufferPolyfill(bytes);
     }
     if (data instanceof ArrayBuffer) {
@@ -602,47 +605,30 @@ class BufferPolyfill extends Uint8Array {
     if (enc === 'hex') {
       return string.length / 2;
     }
-    return new TextEncoder().encode(string).length;
+    return _encoder.encode(string).length;
   }
 
   toString(encoding: BufferEncoding = 'utf8'): string {
     const enc = (encoding || 'utf8').toLowerCase();
 
     if (enc === 'base64') {
-      let binary = '';
-      for (let i = 0; i < this.length; i++) {
-        binary += String.fromCharCode(this[i]);
-      }
-      return btoa(binary);
+      return uint8ToBase64(this);
     }
 
     if (enc === 'base64url') {
-      let binary = '';
-      for (let i = 0; i < this.length; i++) {
-        binary += String.fromCharCode(this[i]);
-      }
-      return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+      return uint8ToBase64(this).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
     }
 
     if (enc === 'hex') {
-      let hex = '';
-      for (let i = 0; i < this.length; i++) {
-        hex += this[i].toString(16).padStart(2, '0');
-      }
-      return hex;
+      return uint8ToHex(this);
     }
 
     if (enc === 'latin1' || enc === 'binary') {
-      let str = '';
-      for (let i = 0; i < this.length; i++) {
-        str += String.fromCharCode(this[i]);
-      }
-      return str;
+      return uint8ToBinaryString(this);
     }
 
     // Default: utf8
-    const decoder = new TextDecoder('utf-8');
-    return decoder.decode(this);
+    return _decoder.decode(this);
   }
 
   slice(start?: number, end?: number): BufferPolyfill {
@@ -654,7 +640,7 @@ class BufferPolyfill extends Uint8Array {
   }
 
   write(string: string, offset?: number): number {
-    const bytes = new TextEncoder().encode(string);
+    const bytes = _encoder.encode(string);
     this.set(bytes, offset || 0);
     return bytes.length;
   }

package/src/shims/vfs-adapter.ts

@@ -14,6 +14,9 @@ import type {
 } from 'just-bash';
 import type { VirtualFS } from '../virtual-fs';
 import { createNodeError } from '../virtual-fs';
+import { uint8ToBinaryString } from '../utils/binary-encoding';
+
+const _decoder = new TextDecoder();
 
 // Local types for just-bash interface compatibility
 // These are not exported from just-bash main entry point
@@ -53,7 +56,7 @@ export class VirtualFSAdapter implements IFileSystem {
     // For binary/latin1 encoding, convert each byte to a character
     if (encoding === 'binary' || encoding === 'latin1') {
       const buffer = this.vfs.readFileSync(path);
-      return String.fromCharCode(...buffer);
+      return uint8ToBinaryString(buffer);
     }
 
     // For other encodings, fall back to utf8
@@ -93,7 +96,7 @@ export class VirtualFSAdapter implements IFileSystem {
       // File doesn't exist, start with empty content
     }
     const newContent =
-      typeof content === 'string' ? content : new TextDecoder().decode(content);
+      typeof content === 'string' ? content : _decoder.decode(content);
     this.vfs.writeFileSync(path, existing + newContent);
   }
 

package/src/shims/ws.ts

@@ -59,6 +59,7 @@ export class WebSocket extends EventEmitter {
 
   private _id: string;
   private _server: WebSocketServer | null = null;
+  private _nativeWs: globalThis.WebSocket | null = null;
 
   // Event handler properties
   onopen: ((event: Event) => void) | null = null;
@@ -88,7 +89,15 @@ export class WebSocket extends EventEmitter {
       return;
     }
 
-    // If no BroadcastChannel, act as if connected
+    // For external WebSocket connections, use the browser's native WebSocket.
+    // This allows libraries like the Convex CLI (which require('ws')) to
+    // communicate with real remote servers.
+    if (this.url.startsWith('ws://') || this.url.startsWith('wss://')) {
+      this._connectNative();
+      return;
+    }
+
+    // For all other URLs, use BroadcastChannel (internal Vite HMR)
     if (!messageChannel) {
       setTimeout(() => {
         this.readyState = WebSocket.OPEN;
@@ -158,11 +167,75 @@ export class WebSocket extends EventEmitter {
     }, 100);
   }
 
+  private _connectNative(): void {
+    // Check that the browser's native WebSocket is available and is not our own shim
+    const NativeWS = typeof globalThis.WebSocket === 'function' && globalThis.WebSocket !== (WebSocket as any)
+      ? globalThis.WebSocket
+      : null;
+
+    if (!NativeWS) {
+      // No native WebSocket (test env, Node.js, etc.) — act as if connected
+      setTimeout(() => {
+        this.readyState = WebSocket.OPEN;
+        this.emit('open');
+        if (this.onopen) this.onopen(new Event('open'));
+      }, 0);
+      return;
+    }
+
+    try {
+      this._nativeWs = new NativeWS(this.url);
+      this._nativeWs.binaryType = this.binaryType === 'arraybuffer' ? 'arraybuffer' : 'blob';
+    } catch {
+      this.readyState = WebSocket.CLOSED;
+      const errorEvent = new Event('error');
+      this.emit('error', errorEvent);
+      if (this.onerror) this.onerror(errorEvent);
+      return;
+    }
+
+    this._nativeWs.onopen = () => {
+      this.readyState = WebSocket.OPEN;
+      this.emit('open');
+      if (this.onopen) this.onopen(new Event('open'));
+    };
+
+    this._nativeWs.onmessage = (event: globalThis.MessageEvent) => {
+      const msgEvent = new MessageEventPolyfill('message', { data: event.data });
+      this.emit('message', msgEvent);
+      if (this.onmessage) this.onmessage(msgEvent as unknown as MessageEvent);
+    };
+
+    this._nativeWs.onclose = (event: globalThis.CloseEvent) => {
+      this.readyState = WebSocket.CLOSED;
+      this._nativeWs = null;
+      const closeEvent = new CloseEventPolyfill('close', {
+        code: event.code,
+        reason: event.reason,
+        wasClean: event.wasClean,
+      });
+      this.emit('close', closeEvent);
+      if (this.onclose) this.onclose(closeEvent as unknown as CloseEvent);
+    };
+
+    this._nativeWs.onerror = () => {
+      const errorEvent = new Event('error');
+      this.emit('error', errorEvent);
+      if (this.onerror) this.onerror(errorEvent);
+    };
+  }
+
   send(data: string | ArrayBuffer | Uint8Array): void {
     if (this.readyState !== WebSocket.OPEN) {
       throw new Error('WebSocket is not open');
     }
 
+    // If connected to native WebSocket (external server)
+    if (this._nativeWs) {
+      this._nativeWs.send(data);
+      return;
+    }
+
     // If connected to internal server
     if (this._server) {
       this._server._handleClientMessage(this, data);
@@ -187,6 +260,12 @@ export class WebSocket extends EventEmitter {
 
     this.readyState = WebSocket.CLOSING;
 
+    // If connected to native WebSocket, close it (onclose handler emits events)
+    if (this._nativeWs) {
+      this._nativeWs.close(code, reason);
+      return;
+    }
+
     if (messageChannel) {
       messageChannel.postMessage({
         type: 'disconnect',
@@ -218,7 +297,18 @@ export class WebSocket extends EventEmitter {
   }
 
   terminate(): void {
-    this.close(1006, 'Connection terminated');
+    if (this._nativeWs) {
+      this._nativeWs.close();
+      this._nativeWs = null;
+    }
+    this.readyState = WebSocket.CLOSED;
+    const closeEvent = new CloseEventPolyfill('close', {
+      code: 1006,
+      reason: 'Connection terminated',
+      wasClean: false,
+    });
+    this.emit('close', closeEvent);
+    if (this.onclose) this.onclose(closeEvent as unknown as CloseEvent);
   }
 
   // For internal server use

package/src/utils/binary-encoding.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared binary encoding utilities.
+ * Replaces O(n²) string concatenation patterns used throughout the codebase.
+ */
+
+const CHUNK = 8192;
+
+/** Convert Uint8Array to base64 string */
+export function uint8ToBase64(bytes: Uint8Array): string {
+  const parts: string[] = [];
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    parts.push(String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK))));
+  }
+  return btoa(parts.join(''));
+}
+
+/** Convert base64 string to Uint8Array */
+export function base64ToUint8(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+/** Convert Uint8Array to hex string */
+export function uint8ToHex(bytes: Uint8Array): string {
+  const hex = new Array(bytes.length);
+  for (let i = 0; i < bytes.length; i++) {
+    hex[i] = bytes[i].toString(16).padStart(2, '0');
+  }
+  return hex.join('');
+}
+
+/** Convert Uint8Array to binary (latin1) string */
+export function uint8ToBinaryString(bytes: Uint8Array): string {
+  const parts: string[] = [];
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    parts.push(String.fromCharCode.apply(null, Array.from(bytes.subarray(i, i + CHUNK))));
+  }
+  return parts.join('');
+}