@4xeoz/re-entry 0.2.1 → 0.2.3

package/README.md

@@ -13,14 +13,37 @@ Requirements: macOS, Node.js 24+, Codex installed and signed in, and an absolute
 Codex may read and write.
 
 ```sh
-npx @4xeoz/re-entry install --codex-cd /absolute/path/to/your/project
+npx @4xeoz/re-entry install
+```
+
+This uses the deployed Re-entry Cloud Receiver by default:
+`https://reentry-cloud.vercel.app`.
+
+The interactive CLI lets you choose the Codex workspace with ↑/↓ and Enter. If you want to choose
+the workspace explicitly, pass it directly:
+
+```sh
+npx @4xeoz/re-entry install \
+  --codex-cd /absolute/path/to/your/project
+```
+
+Run this from the Host project directory, your home directory, or another normal working
+directory—not from a checked-out `runtime/local-connector` package directory. npm can treat that
+source directory as the package itself and fail to create the temporary executable link.
+
+If npm prints `sh: re-entry: command not found`, the package is present but that npm installation
+has an `npx` temporary-bin `PATH` bug. Use the reliable one-time global installation instead:
+
+```sh
+npm install --global @4xeoz/re-entry@0.2.1
+re-entry install --codex-cd /absolute/path/to/your/project
 ```
 
 The published package uses the hosted Receiver by default. Use `--receiver` only when testing a
 different Receiver, such as the local preview:
 
 ```sh
-npx @4xeoz/re-entry install \
+npx --yes --package=@4xeoz/re-entry re-entry install \
   --receiver http://127.0.0.1:43224 \
   --codex-cd /absolute/path/to/your/project
 ```
@@ -29,6 +52,7 @@ npx @4xeoz/re-entry install \
 
 ```text
 check Node + find Codex + validate project directory
+  -> choose the Codex workspace with ↑/↓ and Enter when --codex-cd is omitted
   -> request a device authorization from Re-entry
   -> show the verification URL and wait for the user to press Enter
   -> open Re-entry in the default browser
@@ -59,6 +83,18 @@ re-entry claim-once --codex-cd /absolute/path/to/project
 re-entry start --codex-cd /absolute/path/to/project
 ```
 
+To pause or remove the local Connector:
+
+```sh
+re-entry stop
+re-entry uninstall
+```
+
+`stop` pauses the macOS background service and keeps the account connection. `uninstall` requires
+typing `DELETE`, then removes only the LaunchAgent, saved Connector credential, and Connector logs.
+It does not recursively delete folders or uninstall the npm package. To remove a global npm
+installation separately, run `npm uninstall --global @4xeoz/re-entry`.
+
 `connect` repeats only account authorization. `install` is the normal product path because it also
 installs the background job. `claim-once` is the smallest manual delivery test. The legacy
 Host-code `pair` command remains only for compatibility tests.
@@ -69,7 +105,7 @@ Copy this prompt into a coding-agent task:
 
 ```text
 Install the Re-entry Local Connector on this Mac. First read the package README. Verify Node.js 24
-or newer and locate the installed Codex executable. Run `npx @4xeoz/re-entry install` with an absolute
+or newer and locate the Connector executable. Run `npx --yes --package=@4xeoz/re-entry re-entry install` with an absolute
 project directory. Let the human complete the Re-entry
 browser approval; never copy browser cookies, organization keys, Connector tokens, or private keys
 into chat, logs, source files, or git. Finish by running `re-entry status` and report the bounded
@@ -81,7 +117,8 @@ results without claiming Browser/WebMCP or production deployment.
 - `src/main.mjs` — `re-entry` CLI and long-running poll loop.
 - `src/pairing-client.mjs` — account-first browser device authorization.
 - `src/credentials.mjs` — atomic local credential storage.
-- `src/macos-service.mjs` — per-user LaunchAgent install and status.
+- `src/macos-service.mjs` — per-user LaunchAgent install, stop, uninstall, and status.
+- `src/workspace-picker.mjs` — interactive Codex workspace selection.
 - `src/local-connector.mjs` — one claim and activation boundary.
 - `src/codex-exec-adapter.mjs` — fresh local Codex process adapter.
 - `src/terminal-ui.mjs` — dependency-free human CLI presentation.
@@ -137,9 +174,13 @@ npm login
 npm publish --access public
 ```
 
-After publishing, users run `npx @4xeoz/re-entry install`. The executable inside the package is
+After publishing, users run `npx --yes --package=@4xeoz/re-entry re-entry install`. The explicit
+`--package` form works across npm versions when the package is scoped; the executable itself is
 still named `re-entry`.
 
+On npm installations affected by the temporary-bin `PATH` bug, use `npm install --global
+@4xeoz/re-entry` once and then run `re-entry install` directly.
+
 ## Check a Mac before pairing
 
 Run the read-only readiness check before connecting the machine:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "Outbound Local Connector process for the Re-entry Core local preview.",
   "publishConfig": {

package/src/macos-service.mjs

@@ -96,6 +96,58 @@ export async function inspectMacConnectorService(options = {}) {
   });
 }
 
+export async function stopMacConnectorService(options = {}) {
+  const configuration = requireServiceConfiguration(options, "stop");
+  if (process.platform !== "darwin" && configuration.allowNonMacForTest !== true) {
+    return Object.freeze({ supported: false, stopped: false, installed: false, running: false });
+  }
+  const status = await inspectMacConnectorService(configuration);
+  if (!status.installed || !status.running) {
+    return Object.freeze({ ...status, stopped: false });
+  }
+  const domain = `gui/${typeof process.getuid === "function" ? process.getuid() : 0}`;
+  const result = await configuration.runCommand(["bootout", `${domain}/${LABEL}`]);
+  if (result.code !== 0) {
+    throw serviceFailure("connector_service_stop_failed", "Background service could not be stopped");
+  }
+  return Object.freeze({ ...status, stopped: true, running: false });
+}
+
+export async function uninstallMacConnectorService(options = {}) {
+  const configuration = requireServiceConfiguration(options, "uninstall");
+  if (process.platform !== "darwin" && configuration.allowNonMacForTest !== true) {
+    return Object.freeze({ supported: false, removedPaths: [] });
+  }
+  const service = await stopMacConnectorService(configuration);
+  const stateDirectory = configuration.stateDirectory ?? join(homedir(), ".webmcp-connector");
+  const credentialFile = requireAbsolutePath(
+    configuration.credentialFile ?? join(stateDirectory, "credentials.json"),
+    "Credential file",
+  );
+  const paths = [...new Set([
+    service.plistPath,
+    credentialFile,
+    join(stateDirectory, "connector.log"),
+    join(stateDirectory, "connector-error.log"),
+  ])];
+  const removedPaths = [];
+  for (const path of paths) {
+    try {
+      await unlink(path);
+      removedPaths.push(path);
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw serviceFailure("connector_service_remove_failed", "Connector data could not be removed", error);
+      }
+    }
+  }
+  return Object.freeze({
+    supported: true,
+    removedPaths,
+    plistPath: service.plistPath,
+  });
+}
+
 export function renderLaunchAgent(options) {
   const argumentsList = [
     options.nodeExecutable,
@@ -156,6 +208,18 @@ function runLaunchctl(argumentsList) {
   });
 }
 
+function requireServiceConfiguration(options, operation) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw serviceFailure("connector_service_input_invalid", `Service ${operation} options are invalid`);
+  }
+  const launchAgentsDirectory = options.launchAgentsDirectory ?? join(homedir(), "Library", "LaunchAgents");
+  const runCommand = options.runCommand ?? runLaunchctl;
+  if (typeof runCommand !== "function") {
+    throw new TypeError(`Service ${operation} runCommand must be a function`);
+  }
+  return { ...options, launchAgentsDirectory, runCommand };
+}
+
 function requireAbsolutePath(value, label) {
   if (
     typeof value !== "string" ||

package/src/main.mjs

@@ -20,9 +20,12 @@ import { LocalConnector } from "./local-connector.mjs";
 import { LocalConnectorCredentialStore } from "./credentials.mjs";
 import { LocalConnectorPairingClient } from "./pairing-client.mjs";
 import { waitForEnterToOpenBrowser } from "./browser-prompt.mjs";
+import { chooseWorkspaceDirectory } from "./workspace-picker.mjs";
 import {
   inspectMacConnectorService,
   installMacConnectorService,
+  stopMacConnectorService,
+  uninstallMacConnectorService,
 } from "./macos-service.mjs";
 import { createTerminalUi } from "./terminal-ui.mjs";
 
@@ -63,6 +66,14 @@ async function main() {
       await status(flags, ui);
       return;
     }
+    if (command === "stop") {
+      await stop(flags, ui);
+      return;
+    }
+    if (command === "uninstall") {
+      await uninstall(flags, ui);
+      return;
+    }
     if (command === "install") {
       await install(flags, ui);
       return;
@@ -98,13 +109,15 @@ function printHelp() {
 Connect this Mac once, then receive approved work in Codex in the background.
 
 Usage:
-  re-entry install --receiver <url> --codex-cd <project>   Recommended first run
+  re-entry install                                      Recommended first run
   re-entry status                                          Check the connection
-  re-entry start --codex-cd <project>                      Run in this terminal
+  re-entry start                                          Run in this terminal
 
 Commands:
   install      Check this Mac, connect the Re-entry account, and start at login
   status       Show account, Receiver, service, Node.js, and Codex readiness
+  stop         Stop the background Connector without removing its credential
+  uninstall    Stop the Connector and remove its local service data
   connect      Authorize this Mac without installing the background service
   start        Poll for approved work until stopped
   doctor       Check Node.js, Codex, and the optional project directory
@@ -113,9 +126,10 @@ Commands:
 
 Common options:
   --receiver <url>       Re-entry Receiver origin
-  --codex-cd <path>      Project opened for the fresh Codex session
+  --codex-cd <path>      Workspace for Codex; interactive mode offers a folder picker if omitted
   --codex-binary <path>  Explicit Codex executable
   --json                 Machine-readable output
+  --yes                  Confirm uninstall in a non-interactive script
   --help                 Show this help
   --version              Show the installed version
 
@@ -160,6 +174,17 @@ function inspectReadiness(flags) {
   return Object.freeze({ workingDirectory, installation });
 }
 
+async function withWorkspaceDirectory(flags, ui) {
+  if (flags["codex-cd"] !== undefined || !ui.interactive) {
+    return { ...flags, "codex-cd": flags["codex-cd"] ?? process.cwd() };
+  }
+  ui.info("Workspace", "choose the folder Codex will open");
+  const selected = await chooseWorkspaceDirectory({ startDirectory: process.cwd() });
+  if (!selected) throw cliFailure("connector_codex_cd_missing");
+  ui.success("Workspace", selected);
+  return { ...flags, "codex-cd": selected };
+}
+
 function showReadiness(readiness, ui) {
   if (!ui.interactive) return;
   ui.success("Node.js", process.versions.node);
@@ -223,7 +248,8 @@ async function connect(flags, ui, options = {}) {
   const credentialFile = flags["credential-file"] ?? defaultCredentialFile();
   const store = new LocalConnectorCredentialStore({ filename: credentialFile });
   const current = await store.load();
-  if (current && Date.parse(current.connector_expires_at) > Date.now()) {
+  const currentIsValid = current && Date.parse(current.connector_expires_at) > Date.now();
+  if (currentIsValid && current.receiver_origin === receiver) {
     if (ui.interactive) {
       ui.success("Already connected", `${current.connector_id} · ${current.receiver_origin}`);
       ui.info("Next", "run `re-entry start` to wait for approved work");
@@ -237,6 +263,10 @@ async function connect(flags, ui, options = {}) {
     return current;
   }
 
+  if (currentIsValid && ui.interactive) {
+    ui.warning("Receiver changed", `${current.receiver_origin} → ${receiver}; approve this Mac again`);
+  }
+
   if (ui.interactive) {
     ui.step("Re-entry", receiver);
     ui.step("This Mac", flags["device-name"] ?? defaultDeviceName());
@@ -318,14 +348,54 @@ async function status(flags, ui) {
   }
 }
 
+async function stop(flags, ui) {
+  if (ui.interactive) {
+    ui.begin("Stop the Connector", "Pause background delivery without removing your account connection");
+  }
+  const result = await stopMacConnectorService();
+  if (ui.interactive) {
+    if (!result.supported) ui.warning("Platform", "background service control currently supports macOS only");
+    else if (result.stopped) ui.success("Stopped", "the background Connector is no longer running");
+    else ui.info("Already stopped", "no running background Connector was found");
+  } else {
+    process.stdout.write(`${JSON.stringify({
+      event: "connector_stopped",
+      supported: result.supported,
+      stopped: result.stopped,
+    })}\n`);
+  }
+}
+
+async function uninstall(flags, ui) {
+  if (ui.interactive) {
+    ui.begin("Uninstall Re-entry", "Stop the Connector and remove only its local service data");
+    ui.warning("This removes", "the LaunchAgent, saved Connector credential, and Connector logs");
+    await askForUninstallConfirmation();
+  } else if (flags.yes !== true) {
+    throw cliFailure("connector_uninstall_confirmation_required");
+  }
+  const result = await uninstallMacConnectorService({
+    credentialFile: flags["credential-file"] ?? defaultCredentialFile(),
+  });
+  if (ui.interactive) {
+    ui.success("Uninstalled", "local Connector service data was removed");
+    ui.info("Package", "remove the npm package separately with `npm uninstall --global @4xeoz/re-entry`");
+  } else {
+    process.stdout.write(`${JSON.stringify({
+      event: "connector_uninstalled",
+      supported: result.supported,
+      removed_paths: result.removedPaths,
+    })}\n`);
+  }
+}
+
 async function install(flags, ui) {
   if (ui.interactive) {
     ui.begin("Install Re-entry", "Check Codex, connect your account, then start at login");
+    ui.info("Setup", "choose a workspace, approve this Mac, then leave the Connector running");
   }
-  const runtimeFlags = {
-    ...flags,
-    "codex-cd": flags["codex-cd"] ?? process.cwd(),
-  };
+  const runtimeFlags = await withWorkspaceDirectory(flags, ui);
+  if (ui.interactive) ui.info("Receiver", runtimeFlags.receiver ?? DEFAULT_RECEIVER_ORIGIN);
   const readiness = inspectReadiness(runtimeFlags);
   showReadiness(readiness, ui);
   const credentials = await connect(runtimeFlags, ui, { quietHeader: true });
@@ -340,6 +410,7 @@ async function install(flags, ui) {
     ui.stopWait("Installed", "Re-entry will start automatically when you log in");
     ui.success("Account", credentials.connector_id);
     ui.info("Logs", service.stdoutPath);
+    ui.info("Commands", "status to inspect · stop to pause · uninstall to remove local setup");
     ui.info("You are done", "the Connector now waits in the background");
   } else {
     process.stdout.write(`${JSON.stringify({
@@ -356,10 +427,7 @@ async function start(flags, ui) {
   if (ui.interactive) {
     ui.begin("Re-entry is starting", "Connect once, then wait quietly for work you approve");
   }
-  const runtimeFlags = {
-    ...flags,
-    "codex-cd": flags["codex-cd"] ?? process.cwd(),
-  };
+  const runtimeFlags = await withWorkspaceDirectory(flags, ui);
   const readiness = inspectReadiness(runtimeFlags);
   showReadiness(readiness, ui);
   if (!ui.interactive) {
@@ -572,7 +640,7 @@ function parseArguments(argumentsList) {
     const value = rest[index];
     if (!value.startsWith("--")) throw cliFailure("connector_argument_invalid");
     const name = value.slice(2);
-    if (name === "json") {
+    if (name === "json" || name === "yes") {
       if (Object.hasOwn(flags, name)) throw cliFailure("connector_argument_invalid");
       flags[name] = true;
       continue;
@@ -591,6 +659,8 @@ function validateCommandFlags(command, flags) {
     pair: new Set(["receiver", "code", "credential-file", "json"]),
     connect: new Set(["receiver", "device-name", "credential-file", "json"]),
     status: new Set(["credential-file", "codex-cd", "codex-binary", "json"]),
+    stop: new Set(["json"]),
+    uninstall: new Set(["credential-file", "yes", "json"]),
     install: new Set([
       "receiver",
       "device-name",
@@ -708,6 +778,17 @@ async function askForPairingCode(ui) {
   }
 }
 
+async function askForUninstallConfirmation() {
+  if (process.stdin.isTTY !== true) throw cliFailure("connector_uninstall_confirmation_required");
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await readline.question("  Type DELETE to remove local Connector data: ");
+    if (answer.trim() !== "DELETE") throw cliFailure("connector_uninstall_confirmation_required");
+  } finally {
+    readline.close();
+  }
+}
+
 function errorHint(error) {
   const hints = {
     connector_codex_cd_missing: "pass --codex-cd /absolute/path/to/your/Host-project",
@@ -726,6 +807,8 @@ function errorHint(error) {
     connector_poll_interval_invalid: "use a polling interval between 1000 and 60000 milliseconds",
     connector_max_errors_invalid: "use a maximum error count between 1 and 20",
     connector_service_load_failed: "run `re-entry install` again; if it still fails, inspect the Connector error log",
+    connector_uninstall_confirmation_required: "run uninstall interactively and type DELETE, or pass `--yes` in a deliberate script",
+    connector_service_stop_failed: "check the Connector status and try `re-entry stop` again",
   };
   return hints[error?.code] ?? "check the Receiver address and try again";
 }

package/src/terminal-ui.mjs

@@ -8,6 +8,19 @@ const YELLOW = "\u001b[33m";
 const RED = "\u001b[31m";
 const CYAN = "\u001b[36m";
 const SPINNER_FRAMES = ["·", "✦", "✧", "✦"];
+const REENTRY_ASCII = [
+  "  ____  _____       _____ _   _ _____ ____  __   __",
+  " |  _ \\| ____|     | ____| \\ | | ____|  _ \\ \\ \\ / /",
+  " | |_) |  _| _____ |  _| |  \\| |  _| | |_) | \\ V /",
+  " |  _ <| |__|_____| | |___| |\\  | |___|  _ <   | |",
+  " |_| \\_\\_____|     |_____|_| \\_|_____|_| \\_\\  |_|",
+];
+const REENTRY_PANEL = [
+  "  +-----------------------------------------------+",
+  "  |                 RE-ENTRY                     |",
+  "  |              LOCAL CONNECTOR                 |",
+  "  +-----------------------------------------------+",
+];
 
 /**
  * Small dependency-free terminal presentation for the Local Connector CLI.
@@ -41,6 +54,10 @@ export function createTerminalUi(options = {}) {
     begin(title, subtitle) {
       if (!interactive) return;
       write("");
+      for (const line of REENTRY_ASCII) write(style(line, BOLD));
+      write("");
+      for (const line of REENTRY_PANEL) write(style(line, BOLD));
+      write("");
       write(`  ${style("RE-ENTRY", BOLD)} ${style("LOCAL CONNECTOR", DIM)}`);
       write(`  ${style(title, BOLD)}`);
       if (subtitle) write(`  ${style(subtitle, DIM)}`);

package/src/workspace-picker.mjs

@@ -0,0 +1,125 @@
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { emitKeypressEvents } from "node:readline";
+import process from "node:process";
+
+const MAX_VISIBLE_DIRECTORIES = 40;
+
+/**
+ * Let an interactive user choose the directory passed to Codex as its workspace.
+ * The picker only selects existing directories; it never creates or deletes files.
+ */
+export async function chooseWorkspaceDirectory(options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  if (input.isTTY !== true || output.isTTY !== true || typeof input.setRawMode !== "function") {
+    return null;
+  }
+
+  const homeDirectory = resolve(options.homeDirectory ?? homedir());
+  const preferredDirectory = resolve(options.startDirectory ?? process.cwd());
+  let current = homeDirectory;
+  const shortcuts = shortcutDirectories(homeDirectory);
+  let selected = 0;
+  const wasRaw = Boolean(input.isRaw);
+  emitKeypressEvents(input);
+  input.setRawMode(true);
+
+  try {
+    while (true) {
+      const directories = await readableDirectories(current);
+      const choices = createChoices({ current, homeDirectory, preferredDirectory, shortcuts, directories });
+      selected = Math.min(selected, choices.length - 1);
+      renderPicker(output, current, choices, selected);
+      const key = await readKey(input);
+      if (key.name === "up") {
+        selected = (selected - 1 + choices.length) % choices.length;
+      } else if (key.name === "down") {
+        selected = (selected + 1) % choices.length;
+      } else if (key.name === "return" || key.name === "enter") {
+        const choice = choices[selected];
+        if (choice.action === "use") return choice.path;
+        if (choice.action === "cancel") {
+          throw pickerFailure("workspace_selection_cancelled", "Workspace selection was cancelled");
+        }
+        current = choice.path;
+        selected = 0;
+      } else if (key.name === "escape" || key.sequence === "\u0003") {
+        throw pickerFailure("workspace_selection_cancelled", "Workspace selection was cancelled");
+      }
+    }
+  } finally {
+    input.setRawMode(wasRaw);
+    output.write("\n");
+  }
+}
+
+function createChoices({ current, homeDirectory, preferredDirectory, shortcuts, directories }) {
+  const choices = [];
+  if (current === homeDirectory && preferredDirectory !== homeDirectory) {
+    choices.push({ label: `Use current folder  ${preferredDirectory}`, action: "use", path: preferredDirectory });
+  }
+  choices.push({ label: `Use this folder  ${current}`, action: "use", path: current });
+  if (current === homeDirectory) {
+    for (const shortcut of shortcuts) {
+      if (directories.some((directory) => directory.path === shortcut.path)) {
+        choices.push({ label: `Open ${shortcut.label}`, action: "open", path: shortcut.path });
+      }
+    }
+  }
+  const parent = dirname(current);
+  if (parent !== current) choices.push({ label: `Go up  ${parent}`, action: "open", path: parent });
+  const shortcutPaths = new Set(shortcuts.map((shortcut) => shortcut.path));
+  for (const directory of directories) {
+    if (current === homeDirectory && shortcutPaths.has(directory.path)) continue;
+    choices.push({ label: `Open ${directory.name}`, action: "open", path: directory.path });
+  }
+  choices.push({ label: "Cancel", action: "cancel", path: null });
+  return choices;
+}
+
+async function readableDirectories(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .slice(0, MAX_VISIBLE_DIRECTORIES)
+    .map((entry) => ({ name: entry.name, path: join(directory, entry.name) }));
+}
+
+function shortcutDirectories(home) {
+  return [
+    { label: "Desktop", path: join(home, "Desktop") },
+    { label: "Documents", path: join(home, "Documents") },
+    { label: "Downloads", path: join(home, "Downloads") },
+    { label: "Home", path: home },
+  ];
+}
+
+function renderPicker(output, current, choices, selected) {
+  output.write("\u001b[2J\u001b[H");
+  output.write("RE-ENTRY WORKSPACE\n\n");
+  output.write("Choose the folder where Codex will work. Files stay inside this workspace.\n");
+  output.write(`Current folder: ${current}\n\n`);
+  for (let index = 0; index < choices.length; index += 1) {
+    output.write(`${index === selected ? "❯" : " "} ${choices[index].label}\n`);
+  }
+  output.write("\n↑/↓ Move   Enter Select   Esc Cancel");
+}
+
+function readKey(input) {
+  return new Promise((resolveKey) => {
+    function onKeypress(_sequence, key = {}) {
+      input.removeListener("keypress", onKeypress);
+      resolveKey(key);
+    }
+    input.on("keypress", onKeypress);
+  });
+}
+
+function pickerFailure(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}