androdex 1.1.3 → 1.1.6

package/README.md

@@ -1,8 +1,8 @@
 # androdex
 
-`androdex` is the host-side CLI bridge for the Androdex project.
+`androdex` is the macOS host bridge for the Androdex Android client.
 
-It is published separately from the Android app. The daemon keeps a stable host identity alive on the host machine and lets the Android client control local Codex remotely.
+It keeps Codex running locally on the Mac, exposes a relay-backed encrypted session for Android, and uses a launchd-managed background service so pairing and reconnect survive terminal closes.
 
 ## Install
 
@@ -13,59 +13,84 @@ npm install -g androdex
 ## Usage
 
 ```sh
-androdex pair
 androdex up
-androdex daemon status
+androdex start
+androdex restart
+androdex stop
+androdex status
 androdex reset-pairing
 androdex resume
-androdex watch
+androdex watch [threadId]
 ```
 
+## Command Model
+
+- `androdex up`
+  Starts or refreshes the macOS bridge service, waits for a fresh pairing QR, prints it, and binds the current working directory as the active workspace.
+- `androdex start`
+  Starts the launchd-managed macOS bridge service without changing the active workspace.
+- `androdex restart`
+  Restarts the launchd-managed macOS bridge service without changing the active workspace.
+- `androdex stop`
+  Stops the macOS bridge service and clears stale in-memory runtime state.
+- `androdex status`
+  Prints launchd status, persisted bridge status, and the stdout/stderr log paths under `~/.androdex`.
+- `androdex run`
+  Runs the bridge in the foreground.
+- `androdex run-service`
+  Internal launchd entrypoint used by the installed plist.
+- `androdex reset-pairing`
+  Stops the service and clears the saved trusted-device state so the next `androdex up` starts fresh.
+- `androdex resume`
+  Reopens the last active thread in the local Codex desktop app if available.
+- `androdex watch [threadId]`
+  Tails the rollout log for the selected thread in real time.
+
 ## What it does
 
-- keeps a durable relay presence keyed by a stable host id
-- prints a pairing QR code and raw pairing payload on demand
-- activates local `codex app-server` for the current workspace
+- runs a launchd-managed macOS bridge service with label `io.androdex.bridge`
+- prints a pairing QR for the current relay session
+- restores the last active workspace on service start when possible
+- lets the Android client browse host folders and switch workspaces remotely
 - forwards JSON-RPC traffic between the host and the Android client
-- handles git and workspace actions on the host machine
-
-## Commands
-
-### `androdex up`
-
-Activates the current workspace in the daemon and launches `codex app-server` locally if needed.
-
-### `androdex pair`
+- handles git and workspace actions on the host machine, including branch/worktree management and reverse-patch safety checks
+- keeps the local Codex desktop app aligned with phone-authored thread activity when desktop refresh is enabled
 
-Prints a fresh pairing QR and raw pairing payload for the already-running daemon identity.
-
-### `androdex daemon [start|stop|status]`
-
-Manages the background daemon that owns the stable host identity and relay presence.
+## Environment variables
 
-### `androdex reset-pairing`
+`androdex` accepts `ANDRODEX_*` variables.
 
-Clears the saved trusted-device state so the next `androdex pair` starts a fresh pairing flow.
+Useful variables:
 
-### `androdex resume`
+- `ANDRODEX_RELAY`: set the relay URL explicitly and override any packaged default
+- `ANDRODEX_DEFAULT_RELAY_URL`: override the built-in default relay URL when no explicit override is present
+- `ANDRODEX_CODEX_ENDPOINT`: connect to an existing Codex WebSocket instead of spawning a local runtime
+- `ANDRODEX_REFRESH_ENABLED`: enable or disable desktop refresh explicitly
+- `ANDRODEX_REFRESH_DEBOUNCE_MS`: adjust refresh debounce timing
+- `ANDRODEX_REFRESH_COMMAND`: override desktop refresh with a custom command
+- `ANDRODEX_CODEX_BUNDLE_ID`: override the Codex desktop bundle ID on macOS
+- `ANDRODEX_PUSH_SERVICE_URL`: optional Android push service endpoint for device registration and completion notifications
 
-Reopens the last active thread in the local Codex desktop app if available.
+The bridge resolves relay configuration in this order:
 
-### `androdex watch [threadId]`
+1. `ANDRODEX_RELAY`
+2. `ANDRODEX_DEFAULT_RELAY_URL`
+3. `wss://relay.androdex.xyz/relay`
 
-Tails the rollout log for the selected thread in real time.
+Common relay patterns:
 
-## Environment variables
+```sh
+# Built-in public relay
+androdex up
 
-`androdex` accepts `ANDRODEX_*` variables.
+# Local relay on your own network
+ANDRODEX_RELAY=ws://192.168.x.x:8787/relay androdex up
 
-Useful variables:
+# Public relay you control
+ANDRODEX_RELAY=wss://relay.example.com/relay androdex up
+```
 
-- `ANDRODEX_RELAY`: set the relay URL explicitly
-- `ANDRODEX_CODEX_ENDPOINT`: connect to an existing Codex WebSocket instead of spawning a local runtime
-- `ANDRODEX_REFRESH_ENABLED`: enable the macOS desktop refresh workaround explicitly
-- `ANDRODEX_REFRESH_DEBOUNCE_MS`: adjust refresh debounce timing
-- `ANDRODEX_REFRESH_COMMAND`: override desktop refresh with a custom command
+If you change relay URLs after pairing, run `androdex reset-pairing` and pair again with `androdex up` so Android gets a fresh payload for the new relay session.
 
 ## Source builds
 
@@ -77,8 +102,36 @@ npm install
 npm start
 ```
 
+## Release
+
+Publish the npm package from this directory, not from the repository root:
+
+```sh
+cd androdex-bridge
+npm test
+npm pack --dry-run
+npm version patch --no-git-tag-version
+npm publish --access public
+```
+
+Verify the published version after the release:
+
+```sh
+npm view androdex version
+```
+
+If your npm account requires write-time 2FA, rerun the publish command with `--otp=<code>`.
+
+## Manual Smoke Checklist
+
+1. Run `androdex up` and confirm the Android app can pair successfully.
+2. Run `androdex up` inside a workspace and confirm the host keeps Codex bound to that local project.
+3. From Android, open an existing thread and create a new one to confirm the remote client flow still works end to end.
+4. If desktop refresh is enabled, verify phone-authored thread activity updates the host Codex desktop via the Settings-bounce remount workaround.
+5. Restart the launchd service or reconnect the phone and confirm the saved pairing and active workspace recover without losing host-local state.
+
 ## Project status
 
-This package is part of Androdex, a local-first project focused on the host-machine-plus-Android workflow today.
+This package is part of Androdex, a macOS host-local Codex plus Android remote-access workflow.
 
 Credit for the upstream fork chain remains with [relaydex](https://github.com/Ranats/relaydex) and [Remodex](https://github.com/Emanuele-web04/remodex).

package/bin/androdex.js

@@ -5,4 +5,6 @@
 // Exports: none
 // Depends on: ./cli
 
-require("./cli");
+const { main } = require("./cli");
+
+void main();

package/bin/cli.js

@@ -1,105 +1,208 @@
 #!/usr/bin/env node
 // FILE: cli.js
-// Purpose: CLI surface for daemon start, workspace activation, pairing, thread resume, and rollout tailing.
+// Purpose: CLI surface for foreground bridge runs, pairing reset, thread resume, and macOS service control.
 // Layer: CLI binary
 // Exports: none
 // Depends on: ../src
 
 const {
-  createPairing,
-  getDaemonStatus,
-  runDaemonProcess,
+  printMacOSBridgePairingQr,
+  printMacOSBridgeServiceStatus,
+  readBridgeConfig,
+  resetMacOSBridgePairing,
+  runMacOSBridgeService,
   startBridge,
-  startDaemonCli,
-  stopDaemonCli,
+  startMacOSBridgeService,
+  stopMacOSBridgeService,
   resetBridgePairing,
   openLastActiveThread,
   watchThreadRollout,
 } = require("../src");
-const { printQR } = require("../src/qr");
-
-const command = process.argv[2] || "up";
-const CLI_NAME = "androdex";
-const CLI_PREFIX = `[${CLI_NAME}]`;
+const { version } = require("../package.json");
+
+const defaultDeps = {
+  printMacOSBridgePairingQr,
+  printMacOSBridgeServiceStatus,
+  readBridgeConfig,
+  resetMacOSBridgePairing,
+  runMacOSBridgeService,
+  startBridge,
+  startMacOSBridgeService,
+  stopMacOSBridgeService,
+  resetBridgePairing,
+  openLastActiveThread,
+  watchThreadRollout,
+};
 
-void main().catch((error) => {
-  console.error(`${CLI_PREFIX} ${(error && error.message) || "Command failed."}`);
-  process.exit(1);
-});
+if (require.main === module) {
+  void main();
+}
 
-async function main() {
-  if (command === "__daemon-run") {
-    await runDaemonProcess();
+async function main({
+  argv = process.argv,
+  platform = process.platform,
+  consoleImpl = console,
+  exitImpl = process.exit,
+  deps = defaultDeps,
+} = {}) {
+  const command = argv[2] || "up";
+
+  if (isVersionCommand(command)) {
+    consoleImpl.log(version);
     return;
   }
 
   if (command === "up") {
-    const status = await startBridge();
-    console.log(`${CLI_PREFIX} Active workspace: ${status.currentCwd || process.cwd()}`);
-    console.log(`${CLI_PREFIX} Relay: ${status.relayStatus}`);
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    deps.readBridgeConfig();
+    const result = await deps.startMacOSBridgeService({
+      waitForPairing: true,
+      activeCwd: process.cwd(),
+    });
+    deps.printMacOSBridgePairingQr({
+      pairingSession: result.pairingSession,
+    });
     return;
   }
 
-  if (command === "pair") {
-    const response = await createPairing();
-    printQR(response.pairingPayload);
+  if (command === "run") {
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    deps.startBridge();
     return;
   }
 
-  if (command === "daemon") {
-    await handleDaemonCommand(process.argv[3] || "status");
+  if (command === "run-service") {
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    deps.runMacOSBridgeService();
     return;
   }
 
-  if (command === "reset-pairing") {
-    await resetBridgePairing();
-    console.log(`${CLI_PREFIX} Cleared the saved pairing state. Run \`${CLI_NAME} pair\` to create a fresh pairing QR.`);
+  if (command === "start") {
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    deps.readBridgeConfig();
+    await deps.startMacOSBridgeService({
+      waitForPairing: false,
+    });
+    consoleImpl.log("[androdex] macOS bridge service is running.");
     return;
   }
 
-  if (command === "resume") {
-    const state = openLastActiveThread();
-    console.log(
-      `${CLI_PREFIX} Opened last active thread: ${state.threadId} (${state.source || "unknown"})`
-    );
+  if (command === "restart") {
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    deps.readBridgeConfig();
+    await deps.startMacOSBridgeService({
+      waitForPairing: false,
+    });
+    consoleImpl.log("[androdex] macOS bridge service restarted.");
     return;
   }
 
-  if (command === "watch") {
-    watchThreadRollout(process.argv[3] || "");
+  if (command === "stop") {
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    deps.stopMacOSBridgeService();
+    consoleImpl.log("[androdex] macOS bridge service stopped.");
     return;
   }
 
-  console.error(`Unknown command: ${command}`);
-  console.error("Usage: androdex up | androdex pair | androdex daemon [start|stop|status] | androdex reset-pairing | androdex resume | androdex watch [threadId]");
-  process.exit(1);
-}
+  if (command === "status") {
+    assertMacOSCommand(command, {
+      platform,
+      consoleImpl,
+      exitImpl,
+    });
+    deps.printMacOSBridgeServiceStatus();
+    return;
+  }
+
+  if (command === "reset-pairing") {
+    try {
+      if (platform === "darwin") {
+        deps.resetMacOSBridgePairing();
+        consoleImpl.log("[androdex] Stopped the macOS bridge service and cleared the saved pairing state. Run `androdex up` to pair again.");
+      } else {
+        deps.resetBridgePairing();
+        consoleImpl.log("[androdex] Cleared the saved pairing state. Run `androdex up` to pair again.");
+      }
+    } catch (error) {
+      consoleImpl.error(`[androdex] ${(error && error.message) || "Failed to clear the saved pairing state."}`);
+      exitImpl(1);
+    }
+    return;
+  }
 
-async function handleDaemonCommand(subcommand) {
-  if (subcommand === "start") {
-    const response = await startDaemonCli();
-    printDaemonStatus(response.status);
+  if (command === "resume") {
+    try {
+      const state = deps.openLastActiveThread();
+      consoleImpl.log(
+        `[androdex] Opened last active thread: ${state.threadId} (${state.source || "unknown"})`
+      );
+    } catch (error) {
+      consoleImpl.error(`[androdex] ${(error && error.message) || "Failed to reopen the last thread."}`);
+      exitImpl(1);
+    }
     return;
   }
 
-  if (subcommand === "stop") {
-    await stopDaemonCli();
-    console.log(`${CLI_PREFIX} Daemon stopped.`);
+  if (command === "watch") {
+    try {
+      deps.watchThreadRollout(argv[3] || "");
+    } catch (error) {
+      consoleImpl.error(`[androdex] ${(error && error.message) || "Failed to watch the thread rollout."}`);
+      exitImpl(1);
+    }
     return;
   }
 
-  if (subcommand === "status") {
-    const response = await getDaemonStatus();
-    printDaemonStatus(response.status);
+  consoleImpl.error(`Unknown command: ${command}`);
+  consoleImpl.error(
+    "Usage: androdex up | androdex run | androdex start | androdex restart | androdex stop | androdex status | "
+    + "androdex reset-pairing | androdex resume | androdex watch [threadId] | androdex --version"
+  );
+  exitImpl(1);
+}
+
+function assertMacOSCommand(name, {
+  platform = process.platform,
+  consoleImpl = console,
+  exitImpl = process.exit,
+} = {}) {
+  if (platform === "darwin") {
     return;
   }
 
-  throw new Error(`Unknown daemon subcommand: ${subcommand}`);
+  consoleImpl.error(`[androdex] \`${name}\` is only available on macOS right now.`);
+  exitImpl(1);
 }
 
-function printDaemonStatus(status) {
-  console.log(`${CLI_PREFIX} Relay: ${status.relayStatus || "unknown"}`);
-  console.log(`${CLI_PREFIX} Host ID: ${status.hostId || "unavailable"}`);
-  console.log(`${CLI_PREFIX} Workspace: ${status.currentCwd || "none"}`);
-  console.log(`${CLI_PREFIX} Workspace active: ${status.workspaceActive ? "yes" : "no"}`);
+function isVersionCommand(value) {
+  return value === "-v" || value === "--v" || value === "-V" || value === "--version" || value === "version";
 }
+
+module.exports = {
+  isVersionCommand,
+  main,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "androdex",
-  "version": "1.1.3",
-  "description": "Local bridge between Codex and the Androdex mobile app. Run `androdex up` to start.",
+  "version": "1.1.6",
+  "description": "macOS host bridge between Codex and the Androdex Android app. Run `androdex up` to start.",
   "main": "src/index.js",
   "bin": {
     "androdex": "bin/androdex.js"
@@ -14,14 +14,15 @@
   ],
   "scripts": {
     "start": "node ./bin/androdex.js up",
-    "test": "node --test ./test/*.test.js"
+    "test": "node --test --test-concurrency=1"
   },
   "keywords": [
     "androdex",
     "codex",
     "bridge",
     "cli",
-    "android"
+    "android",
+    "macos"
   ],
   "author": "Robert Gordon",
   "license": "ISC",
@@ -29,6 +30,9 @@
   "engines": {
     "node": ">=18"
   },
+  "os": [
+    "darwin"
+  ],
   "publishConfig": {
     "access": "public"
   },

package/src/account-status.js

@@ -0,0 +1,127 @@
+// FILE: account-status.js
+// Purpose: Converts raw Codex account/auth responses into a sanitized host-account snapshot for Android.
+// Layer: CLI helper
+// Exports: composeAccountStatus, composeSanitizedAuthStatusFromSettledResults, redactAuthStatus
+// Depends on: ../package.json
+
+const { version: bridgePackageVersion = "" } = require("../package.json");
+
+function composeAccountStatus({
+  accountRead = null,
+  authStatus = null,
+  loginInFlight = false,
+  bridgeVersionInfo = null,
+} = {}) {
+  const account = accountRead?.account || null;
+  const authToken = normalizeString(authStatus?.authToken);
+  const hasAccountLogin = hasExplicitAccountLogin(account);
+  const authMethod = firstNonEmpty([
+    normalizeString(authStatus?.authMethod),
+    normalizeString(account?.type),
+  ]) || null;
+  const tokenReady = Boolean(authToken);
+  const requiresOpenaiAuth = Boolean(accountRead?.requiresOpenaiAuth || authStatus?.requiresOpenaiAuth);
+  const hasPriorLoginContext = hasAccountLogin || Boolean(authMethod);
+  const needsReauth = !loginInFlight && requiresOpenaiAuth && hasPriorLoginContext;
+  const isAuthenticated = !needsReauth && (tokenReady || hasAccountLogin);
+  const status = isAuthenticated
+    ? "authenticated"
+    : (loginInFlight ? "pending_login" : (needsReauth ? "expired" : "not_logged_in"));
+
+  return {
+    status,
+    authMethod,
+    email: normalizeString(account?.email) || null,
+    planType: normalizeString(account?.planType) || null,
+    loginInFlight: Boolean(loginInFlight),
+    needsReauth,
+    tokenReady,
+    expiresAt: null,
+    requiresOpenaiAuth,
+    bridgeVersion: firstNonEmpty([
+      normalizeString(bridgeVersionInfo?.bridgeVersion),
+      normalizeString(bridgePackageVersion),
+    ]) || null,
+    bridgeLatestVersion: normalizeString(bridgeVersionInfo?.bridgeLatestVersion) || null,
+  };
+}
+
+function redactAuthStatus(authStatus = null, extras = {}) {
+  const composed = composeAccountStatus({
+    accountRead: extras.accountRead || null,
+    authStatus,
+    loginInFlight: Boolean(extras.loginInFlight),
+    bridgeVersionInfo: extras.bridgeVersionInfo || null,
+  });
+
+  return {
+    authMethod: composed.authMethod,
+    status: composed.status,
+    email: composed.email,
+    planType: composed.planType,
+    loginInFlight: composed.loginInFlight,
+    needsReauth: composed.needsReauth,
+    tokenReady: composed.tokenReady,
+    expiresAt: composed.expiresAt,
+    bridgeVersion: composed.bridgeVersion,
+    bridgeLatestVersion: composed.bridgeLatestVersion,
+  };
+}
+
+function composeSanitizedAuthStatusFromSettledResults({
+  accountReadResult = null,
+  authStatusResult = null,
+  loginInFlight = false,
+  bridgeVersionInfo = null,
+} = {}) {
+  const accountRead = accountReadResult?.status === "fulfilled" ? accountReadResult.value : null;
+  const authStatus = authStatusResult?.status === "fulfilled" ? authStatusResult.value : null;
+
+  if (!accountRead && !authStatus) {
+    const error = new Error("Unable to read host account status from the bridge.");
+    error.errorCode = "auth_status_unavailable";
+    throw error;
+  }
+
+  return redactAuthStatus(authStatus, {
+    accountRead,
+    loginInFlight: Boolean(loginInFlight),
+    bridgeVersionInfo,
+  });
+}
+
+function hasExplicitAccountLogin(account) {
+  if (!account || typeof account !== "object") {
+    return false;
+  }
+
+  if (parseBoolean(account.loggedIn) || parseBoolean(account.logged_in) || parseBoolean(account.isLoggedIn)) {
+    return true;
+  }
+
+  return Boolean(normalizeString(account.email));
+}
+
+function firstNonEmpty(values) {
+  for (const value of values) {
+    const normalized = normalizeString(value);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return "";
+}
+
+function normalizeString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function parseBoolean(value) {
+  return value === true;
+}
+
+module.exports = {
+  composeAccountStatus,
+  composeSanitizedAuthStatusFromSettledResults,
+  redactAuthStatus,
+};