@4xeoz/re-entry 0.2.5 → 0.2.6

package/README.md

@@ -16,6 +16,16 @@ Codex may read and write.
 npx @4xeoz/re-entry install
 ```
 
+`npx` runs a temporary copy, so it does not leave a permanent shell command behind. Install the
+small CLI globally once if you want to use `re-entry` from any folder afterward:
+
+```sh
+npm install --global @4xeoz/re-entry
+```
+
+The package installs both `re-entry` and the older `reentry` spelling; `re-entry` is the documented
+command.
+
 This uses the deployed Re-entry Cloud Receiver by default:
 `https://reentry-cloud.vercel.app`.
 
@@ -74,11 +84,13 @@ preview.
 
 ```sh
 re-entry status
+re-entry listen
 re-entry --help
 ```
 
 The status view checks the local authorization, background job, Receiver reachability, Node, and
-Codex. Useful development commands are:
+Codex. `listen` watches the already-running background Connector and displays new activity until
+you press Ctrl+C; it does not start a competing second poller. Useful development commands are:
 
 ```sh
 re-entry doctor --codex-cd /absolute/path/to/project
@@ -87,6 +99,15 @@ re-entry claim-once --codex-cd /absolute/path/to/project
 re-entry start --codex-cd /absolute/path/to/project
 ```
 
+Test the local Codex handoff without waiting for Cloud work:
+
+```sh
+re-entry test "Reply with: Re-entry is working."
+```
+
+This starts one fresh local Codex process through the same adapter seam used by real deliveries. It
+does not create a Grant, claim Receiver work, or prove the browser/WebMCP return path.
+
 To pause or remove the local Connector:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "description": "Outbound Local Connector process for the Re-entry Core local preview.",
   "publishConfig": {
@@ -10,7 +10,10 @@
     "README.md",
     "src"
   ],
-  "bin": "./src/main.mjs",
+  "bin": {
+    "re-entry": "./src/main.mjs",
+    "reentry": "./src/main.mjs"
+  },
   "exports": {
     ".": "./src/index.mjs",
     "./connector": "./src/local-connector.mjs",

package/src/activity-monitor.mjs

@@ -0,0 +1,107 @@
+import { open, stat } from "node:fs/promises";
+
+const MAX_LINE_BYTES = 16 * 1_024;
+const MAX_READ_BYTES = 64 * 1_024;
+
+/**
+ * Follow new JSON events written by the installed background Connector.
+ * The monitor starts at the end of each file and never starts another Connector poller.
+ */
+export async function followConnectorActivity(options) {
+  requireOptions(options);
+  const cursors = await Promise.all(options.paths.map(initializeCursor));
+  const pollIntervalMs = options.pollIntervalMs ?? 350;
+  if (!Number.isSafeInteger(pollIntervalMs) || pollIntervalMs < 10 || pollIntervalMs > 5_000) {
+    throw new TypeError("Activity monitor poll interval is invalid");
+  }
+
+  while (!options.signal.aborted) {
+    for (const cursor of cursors) {
+      await readNewEvents(cursor, options.onEvent);
+    }
+    await waitForNextRead(pollIntervalMs, options.signal);
+  }
+}
+
+async function initializeCursor(path) {
+  try {
+    const metadata = await stat(path);
+    return { path, offset: metadata.size, pending: "" };
+  } catch (error) {
+    if (error?.code === "ENOENT") return { path, offset: 0, pending: "" };
+    throw error;
+  }
+}
+
+async function readNewEvents(cursor, onEvent) {
+  let handle;
+  try {
+    handle = await open(cursor.path, "r");
+    const metadata = await handle.stat();
+    if (metadata.size < cursor.offset) {
+      cursor.offset = 0;
+      cursor.pending = "";
+    }
+    if (metadata.size === cursor.offset) return;
+    const length = Math.min(metadata.size - cursor.offset, MAX_READ_BYTES);
+    const buffer = Buffer.alloc(length);
+    const { bytesRead } = await handle.read(buffer, 0, length, cursor.offset);
+    cursor.offset += bytesRead;
+    const lines = `${cursor.pending}${buffer.subarray(0, bytesRead).toString("utf8")}`.split("\n");
+    cursor.pending = lines.pop() ?? "";
+    if (Buffer.byteLength(cursor.pending, "utf8") > MAX_LINE_BYTES) cursor.pending = "";
+    for (const line of lines) {
+      const event = parseEvent(line);
+      if (event) await onEvent(event);
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  } finally {
+    await handle?.close();
+  }
+}
+
+function parseEvent(line) {
+  if (line.length === 0 || Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) return null;
+  try {
+    const value = JSON.parse(line);
+    if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.event !== "string") {
+      return null;
+    }
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+function waitForNextRead(milliseconds, signal) {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, milliseconds);
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+    signal.addEventListener("abort", done, { once: true });
+  });
+}
+
+function requireOptions(options) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new TypeError("Activity monitor options are required");
+  }
+  const fields = Object.keys(options);
+  if (fields.some((field) => !["paths", "signal", "onEvent", "pollIntervalMs"].includes(field))) {
+    throw new TypeError("Activity monitor options contain an unsupported field");
+  }
+  if (
+    !Array.isArray(options.paths) ||
+    options.paths.length !== 2 ||
+    options.paths.some((path) => typeof path !== "string" || path.length === 0) ||
+    !(options.signal instanceof AbortSignal) ||
+    typeof options.onEvent !== "function"
+  ) {
+    throw new TypeError("Activity monitor options are invalid");
+  }
+}

package/src/codex-exec-adapter.mjs

@@ -22,6 +22,7 @@ const MIN_COMMAND_TIMEOUT_MS = 100;
 const MAX_COMMAND_TIMEOUT_MS = 60_000;
 const MAX_REFERENCE_BYTES = 4 * 1_024;
 const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const PROMPT_CONTROL_CHARACTER_PATTERN = /[\u0000-\u0009\u000b-\u001f\u007f]/;
 
 /**
  * Create the fresh-session Codex adapter that lives inside the Local Connector process.
@@ -54,11 +55,11 @@ export function createCodexExecAdapter(options) {
         return activationResult(activation, "rejected", "activation_rejected", null);
       }
 
-      await runCodexExec({
+      await runCodexPrompt({
         executable,
         workingDirectory,
         prompt: buildContinuationPrompt(activation),
-        timeoutMs: commandTimeoutMs,
+        commandTimeoutMs,
         spawnCommand,
       });
       return activationResult(
@@ -71,6 +72,30 @@ export function createCodexExecAdapter(options) {
   });
 }
 
+/**
+ * Run one local prompt through the same fresh Codex process seam used by real activations.
+ * This helper carries no Receiver authority and is intended only for an explicit local smoke test.
+ */
+export async function runCodexPrompt(options) {
+  requireExactRecord(
+    options,
+    ["workingDirectory", "prompt", "executable", "commandTimeoutMs", "spawnCommand"],
+    ["workingDirectory", "prompt"],
+    "Codex prompt options",
+  );
+  const workingDirectory = validateCodexWorkingDirectory(options.workingDirectory);
+  const executable = options.executable === undefined
+    ? discoverCodexExecutable()
+    : requireReference(options.executable, "Codex executable");
+  const prompt = requirePrompt(options.prompt);
+  const timeoutMs = requireTimeout(options.commandTimeoutMs ?? 60_000);
+  const spawnCommand = options.spawnCommand ?? spawn;
+  if (typeof spawnCommand !== "function") {
+    throw new TypeError("Codex prompt spawnCommand must be a function");
+  }
+  await runCodexExec({ executable, workingDirectory, prompt, timeoutMs, spawnCommand });
+}
+
 function buildContinuationPrompt(activation) {
   return [
     "You are a Re-entry continuation agent.",
@@ -183,6 +208,19 @@ function requireReference(value, label) {
   return value;
 }
 
+function requirePrompt(value) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.trim() !== value ||
+    Buffer.byteLength(value, "utf8") > MAX_REFERENCE_BYTES ||
+    PROMPT_CONTROL_CHARACTER_PATTERN.test(value)
+  ) {
+    throw new TypeError("Codex prompt is invalid");
+  }
+  return value;
+}
+
 function requireExactRecord(value, allowedFields, requiredFields, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new TypeError(`${label} must be an object`);

package/src/main.mjs

@@ -9,7 +9,8 @@ import { randomBytes } from "node:crypto";
 import process from "node:process";
 
 import { LocalConnectorClient } from "@webmcp-challenge/reentry-core/local-connector-client";
-import { createCodexExecAdapter } from "./codex-exec-adapter.mjs";
+import { followConnectorActivity } from "./activity-monitor.mjs";
+import { createCodexExecAdapter, runCodexPrompt } from "./codex-exec-adapter.mjs";
 import {
   discoverCodexExecutable,
   requireSupportedNode,
@@ -47,8 +48,8 @@ async function main() {
       process.stdout.write(`${CONNECTOR_VERSION}\n`);
       return;
     }
-    const { command, flags } = parseArguments(argumentsList);
-    validateCommandFlags(command, flags);
+    const { command, flags, positionals } = parseArguments(argumentsList);
+    validateCommandFlags(command, flags, positionals);
     ui = createTerminalUi({ interactive: flags.json !== true && process.stdout.isTTY === true });
     requireSupportedNode();
     if (command === "doctor") {
@@ -67,6 +68,14 @@ async function main() {
       await status(flags, ui);
       return;
     }
+    if (command === "listen") {
+      await listen(flags, ui);
+      return;
+    }
+    if (command === "test") {
+      await testCodex(flags, positionals, ui);
+      return;
+    }
     if (command === "stop") {
       await stop(flags, ui);
       return;
@@ -111,12 +120,14 @@ Connect this Mac once, then receive approved work in Codex in the background.
 
 Usage:
   re-entry install                                      Recommended first run
-  re-entry status                                          Check the connection
-  re-entry start                                          Run in this terminal
+  re-entry listen                                      Watch live activity
+  re-entry test "Reply with hello"                     Test Codex locally
 
 Commands:
   install      Check this Mac, connect the Re-entry account, and start at login
   status       Show account, Receiver, service, Node.js, and Codex readiness
+  listen       Watch the background Connector until you press Ctrl+C
+  test         Start one fresh local Codex session with the supplied prompt
   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
@@ -134,6 +145,7 @@ Common options:
   --help                 Show this help
   --version              Show the installed version
 
+Both commands are installed: re-entry and reentry.
 The Connector opens no inbound port. Host keys never belong on this Mac.
 `);
 }
@@ -361,6 +373,7 @@ async function status(flags, ui) {
       ui.next("re-entry status", "Check again when the Re-entry Cloud service is available.");
     } else {
       ui.complete("Everything looks good", "Re-entry is ready for approved work.");
+      ui.next("re-entry listen", "Watch live activity. Press Ctrl+C when you are done.");
     }
   } else {
     process.stdout.write(`${JSON.stringify({
@@ -378,6 +391,109 @@ async function status(flags, ui) {
   }
 }
 
+async function listen(flags, ui) {
+  if (ui.interactive) {
+    ui.begin("Live activity", "Watch the background Connector. Ctrl+C closes this view.");
+  }
+  const service = await inspectMacConnectorService();
+  const credentials = await new LocalConnectorCredentialStore({
+    filename: defaultCredentialFile(),
+  }).load();
+  if (!service.running || !credentials) {
+    if (ui.interactive) {
+      if (!credentials) ui.warning("Account", "not connected");
+      if (!service.running) ui.warning("Background", "not running");
+      ui.next("re-entry install", "Finish setup and start the background Connector.");
+    } else {
+      process.stdout.write(`${JSON.stringify({
+        event: "connector_listener_unavailable",
+        connected: Boolean(credentials),
+        service_running: service.running,
+      })}\n`);
+    }
+    return;
+  }
+
+  if (ui.interactive) {
+    ui.success("Background", "running");
+    ui.success("Account", "connected");
+    ui.wait("Listening for approved work…");
+  } else {
+    process.stdout.write('{"event":"connector_listener_started"}\n');
+  }
+
+  const stopSignal = createStopSignal();
+  try {
+    await followConnectorActivity({
+      paths: defaultConnectorLogFiles(),
+      signal: stopSignal.signal,
+      onEvent(event) {
+        if (ui.interactive) reportLiveActivity(event, ui);
+        else process.stdout.write(`${JSON.stringify(event)}\n`);
+      },
+    });
+  } finally {
+    stopSignal.close();
+    if (ui.interactive) {
+      ui.stopWait("Live view closed", "the background Connector is still running", "info");
+    } else {
+      process.stdout.write('{"event":"connector_listener_stopped"}\n');
+    }
+  }
+}
+
+async function testCodex(flags, positionals, ui) {
+  const prompt = requireTestPrompt(positionals);
+  const runtimeFlags = await withWorkspaceDirectory(flags, ui);
+  const readiness = inspectReadiness(runtimeFlags);
+  if (ui.interactive) {
+    ui.begin("Test Codex", "Run one local prompt through the Re-entry Codex adapter.");
+    ui.success("Codex", "ready");
+    ui.success("Workspace", readiness.workingDirectory);
+    ui.info("Prompt", prompt);
+    ui.wait("Starting a fresh Codex session…");
+  }
+  await runCodexPrompt({
+    workingDirectory: readiness.workingDirectory,
+    executable: readiness.installation.executable,
+    prompt,
+    commandTimeoutMs: readBoundedNumber(
+      flags["activation-timeout"] ?? 60_000,
+      100,
+      60_000,
+      "connector_activation_timeout_invalid",
+    ),
+  });
+  if (ui.interactive) {
+    ui.stopWait("Codex", "completed the local test");
+    ui.complete("Test passed", "The same fresh-session process seam is ready for Re-entry work.");
+    ui.next("re-entry listen", "Watch the background Connector for approved work.");
+  } else {
+    process.stdout.write('{"event":"connector_codex_test_passed"}\n');
+  }
+}
+
+function reportLiveActivity(event, ui) {
+  if (event.event === "connector_waiting") return;
+  if (event.event === "connector_activation_result") {
+    const accepted = event.outcome === "accepted";
+    ui.stopWait(
+      accepted ? "Work received" : "Work finished",
+      accepted ? "a fresh Codex session was started" : String(event.outcome ?? "unknown"),
+      accepted ? "success" : "warning",
+    );
+  } else if (event.event === "connector_poll_failed" || event.event === "local_connector_failed") {
+    ui.stopWait("Connection interrupted", "Re-entry is retrying", "warning");
+  } else if (event.event === "connector_ready") {
+    ui.stopWait("Connector", "ready", "success");
+  } else if (event.event === "connector_stopped") {
+    ui.stopWait("Background", "stopped", "warning");
+  } else {
+    ui.stopWait("Activity", event.event.replaceAll("_", " "), "info");
+  }
+  ui.wait("Listening for approved work…");
+}
+
 async function stop(flags, ui) {
   if (ui.interactive) {
     ui.begin("Stop the Connector", "Pause background delivery without removing your account connection");
@@ -442,7 +558,7 @@ async function install(flags, ui) {
   if (ui.interactive) {
     ui.stopWait("Background", "running at login");
     ui.complete("You're all set", "Re-entry is connected and waiting for approved work.");
-    ui.next("re-entry status", "Check the connection at any time.");
+    ui.next("re-entry listen", "Watch live activity. Press Ctrl+C when you are done.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_service_installed",
@@ -668,9 +784,14 @@ function parseArguments(argumentsList) {
     ...(hasExplicitCommand ? argumentsList.slice(commandIndex + 1) : argumentsList.slice(commandIndex)),
   ];
   const flags = {};
+  const positionals = [];
   for (let index = 0; index < rest.length; index += 1) {
     const value = rest[index];
-    if (!value.startsWith("--")) throw cliFailure("connector_argument_invalid");
+    if (!value.startsWith("--")) {
+      if (command !== "test") throw cliFailure("connector_argument_invalid");
+      positionals.push(value);
+      continue;
+    }
     const name = value.slice(2);
     if (name === "json" || name === "yes") {
       if (Object.hasOwn(flags, name)) throw cliFailure("connector_argument_invalid");
@@ -682,15 +803,17 @@ function parseArguments(argumentsList) {
     flags[name] = next;
     index += 1;
   }
-  return { command, flags };
+  return { command, flags, positionals };
 }
 
-function validateCommandFlags(command, flags) {
+function validateCommandFlags(command, flags, positionals) {
   const allowedByCommand = {
     doctor: new Set(["codex-binary", "codex-cd", "json"]),
     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"]),
+    listen: new Set(["json"]),
+    test: new Set(["codex-cd", "codex-binary", "activation-timeout", "json"]),
     stop: new Set(["json"]),
     uninstall: new Set(["credential-file", "yes", "json"]),
     install: new Set([
@@ -725,7 +848,11 @@ function validateCommandFlags(command, flags) {
     ]),
   };
   const allowed = allowedByCommand[command];
-  if (!allowed || Object.keys(flags).some((name) => !allowed.has(name))) {
+  if (
+    !allowed ||
+    Object.keys(flags).some((name) => !allowed.has(name)) ||
+    (command !== "test" && positionals.length > 0)
+  ) {
     throw cliFailure("connector_argument_invalid");
   }
 }
@@ -740,6 +867,14 @@ function defaultCredentialFile() {
   return join(homedir(), ".webmcp-connector", "credentials.json");
 }
 
+function defaultConnectorLogFiles() {
+  const stateDirectory = join(homedir(), ".webmcp-connector");
+  return [
+    join(stateDirectory, "connector.log"),
+    join(stateDirectory, "connector-error.log"),
+  ];
+}
+
 function defaultDeviceName() {
   const value = hostname().trim();
   return value.length >= 2 && Buffer.byteLength(value, "utf8") <= 80
@@ -755,6 +890,23 @@ function displayReceiver(origin) {
   }
 }
 
+function requireTestPrompt(positionals) {
+  if (!Array.isArray(positionals) || positionals.length !== 1) {
+    throw cliFailure("connector_test_prompt_missing");
+  }
+  const value = positionals[0];
+  if (
+    typeof value !== "string" ||
+    value.trim() !== value ||
+    value.length === 0 ||
+    Buffer.byteLength(value, "utf8") > 4 * 1_024 ||
+    /[\u0000-\u001f\u007f]/.test(value)
+  ) {
+    throw cliFailure("connector_test_prompt_invalid");
+  }
+  return value;
+}
+
 function readBoundedNumber(value, minimum, maximum, code) {
   const number = typeof value === "number" ? value : Number(value);
   if (!Number.isSafeInteger(number) || number < minimum || number > maximum) {
@@ -853,6 +1005,9 @@ function errorHint(error) {
     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",
+    connector_test_prompt_missing: "use `re-entry test \"Reply with: Re-entry is working.\"`",
+    connector_test_prompt_invalid: "use one short, single-line prompt inside quotes",
+    connector_activation_timeout_invalid: "use an activation timeout between 100 and 60000 milliseconds",
   };
   return hints[error?.code] ?? "check the Receiver address and try again";
 }

package/src/terminal-ui.mjs

@@ -11,8 +11,11 @@ const SPINNER_FRAMES = ["·", "✦", "✧", "✦"];
 const RULE = "  ─────────────────────────────────────────────";
 
 export const REENTRY_WORDMARK = Object.freeze([
-  "  █▀█ █▀▀   █▀▀ █▄░█ ▀█▀ █▀█ █▄█",
-  "  █▀▄ ██▄ ▀ ██▄ █░▀█ ░█░ █▀▄ ░█░",
+  "   ____  _____      _____ _   _ _____ ______   __",
+  "  |  _ \\| ____|    | ____| \\ | |_   _|  _ \\ \\ / /",
+  "  | |_) |  _| _____|  _| |  \\| | | | | |_) | \\ V /",
+  "  |  _ <| |__|_____| |___| |\\  | | | |  _ <   | |",
+  "  |_| \\_\\_____|    |_____|_| \\_| |_| |_| \\_\\  |_|",
 ]);
 
 /**