remodex-windows-fix 1.0.2

package/README.md

@@ -0,0 +1,183 @@
+# remodex-windows-fix
+
+Windows-friendly mirror of `remodex` with a launcher fix for `codex app-server`.
+
+## What Changed
+
+- Fixes Windows startup when `remodex up` tries to spawn `codex` and fails with `spawn codex ENOENT`.
+- Prefers `codex.cmd` or `codex.bat` on Windows and runs them with shell support.
+- Falls back to `codex.exe` when a wrapper script is not present.
+- Adds `REMODEX_CODEX_BIN` and `PHODEX_CODEX_BIN` overrides for explicit Codex binary selection.
+- Prevents immediate uncaught startup crashes by routing launcher failures through Remodex error handling.
+
+## Why This Exists
+
+On Windows, `codex` is often installed through npm as a `.cmd` shim. A plain Node `spawn("codex", ["app-server"])` call can fail even when `codex` works in PowerShell. This fork resolves the executable explicitly before launching the bridge.
+
+## Install
+
+Install from this GitHub repository:
+
+```bash
+npm install -g github:needitem/remodex-windows-fix
+```
+
+Global CLI command:
+
+```bash
+remodex-windows-fix
+```
+
+## Usage
+
+Start the bridge:
+
+```bash
+remodex-windows-fix up
+```
+
+Resume the last active thread:
+
+```bash
+remodex-windows-fix resume
+```
+
+Watch rollout output:
+
+```bash
+remodex-windows-fix watch [threadId]
+```
+
+## Windows Override
+
+If you want to force a specific Codex binary, set one of these environment variables before running `remodex up`:
+
+```powershell
+$env:REMODEX_CODEX_BIN = "C:\Users\th072\AppData\Roaming\npm\codex.cmd"
+```
+
+Legacy alias:
+
+```powershell
+$env:PHODEX_CODEX_BIN = "C:\Users\th072\AppData\Roaming\npm\codex.cmd"
+```
+
+## Self-Hosted Relay
+
+This repository now includes the upstream-compatible relay code and a local runner.
+
+Start your own relay:
+
+```bash
+npm run relay
+```
+
+Or use the bundled binary directly:
+
+```bash
+remodex-relay
+```
+
+Optional relay host/port overrides:
+
+```powershell
+$env:REMODEX_RELAY_HOST = "0.0.0.0"
+$env:REMODEX_RELAY_PORT = "9000"
+```
+
+Point the bridge at your relay:
+
+```powershell
+$env:REMODEX_RELAY = "ws://YOUR_HOST:9000/relay"
+remodex up
+```
+
+For TLS/reverse-proxy setups, use the public `wss://YOUR_DOMAIN/relay` URL instead.
+
+Health endpoint:
+
+```text
+GET /health
+```
+
+## Cloudflare Deploy
+
+This repository also includes a Cloudflare Workers relay implementation in [cloudflare/worker.mjs](cloudflare/worker.mjs) with Durable Objects configured in [wrangler.toml](wrangler.toml).
+
+GitHub itself still does not host persistent WebSocket servers, but Cloudflare Workers can deploy this relay directly from your GitHub repository without running anything locally.
+
+Import this repository in Cloudflare:
+
+1. Open Cloudflare Workers & Pages.
+2. Create or import a Worker from your GitHub repository.
+3. Use the worker name `remodex-relay` so it matches [wrangler.toml](wrangler.toml).
+4. Deploy the repository as-is.
+5. After deploy, use the public Worker URL as the relay base:
+
+```powershell
+$env:REMODEX_RELAY = "wss://YOUR-WORKER.YOUR-SUBDOMAIN.workers.dev/relay"
+remodex-windows-fix up
+```
+
+Current deployed example for this repository:
+
+```powershell
+$env:REMODEX_RELAY = "wss://remodex-relay.th07290828.workers.dev/relay"
+remodex-windows-fix up
+```
+
+If you are using `cmd.exe` instead of PowerShell:
+
+```cmd
+set REMODEX_RELAY=wss://remodex-relay.th07290828.workers.dev/relay
+remodex-windows-fix up
+```
+
+Health check:
+
+```text
+https://remodex-relay.th07290828.workers.dev/health
+```
+
+Cloudflare health endpoint:
+
+```text
+GET /health
+```
+
+## Alternative GitHub Deploy
+
+If you prefer a normal Node web service instead of Workers, this repository still includes the Render-compatible runner in [render.yaml](render.yaml).
+
+```powershell
+$env:REMODEX_RELAY = "wss://YOUR-SERVICE.onrender.com/relay"
+remodex-windows-fix up
+```
+
+## Validation
+
+Typical local verification:
+
+```bash
+codex --version
+codex app-server --help
+remodex-windows-fix up
+```
+
+Expected Windows resolution after the fix:
+
+```text
+C:\Users\th072\AppData\Roaming\npm\codex.cmd app-server
+```
+
+## Project Layout
+
+```text
+bin/
+src/
+package.json
+```
+
+## Attribution
+
+This repository preserves the upstream Remodex package structure and credits the original package author in `package.json`. This fork adds a Windows launcher compatibility patch and accompanying documentation.

package/bin/phodex.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// FILE: phodex.js
+// Purpose: Backward-compatible wrapper that forwards legacy `phodex up` usage to `remodex up`.
+// Layer: CLI binary
+// Exports: none
+// Depends on: ./remodex
+
+require("./remodex");

package/bin/remodex-relay.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// FILE: remodex-relay.js
+// Purpose: CLI entrypoint for running the bundled Remodex relay locally.
+// Layer: CLI binary
+// Exports: none
+// Depends on: ../src/relay-server
+
+const { startRelayServer } = require("../src/relay-server");
+
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+  console.log("Usage: remodex-relay [port]");
+  console.log("Environment: REMODEX_RELAY_HOST, REMODEX_RELAY_PORT");
+  process.exit(0);
+}
+
+const portArg = process.argv[2];
+startRelayServer({
+  port: portArg ? Number.parseInt(portArg, 10) : undefined,
+});

package/bin/remodex.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// FILE: remodex.js
+// Purpose: CLI surface for starting the local Remodex bridge, reopening the latest active thread, and tailing its rollout file.
+// Layer: CLI binary
+// Exports: none
+// Depends on: ../src
+
+const { startBridge, openLastActiveThread, watchThreadRollout } = require("../src");
+
+const command = process.argv[2] || "up";
+
+if (command === "up") {
+  startBridge();
+  return;
+}
+
+if (command === "resume") {
+  try {
+    const state = openLastActiveThread();
+    console.log(
+      `[remodex] Opened last active thread: ${state.threadId} (${state.source || "unknown"})`
+    );
+  } catch (error) {
+    console.error(`[remodex] ${(error && error.message) || "Failed to reopen the last thread."}`);
+    process.exit(1);
+  }
+  return;
+}
+
+if (command === "watch") {
+  try {
+    watchThreadRollout(process.argv[3] || "");
+  } catch (error) {
+    console.error(`[remodex] ${(error && error.message) || "Failed to watch the thread rollout."}`);
+    process.exit(1);
+  }
+  return;
+}
+
+if (command !== "up") {
+  console.error(`Unknown command: ${command}`);
+  console.error("Usage: remodex up | remodex resume | remodex watch [threadId]");
+  process.exit(1);
+}

package/cloudflare/README.md

@@ -0,0 +1,16 @@
+# Cloudflare Relay
+
+This folder contains a Cloudflare Workers + Durable Objects implementation of the Remodex relay protocol.
+
+It preserves the same session path and headers used by the bridge and iPhone client:
+
+- path: `/relay/{sessionId}`
+- required header: `x-role: mac` or `x-role: iphone`
+- close code `4000`: invalid session or role
+- close code `4001`: previous Mac connection replaced
+- close code `4002`: session unavailable / Mac disconnected
+- close code `4003`: previous iPhone connection replaced
+
+The public health endpoint is:
+
+- `GET /health`

package/cloudflare/worker.mjs

@@ -0,0 +1,221 @@
+import { DurableObject } from "cloudflare:workers";
+
+const MAX_HISTORY = 500;
+const CLOSE_CODE_INVALID_SESSION = 4000;
+const CLOSE_CODE_MAC_REPLACED = 4001;
+const CLOSE_CODE_SESSION_UNAVAILABLE = 4002;
+const CLOSE_CODE_IPHONE_REPLACED = 4003;
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+
+    if (url.pathname === "/health") {
+      return jsonResponse({
+        ok: true,
+        service: "remodex-relay",
+        runtime: "cloudflare-workers",
+      });
+    }
+
+    const match = url.pathname.match(/^\/relay\/([^/?]+)/);
+    if (!match) {
+      return new Response("not found", { status: 404 });
+    }
+
+    const sessionId = match[1];
+    const stub = env.SESSION_RELAY.get(env.SESSION_RELAY.idFromName(sessionId));
+    return stub.fetch(request);
+  },
+};
+
+export class SessionRelay extends DurableObject {
+  constructor(ctx, env) {
+    super(ctx, env);
+    this.ctx = ctx;
+    this.env = env;
+    this.mac = null;
+    this.clients = new Set();
+    this.history = [];
+
+    this.ctx.blockConcurrencyWhile(async () => {
+      this.history = (await this.ctx.storage.get("history")) || [];
+      for (const socket of this.ctx.getWebSockets()) {
+        const metadata = socket.deserializeAttachment() || {};
+        if (metadata.role === "mac") {
+          this.mac = socket;
+        } else if (metadata.role === "iphone") {
+          this.clients.add(socket);
+        }
+      }
+    });
+  }
+
+  async fetch(request) {
+    const upgrade = request.headers.get("Upgrade");
+    if (!upgrade || upgrade.toLowerCase() !== "websocket") {
+      return new Response("Expected WebSocket upgrade", { status: 426 });
+    }
+
+    const url = new URL(request.url);
+    const sessionId = url.pathname.match(/^\/relay\/([^/?]+)/)?.[1];
+    const role = request.headers.get("x-role");
+
+    if (!sessionId || (role !== "mac" && role !== "iphone")) {
+      return closeWebSocketResponse(
+        CLOSE_CODE_INVALID_SESSION,
+        "Missing sessionId or invalid x-role header"
+      );
+    }
+
+    if (role === "iphone" && !this.isSocketOpen(this.mac)) {
+      return closeWebSocketResponse(
+        CLOSE_CODE_SESSION_UNAVAILABLE,
+        "Mac session not available"
+      );
+    }
+
+    const pair = new WebSocketPair();
+    const [clientSocket, serverSocket] = Object.values(pair);
+
+    this.ctx.acceptWebSocket(serverSocket);
+    serverSocket.serializeAttachment({ role });
+
+    if (role === "mac") {
+      if (this.isSocketOpen(this.mac)) {
+        this.safeClose(
+          this.mac,
+          CLOSE_CODE_MAC_REPLACED,
+          "Replaced by new Mac connection"
+        );
+      }
+      this.mac = serverSocket;
+      console.log(`[relay] Mac connected -> session ${sessionId}`);
+    } else {
+      for (const existingClient of this.clients) {
+        if (existingClient === serverSocket) {
+          continue;
+        }
+        this.safeClose(
+          existingClient,
+          CLOSE_CODE_IPHONE_REPLACED,
+          "Replaced by newer iPhone connection"
+        );
+      }
+      this.clients = new Set([serverSocket]);
+      console.log(`[relay] iPhone connected -> session ${sessionId} (1 client)`);
+
+      for (const msg of this.history) {
+        this.safeSend(serverSocket, msg);
+      }
+    }
+
+    return new Response(null, { status: 101, webSocket: clientSocket });
+  }
+
+  async webSocketMessage(socket, message) {
+    const metadata = socket.deserializeAttachment() || {};
+    const text = normalizeMessage(message);
+
+    if (metadata.role === "mac") {
+      this.history.push(text);
+      if (this.history.length > MAX_HISTORY) {
+        this.history.shift();
+      }
+      await this.ctx.storage.put("history", this.history);
+
+      for (const client of this.clients) {
+        this.safeSend(client, text);
+      }
+      return;
+    }
+
+    if (this.isSocketOpen(this.mac)) {
+      this.safeSend(this.mac, text);
+    }
+  }
+
+  async webSocketClose(socket) {
+    await this.dropSocket(socket);
+  }
+
+  async webSocketError(socket, error) {
+    console.error("[relay] WebSocket error:", error?.message || String(error));
+    await this.dropSocket(socket);
+  }
+
+  async dropSocket(socket) {
+    const metadata = socket.deserializeAttachment() || {};
+
+    if (metadata.role === "mac") {
+      if (this.mac === socket) {
+        this.mac = null;
+        for (const client of this.clients) {
+          this.safeClose(client, CLOSE_CODE_SESSION_UNAVAILABLE, "Mac disconnected");
+        }
+        this.clients.clear();
+      }
+    } else if (metadata.role === "iphone") {
+      this.clients.delete(socket);
+    }
+
+    if (!this.isSocketOpen(this.mac) && this.clients.size === 0) {
+      this.history = [];
+      await this.ctx.storage.deleteAll();
+    }
+  }
+
+  isSocketOpen(socket) {
+    return !!socket && socket.readyState === 1;
+  }
+
+  safeSend(socket, message) {
+    if (!this.isSocketOpen(socket)) {
+      return;
+    }
+
+    try {
+      socket.send(message);
+    } catch {}
+  }
+
+  safeClose(socket, code, reason) {
+    if (!socket) {
+      return;
+    }
+
+    try {
+      socket.close(code, reason);
+    } catch {}
+  }
+}
+
+function normalizeMessage(message) {
+  if (typeof message === "string") {
+    return message;
+  }
+
+  if (message instanceof ArrayBuffer) {
+    return new TextDecoder().decode(message);
+  }
+
+  return String(message);
+}
+
+function closeWebSocketResponse(code, reason) {
+  const pair = new WebSocketPair();
+  const [clientSocket, serverSocket] = Object.values(pair);
+  serverSocket.accept();
+  serverSocket.close(code, reason);
+  return new Response(null, { status: 101, webSocket: clientSocket });
+}
+
+function jsonResponse(value) {
+  const payload = JSON.stringify(value);
+  return new Response(payload, {
+    status: 200,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+    },
+  });
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "remodex-windows-fix",
+  "version": "1.0.2",
+  "description": "Local bridge between Codex and the Remodex mobile app with a Windows-safe Codex launcher.",
+  "main": "src/index.js",
+  "bin": {
+    "remodex-windows-fix": "bin/remodex.js",
+    "remodex-relay": "bin/remodex-relay.js"
+  },
+  "files": [
+    "bin/",
+    "cloudflare/",
+    "relay/",
+    "render.yaml",
+    "src/",
+    "wrangler.toml"
+  ],
+  "scripts": {
+    "start": "node ./bin/remodex.js up",
+    "relay": "node ./bin/remodex-relay.js"
+  },
+  "keywords": [
+    "remodex",
+    "codex",
+    "bridge",
+    "cli",
+    "windows"
+  ],
+  "author": "Emanuele Di Pietro",
+  "license": "ISC",
+  "type": "commonjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/needitem/remodex-windows-fix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/needitem/remodex-windows-fix/issues"
+  },
+  "homepage": "https://github.com/needitem/remodex-windows-fix#readme",
+  "dependencies": {
+    "qrcode-terminal": "^0.12.0",
+    "uuid": "^13.0.0",
+    "ws": "^8.19.0"
+  }
+}

package/relay/README.md

@@ -0,0 +1,39 @@
+# Relay
+
+This folder contains the thin WebSocket relay used by the default hosted Remodex pairing flow.
+
+The implementation is copied from the upstream open-source relay so you can run the same session routing yourself.
+
+## What It Does
+
+- accepts WebSocket connections at `/relay/{sessionId}`
+- pairs one Mac host with one live iPhone client for a session
+- forwards JSON-RPC traffic between Mac and iPhone
+- replays a small in-memory history buffer to a reconnecting iPhone client
+- exposes lightweight stats for a health endpoint
+
+## What It Does Not Do
+
+- it does not run Codex
+- it does not execute git commands
+- it does not contain your repository checkout
+- it does not persist the local workspace on the server
+
+Codex, git, and local file operations still run on the user's machine.
+
+## Local Runner
+
+This repository includes a local relay runner:
+
+```bash
+npm run relay
+```
+
+Environment variables:
+
+- `REMODEX_RELAY_HOST` defaults to `0.0.0.0`
+- `REMODEX_RELAY_PORT` defaults to `9000`
+
+Health endpoint:
+
+- `GET /health`