@4xeoz/re-entry 0.2.17 → 0.2.19

package/README.md

@@ -19,7 +19,7 @@ Requirements: macOS, Node.js 24+, Codex installed and signed in, and an absolute
 Codex may read and write.
 
 ```sh
-npx --yes --package=@4xeoz/re-entry re-entry install
+npx --yes @4xeoz/re-entry install
 ```
 
 `npx` runs a temporary copy, so it does not leave a permanent shell command behind. Install the
@@ -30,8 +30,8 @@ npm install --global @4xeoz/re-entry
 ```
 
 The package installs both `re-entry` and the older `reentry` spelling; `re-entry` is the documented
-command. If you keep using the temporary `npx` form, run later commands with the same executable
-prefix, for example `npx --yes --package=@4xeoz/re-entry re-entry status`.
+command. If you keep using the temporary `npx` form, run later commands with the same short
+executable prefix, for example `npx --yes @4xeoz/re-entry status`.
 
 The CLI defaults to the current Cloud Receiver v2 preview at
 `https://cloud-receiver-delta.vercel.app`. Override it with `--receiver` or
@@ -42,13 +42,14 @@ The interactive CLI first offers Desktop, the current folder, or a small folder
 with ↑/↓ and Enter. If you want to skip the picker, pass the workspace directly:
 
 ```sh
-npx --yes --package=@4xeoz/re-entry re-entry install \
+npx --yes @4xeoz/re-entry install \
   --codex-cd /absolute/path/to/your/project
 ```
 
-The guided screen stays intentionally small: **Workspace → System check → Connect Re-entry**. It
-shows one executable next command when setup finishes; internal Connector IDs, credential paths, and
-log paths stay out of the normal success screen.
+The guided screen stays intentionally small: **Workspace → System check → Connect Re-entry**. On
+success it shows a compact copy-paste command catalog for status, activity, testing, account
+lifecycle, and local diagnostics. Internal Connector IDs, credential paths, and log paths stay out
+of the normal success screen.
 
 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
@@ -66,7 +67,7 @@ re-entry install \
 Use `--receiver` to select an accepted replacement Receiver, such as a local historical preview:
 
 ```sh
-npx --yes --package=@4xeoz/re-entry re-entry install \
+npx --yes @4xeoz/re-entry install \
   --receiver http://127.0.0.1:43224 \
   --codex-cd /absolute/path/to/your/project
 ```
@@ -104,12 +105,12 @@ re-entry uninstall
 If you used the temporary `npx` invocation:
 
 ```sh
-npx --yes --package=@4xeoz/re-entry re-entry status
-npx --yes --package=@4xeoz/re-entry re-entry listen
-npx --yes --package=@4xeoz/re-entry re-entry --help
-npx --yes --package=@4xeoz/re-entry re-entry stop
-npx --yes --package=@4xeoz/re-entry re-entry disconnect
-npx --yes --package=@4xeoz/re-entry re-entry uninstall
+npx --yes @4xeoz/re-entry status
+npx --yes @4xeoz/re-entry listen
+npx --yes @4xeoz/re-entry --help
+npx --yes @4xeoz/re-entry stop
+npx --yes @4xeoz/re-entry disconnect
+npx --yes @4xeoz/re-entry uninstall
 ```
 
 The status view checks the local authorization, background job, Receiver reachability, Node, and
@@ -119,16 +120,16 @@ the already-running background Connector and displays new activity until you pre
 not start a competing second poller. Useful development commands are:
 
 ```sh
-npx --yes --package=@4xeoz/re-entry re-entry doctor --codex-cd /absolute/path/to/project
-npx --yes --package=@4xeoz/re-entry re-entry connect --receiver http://127.0.0.1:43224
-npx --yes --package=@4xeoz/re-entry re-entry claim-once --codex-cd /absolute/path/to/project
-npx --yes --package=@4xeoz/re-entry re-entry start --codex-cd /absolute/path/to/project
+npx --yes @4xeoz/re-entry doctor --codex-cd /absolute/path/to/project
+npx --yes @4xeoz/re-entry connect --receiver http://127.0.0.1:43224
+npx --yes @4xeoz/re-entry claim-once --codex-cd /absolute/path/to/project
+npx --yes @4xeoz/re-entry start --codex-cd /absolute/path/to/project
 ```
 
 Test the local Codex handoff without waiting for Cloud work:
 
 ```sh
-npx --yes --package=@4xeoz/re-entry re-entry test "Reply with: Re-entry is working."
+npx --yes @4xeoz/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
@@ -137,12 +138,16 @@ underlying direct `codex exec` command. It does not create a Grant, claim Receiv
 Desktop UI thread, browser, or WebMCP return path. If it times out, run the equivalent direct
 `codex exec` command to inspect Codex's own output; the test does not contact the Receiver.
 
+The one-shot test allows up to one hour by default. Override it with
+`--activation-timeout <milliseconds>` when needed. Background delivery keeps its separate
+60-second adapter bound.
+
 To pause or remove the local Connector:
 
 ```sh
-npx --yes --package=@4xeoz/re-entry re-entry stop
-npx --yes --package=@4xeoz/re-entry re-entry disconnect
-npx --yes --package=@4xeoz/re-entry re-entry uninstall
+npx --yes @4xeoz/re-entry stop
+npx --yes @4xeoz/re-entry disconnect
+npx --yes @4xeoz/re-entry uninstall
 ```
 
 `stop` pauses the macOS background service and keeps the account connection. `uninstall` requires
@@ -174,10 +179,10 @@ 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 Connector executable. Run `npx --yes --package=@4xeoz/re-entry re-entry install` with an absolute
+or newer and locate the Connector executable. Run `npx --yes @4xeoz/re-entry install` with an absolute
 project directory. Let the human create or sign in to a Re-entry account, click Pair this Mac, and
 enter the code in the CLI; never copy browser cookies, organization keys, Connector tokens, or private keys
-into chat, logs, source files, or git. Finish by running `npx --yes --package=@4xeoz/re-entry re-entry status`
+into chat, logs, source files, or git. Finish by running `npx --yes @4xeoz/re-entry status`
 and report the bounded results without claiming Browser/WebMCP or production deployment.
 ```
 
@@ -250,9 +255,9 @@ npm publish --access public
 NPM versions are immutable: if the target version has already been published, bump it before
 publishing with `npm version patch --no-git-tag-version`.
 
-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`. The command uses the built-in preview Receiver unless `--receiver` or
+After publishing, users run `npx --yes @4xeoz/re-entry install`. The executable itself is still
+named `re-entry`; the short package form works with the scoped package. The command uses the
+built-in preview Receiver unless `--receiver` or
 `REENTRY_RECEIVER_ORIGIN` overrides it.
 
 A temporary `npx` invocation does not add `re-entry` to your shell `PATH`. If you prefer the shorter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "type": "module",
   "description": "Outbound Local Connector process for Re-entry Core; uses the Cloud Receiver v2 preview by default with an explicit override for other accepted origins.",
   "publishConfig": {

package/src/codex-exec-adapter.mjs

@@ -10,6 +10,8 @@ import {
 } from "./codex-discovery.mjs";
 
 export const CODEX_EXEC_ADAPTER_ID = "codex_exec_local";
+export const DEFAULT_CODEX_PROMPT_TIMEOUT_MS = 3_600_000;
+export const MAX_CODEX_PROMPT_TIMEOUT_MS = 3_600_000;
 
 const OPTION_FIELDS = Object.freeze([
   "workingDirectory",
@@ -89,7 +91,10 @@ export async function runCodexPrompt(options) {
     ? discoverCodexExecutable()
     : requireReference(options.executable, "Codex executable");
   const prompt = requirePrompt(options.prompt);
-  const timeoutMs = requireTimeout(options.commandTimeoutMs ?? 60_000);
+  const timeoutMs = requireTimeout(
+    options.commandTimeoutMs ?? DEFAULT_CODEX_PROMPT_TIMEOUT_MS,
+    MAX_CODEX_PROMPT_TIMEOUT_MS,
+  );
   const spawnCommand = options.spawnCommand ?? spawn;
   if (typeof spawnCommand !== "function") {
     throw new TypeError("Codex prompt spawnCommand must be a function");
@@ -216,11 +221,11 @@ function readClock(clock) {
   return new Date(value.getTime());
 }
 
-function requireTimeout(value) {
+function requireTimeout(value, maximum = MAX_COMMAND_TIMEOUT_MS) {
   if (
     !Number.isSafeInteger(value) ||
     value < MIN_COMMAND_TIMEOUT_MS ||
-    value > MAX_COMMAND_TIMEOUT_MS
+    value > maximum
   ) {
     throw new TypeError("Codex exec adapter commandTimeoutMs is invalid");
   }

package/src/main.mjs

@@ -10,7 +10,12 @@ import process from "node:process";
 
 import { LocalConnectorClient } from "@webmcp-challenge/reentry-core/local-connector-client";
 import { followConnectorActivity } from "./activity-monitor.mjs";
-import { createCodexExecAdapter, runCodexPrompt } from "./codex-exec-adapter.mjs";
+import {
+  createCodexExecAdapter,
+  DEFAULT_CODEX_PROMPT_TIMEOUT_MS,
+  MAX_CODEX_PROMPT_TIMEOUT_MS,
+  runCodexPrompt,
+} from "./codex-exec-adapter.mjs";
 import {
   discoverCodexExecutable,
   requireSupportedNode,
@@ -44,7 +49,7 @@ const DEFAULT_MAX_CONSECUTIVE_ERRORS = 5;
 const DEFAULT_PAIRING_REQUEST_TIMEOUT_MS = 20_000;
 const CONNECTOR_VERSION = readConnectorVersion();
 // The npx form is executable even when this CLI was launched from a temporary npx cache.
-const TEMPORARY_CLI_COMMAND = "npx --yes --package=@4xeoz/re-entry re-entry";
+const TEMPORARY_CLI_COMMAND = "npx --yes @4xeoz/re-entry";
 
 async function main() {
   let ui;
@@ -139,7 +144,7 @@ Usage:
   re-entry test "Reply with hello"                     Test Codex locally
 
 Invocation:
-  Temporary npx: npx --yes --package=@4xeoz/re-entry re-entry <command>
+  Temporary npx: npx --yes @4xeoz/re-entry <command>
   Global install: npm install --global @4xeoz/re-entry, then re-entry <command>
 
 Commands:
@@ -160,6 +165,8 @@ Common options:
   --receiver <url>       Accepted Receiver origin (overrides the preview default)
   --codex-cd <path>      Workspace for Codex; interactive mode offers a folder picker if omitted
   --codex-binary <path>  Explicit Codex executable
+  --activation-timeout <ms>
+                         Codex limit; test defaults to 1 hour, background start to 60 seconds
   --json                 Machine-readable output
   --yes                  Confirm uninstall in a non-interactive script
   --help                 Show this help
@@ -178,6 +185,96 @@ function cliCommand(command) {
   return `${TEMPORARY_CLI_COMMAND} ${command}`;
 }
 
+function showInstallGuide(ui, workingDirectory) {
+  const workspace = shellQuote(workingDirectory);
+  ui.commands("COPY-PASTE COMMANDS", [
+    {
+      label: "Connect / install",
+      command: cliCommand(`install --codex-cd ${workspace}`),
+      detail: "run after disconnecting to connect one account on this Mac",
+    },
+    {
+      label: "Check status",
+      command: cliCommand("status"),
+      detail: "account, Cloud, background service, Node.js, and Codex",
+    },
+    {
+      label: "Watch activity",
+      command: cliCommand("listen"),
+      detail: "follow live work; Ctrl+C closes this view",
+    },
+    {
+      label: "Test Codex",
+      command: cliCommand(`test "Reply exactly: Re-entry is working." --codex-cd ${workspace}`),
+      detail: "local smoke test; no Cloud work is claimed",
+    },
+    {
+      label: "Check readiness",
+      command: cliCommand(`doctor --codex-cd ${workspace}`),
+      detail: "verify Node.js, Codex, and the workspace",
+    },
+    {
+      label: "Start manually",
+      command: cliCommand(`start --codex-cd ${workspace}`),
+      detail: "foreground delivery loop for development",
+    },
+    {
+      label: "Check once",
+      command: cliCommand(`claim-once --codex-cd ${workspace}`),
+      detail: "one delivery check, then exit",
+    },
+    {
+      label: "Pause",
+      command: cliCommand("stop"),
+      detail: "stop background delivery; keep the account connected",
+    },
+    {
+      label: "Sign out",
+      command: cliCommand("disconnect"),
+      detail: "clear this Mac's saved account connection",
+    },
+    {
+      label: "Remove setup",
+      command: cliCommand("uninstall"),
+      detail: "remove the local service, credential, and logs",
+    },
+    {
+      label: "Show all help",
+      command: cliCommand("--help"),
+      detail: "all commands, options, and the legacy pairing command",
+    },
+  ]);
+  ui.info("Account", "one account connected on this Mac; disconnect before connecting another");
+  ui.info("Test timeout", "one-shot Codex tests wait up to 1 hour by default");
+}
+
+function showTestGuide(ui, workingDirectory, prompt) {
+  const workspace = shellQuote(workingDirectory);
+  ui.commands("COPY-PASTE COMMANDS", [
+    {
+      label: "Test again",
+      command: cliCommand(`test ${shellQuote(prompt)} --codex-cd ${workspace}`),
+      detail: "run another local Codex smoke test",
+    },
+    {
+      label: "Check readiness",
+      command: cliCommand(`doctor --codex-cd ${workspace}`),
+      detail: "verify Node.js, Codex, and the workspace",
+    },
+    {
+      label: "Show all help",
+      command: cliCommand("--help"),
+      detail: "all commands, options, and account lifecycle actions",
+    },
+  ]);
+  ui.info("Scope", "local Codex test only; no account or Cloud work was used");
+  ui.info("Test timeout", "one-shot Codex tests wait up to 1 hour by default");
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
 function readConnectorVersion() {
   const packageJson = JSON.parse(
     readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -523,16 +620,16 @@ async function testCodex(flags, positionals, ui) {
     prompt,
     stdio: ui.interactive ? "inherit" : ["ignore", "ignore", "ignore"],
     commandTimeoutMs: readBoundedNumber(
-      flags["activation-timeout"] ?? 60_000,
+      flags["activation-timeout"] ?? DEFAULT_CODEX_PROMPT_TIMEOUT_MS,
       100,
-      60_000,
-      "connector_activation_timeout_invalid",
+      MAX_CODEX_PROMPT_TIMEOUT_MS,
+      "connector_test_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(cliCommand("listen"), "Watch the background Connector for approved work.");
+    showTestGuide(ui, readiness.workingDirectory, prompt);
   } else {
     process.stdout.write('{"event":"connector_codex_test_passed"}\n');
   }
@@ -653,7 +750,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(cliCommand("listen"), "Watch live activity. Press Ctrl+C when you are done.");
+    showInstallGuide(ui, readiness.workingDirectory);
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_service_installed",
@@ -1133,6 +1230,7 @@ function errorHint(error) {
     connector_service_stop_failed: `check the Connector status and try \`${cliCommand("stop")}\` again`,
     connector_test_prompt_missing: `use \`${cliCommand('test "Reply with: Re-entry is working."')}\``,
     connector_test_prompt_invalid: "use one short, single-line prompt inside quotes",
+    connector_test_timeout_invalid: "use a test timeout between 100 and 3600000 milliseconds",
     connector_activation_timeout_invalid: "use an activation timeout between 100 and 60000 milliseconds",
   };
   return hints[error?.code] ?? "check the command output and try again";

package/src/terminal-ui.mjs

@@ -128,6 +128,28 @@ export function createTerminalUi(options = {}) {
       write();
     },
 
+    commands(title, entries) {
+      if (!interactive) return;
+      clearSpinnerLine();
+      const validEntries = Array.isArray(entries)
+        ? entries.filter((entry) => (
+          entry &&
+          typeof entry.label === "string" && entry.label.length > 0 &&
+          typeof entry.command === "string" && entry.command.length > 0
+        ))
+        : [];
+      if (validEntries.length === 0) return;
+      const labelWidth = Math.max(...validEntries.map((entry) => entry.label.length));
+      write();
+      if (title) write(`  ${style(title, CYAN)}`);
+      for (const entry of validEntries) {
+        const label = entry.label.padEnd(labelWidth);
+        write(`  ${style(label, BOLD)}  ${style("$", CYAN)} ${style(entry.command, BOLD)}`);
+        if (entry.detail) write(`     ${style(entry.detail, DIM)}`);
+      }
+      write();
+    },
+
     error(label, detail, hint) {
       if (!interactive) return;
       clearSpinnerLine();