@4xeoz/re-entry 0.2.13 → 0.2.14

package/README.md

@@ -18,7 +18,8 @@ Requirements: macOS, Node.js 24+, Codex installed and signed in, and an absolute
 Codex may read and write.
 
 ```sh
-npx @4xeoz/re-entry install
+npx --yes --package=@4xeoz/re-entry re-entry install \
+  --receiver https://your-accepted-receiver.example
 ```
 
 `npx` runs a temporary copy, so it does not leave a permanent shell command behind. Install the
@@ -29,7 +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.
+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`.
 
 The CLI no longer has a default hosted Receiver. For any new or historical test, pass an explicit
 accepted Receiver origin with `--receiver` or `REENTRY_RECEIVER_ORIGIN`; the former
@@ -39,13 +41,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 @4xeoz/re-entry install \
+npx --yes --package=@4xeoz/re-entry re-entry install \
+  --receiver https://your-accepted-receiver.example \
   --codex-cd /absolute/path/to/your/project
 ```
 
 The guided screen stays intentionally small: **Workspace → System check → Connect Re-entry**. It
-shows one clear next command when setup finishes; internal Connector IDs, credential paths, and log
-paths stay out of the normal success screen.
+shows one executable next command when setup finishes; 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
@@ -56,7 +59,9 @@ installation instead:
 
 ```sh
 npm install --global @4xeoz/re-entry
-re-entry install --codex-cd /absolute/path/to/your/project
+re-entry install \
+  --receiver https://your-accepted-receiver.example \
+  --codex-cd /absolute/path/to/your/project
 ```
 
 Use `--receiver` to select an accepted replacement Receiver, such as a local historical preview:
@@ -86,29 +91,43 @@ preview.
 
 ## Check it
 
+If you installed the package globally:
+
 ```sh
 re-entry status
 re-entry listen
 re-entry --help
+re-entry stop
+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 uninstall
 ```
 
 The status view checks the local authorization, background job, Receiver reachability, Node, and
 Codex. If the Receiver rejects a previously saved device credential, the Connector pauses instead
-of retrying forever, and `status`/`listen` tell you to run `re-entry connect` again. `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:
+of retrying forever, and `status`/`listen` print an executable `connect` command. `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
-re-entry connect --receiver http://127.0.0.1:43224
-re-entry claim-once --codex-cd /absolute/path/to/project
-re-entry start --codex-cd /absolute/path/to/project
+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
 ```
 
 Test the local Codex handoff without waiting for Cloud work:
 
 ```sh
-re-entry test "Reply with: Re-entry is working."
+npx --yes --package=@4xeoz/re-entry 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
@@ -117,8 +136,8 @@ does not create a Grant, claim Receiver work, or prove the browser/WebMCP return
 To pause or remove the local Connector:
 
 ```sh
-re-entry stop
-re-entry uninstall
+npx --yes --package=@4xeoz/re-entry re-entry stop
+npx --yes --package=@4xeoz/re-entry re-entry uninstall
 ```
 
 `stop` pauses the macOS background service and keeps the account connection. `uninstall` requires
@@ -139,8 +158,8 @@ Install the Re-entry Local Connector on this Mac. First read the package README.
 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 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 `re-entry status` and report the bounded
-results without claiming Browser/WebMCP or production deployment.
+into chat, logs, source files, or git. Finish by running `npx --yes --package=@4xeoz/re-entry re-entry status`
+and report the bounded results without claiming Browser/WebMCP or production deployment.
 ```
 
 ## Package map
@@ -208,15 +227,16 @@ npm run verify
 npm publish --access public
 ```
 
-NPM versions are immutable: if the current version has already been published, bump it before
-publishing (the current published `0.2.11` therefore requires `0.2.12` or another new version).
+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`.
 
-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.
+A temporary `npx` invocation does not add `re-entry` to your shell `PATH`. If you prefer the shorter
+bare commands, run `npm install --global @4xeoz/re-entry` once and then use `re-entry install`
+directly.
 
 ## Check a Mac before pairing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4xeoz/re-entry",
-  "version": "0.2.13",
+  "version": "0.2.14",
   "type": "module",
   "description": "Outbound Local Connector process for Re-entry Core; new Receiver origins must be explicit.",
   "publishConfig": {

package/src/main.mjs

@@ -41,6 +41,8 @@ const DEFAULT_POLL_INTERVAL_MS = 5_000;
 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";
 
 async function main() {
   let ui;
@@ -129,6 +131,10 @@ Usage:
   re-entry listen                                      Watch live activity
   re-entry test "Reply with hello"                     Test Codex locally
 
+Invocation:
+  Temporary npx: npx --yes --package=@4xeoz/re-entry re-entry <command>
+  Global install: npm install --global @4xeoz/re-entry, then re-entry <command>
+
 Commands:
   install      Check this Mac, connect the Re-entry account, and start at login
   status       Show account, Receiver, service, Node.js, and Codex readiness
@@ -156,6 +162,10 @@ The Connector opens no inbound port. Host keys never belong on this Mac.
 `);
 }
 
+function cliCommand(command) {
+  return `${TEMPORARY_CLI_COMMAND} ${command}`;
+}
+
 function readConnectorVersion() {
   const packageJson = JSON.parse(
     readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -265,7 +275,7 @@ async function pair(flags, ui, options = {}) {
   });
   if (ui.interactive) {
     ui.complete("Pairing complete", "Re-entry can now deliver approved work to this Mac.");
-    ui.next("re-entry start", "Wait for approved work in this terminal.");
+    ui.next(cliCommand("start"), "Wait for approved work in this terminal.");
   } else {
     process.stdout.write(`${JSON.stringify({ event: "connector_paired", connector_id: credentials.connector_id })}\n`);
   }
@@ -288,7 +298,7 @@ async function connect(flags, ui, options = {}) {
     if (ui.interactive) {
       ui.success("Account", "already connected");
       if (!options.guidedInstall) {
-        ui.next("re-entry start", "Wait for approved work in this terminal.");
+        ui.next(cliCommand("start"), "Wait for approved work in this terminal.");
       }
     } else {
       process.stdout.write(`${JSON.stringify({
@@ -347,7 +357,7 @@ async function connect(flags, ui, options = {}) {
   if (ui.interactive) {
     if (!options.guidedInstall) {
       ui.complete("This Mac is connected", "Re-entry can now route approved work here.");
-      ui.next("re-entry start", "Wait for approved work in this terminal.");
+      ui.next(cliCommand("start"), "Wait for approved work in this terminal.");
     }
   } else {
     process.stdout.write(`${JSON.stringify({
@@ -386,14 +396,14 @@ async function status(flags, ui) {
     else if (credentials) ui.warning("Cloud", "unavailable");
 
     if (reauthorizationRequired) {
-      ui.next("re-entry connect", "Approve this Mac again in your browser; the old credential was rejected.");
+      ui.next(cliCommand("connect"), "Approve this Mac again in your browser; the old credential was rejected.");
     } else if (!connected || !service.running) {
-      ui.next("re-entry install", "Finish setup and start Re-entry in the background.");
+      ui.next(cliCommand("install"), "Finish setup and start Re-entry in the background.");
     } else if (!receiverReady) {
-      ui.next("re-entry status", "Check again when the Re-entry Cloud service is available.");
+      ui.next(cliCommand("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.");
+      ui.next(cliCommand("listen"), "Watch live activity. Press Ctrl+C when you are done.");
     }
   } else {
     process.stdout.write(`${JSON.stringify({
@@ -425,11 +435,11 @@ async function listen(flags, ui) {
     if (ui.interactive) {
       if (reauthorizationRequired) {
         ui.warning("Account", "reconnect required; the Cloud Receiver rejected this Mac");
-        ui.next("re-entry connect", "Approve this Mac again in your browser.");
+        ui.next(cliCommand("connect"), "Approve this Mac again in your browser.");
       }
       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.");
+      ui.next(cliCommand("install"), "Finish setup and start the background Connector.");
     } else {
       process.stdout.write(`${JSON.stringify({
         event: "connector_listener_unavailable",
@@ -494,7 +504,7 @@ async function testCodex(flags, positionals, ui) {
   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.");
+    ui.next(cliCommand("listen"), "Watch the background Connector for approved work.");
   } else {
     process.stdout.write('{"event":"connector_codex_test_passed"}\n');
   }
@@ -511,7 +521,7 @@ function reportLiveActivity(event, ui) {
     );
   } else if (event.event === "connector_reauthorization_required" || event.code === "connector_identity_invalid") {
     ui.stopWait("Reconnect required", "the Cloud Receiver rejected this Mac's saved connection", "warning");
-    ui.next("re-entry connect", "Approve this Mac again in your browser.");
+    ui.next(cliCommand("connect"), "Approve this Mac again in your browser.");
     return;
   } else if (event.event === "connector_poll_failed" || event.event === "local_connector_failed") {
     ui.stopWait("Connection interrupted", "Re-entry is retrying", "warning");
@@ -534,7 +544,7 @@ async function stop(flags, ui) {
     if (!result.supported) ui.warning("Platform", "background service control currently supports macOS only");
     else if (result.stopped) ui.complete("Re-entry is paused", "Your account connection is still saved.");
     else ui.info("Already stopped", "no running background Connector was found");
-    if (result.supported) ui.next("re-entry install", "Start Re-entry in the background again.");
+    if (result.supported) ui.next(cliCommand("install"), "Start Re-entry in the background again.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_stopped",
@@ -557,7 +567,7 @@ async function uninstall(flags, ui) {
   });
   if (ui.interactive) {
     ui.complete("Removed from this Mac", "The local service, connection, and logs are gone.");
-    ui.next("npx @4xeoz/re-entry install", "Connect this Mac again whenever you are ready.");
+    ui.next(cliCommand("install"), "Connect this Mac again whenever you are ready.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_uninstalled",
@@ -589,7 +599,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 listen", "Watch live activity. Press Ctrl+C when you are done.");
+    ui.next(cliCommand("listen"), "Watch live activity. Press Ctrl+C when you are done.");
   } else {
     process.stdout.write(`${JSON.stringify({
       event: "connector_service_installed",
@@ -628,7 +638,7 @@ async function start(flags, ui) {
   } else if (await hasConnectorReauthorizationRequired(credentialFile)) {
     if (ui.interactive) {
       ui.warning("Account", "this Mac needs to be connected again");
-      ui.next("re-entry connect", "Create a new dashboard pairing code and connect this Mac again.");
+      ui.next(cliCommand("connect"), "Create a new dashboard pairing code and connect this Mac again.");
     } else {
       process.stdout.write('{"event":"connector_reauthorization_required"}\n');
     }
@@ -674,7 +684,7 @@ async function start(flags, ui) {
           });
           if (ui.interactive) {
             ui.stopWait("Reconnect required", "the Cloud Receiver rejected this Mac's saved connection", "warning");
-            ui.next("re-entry connect", "Approve this Mac again in your browser.");
+            ui.next(cliCommand("connect"), "Approve this Mac again in your browser.");
           } else {
             process.stdout.write('{"event":"connector_reauthorization_required"}\n');
           }
@@ -1038,15 +1048,15 @@ function errorHint(error) {
     connector_codex_cd_missing: "pass --codex-cd /absolute/path/to/your/Host-project",
     connector_codex_not_found: "install Codex, add it to PATH, or pass --codex-binary /path/to/codex",
     connector_codex_binary_not_found: "check --codex-binary or remove it to use automatic discovery",
-    connector_codex_unusable: "open Codex, complete login if needed, then run `npm run doctor` again",
+    connector_codex_unusable: `open Codex, complete login if needed, then run \`${cliCommand("doctor")}\` again`,
     connector_node_unsupported: "use Node.js 24 or newer, then run the command again",
     connector_receiver_missing: "pass --receiver <replacement-receiver-origin> or set REENTRY_RECEIVER_ORIGIN",
-    connector_credentials_missing: "connect this Mac once with `re-entry connect`",
-    connector_credentials_expired: "run `re-entry connect` to authorize this Mac again",
+    connector_credentials_missing: `connect this Mac once with \`${cliCommand("connect")}\``,
+    connector_credentials_expired: `run \`${cliCommand("connect")}\` to authorize this Mac again`,
     connector_credentials_already_exists: "use the existing Connector credential or ask for a new pairing code",
-    connector_identity_invalid: "run `re-entry connect` and approve this Mac again",
-    connector_reauthorization_required: "run `re-entry connect` and approve this Mac again",
-    connector_pairing_code_missing: "ask the Host backend for a new pairing code, then run pair in a terminal",
+    connector_identity_invalid: `run \`${cliCommand("connect")}\` and approve this Mac again`,
+    connector_reauthorization_required: `run \`${cliCommand("connect")}\` and approve this Mac again`,
+    connector_pairing_code_missing: `ask the Host backend for a new pairing code, then run \`${cliCommand("pair")}\` in a terminal`,
     pairing_code_invalid: "use the 16-character code returned by the Host, for example ABCD-EFGH-IJKL-MNOP",
     host_subject_already_paired: "use the existing Connector credential or revoke/reset the preview pairing",
     pairing_expired: "ask the Host backend for a new pairing code",
@@ -1054,14 +1064,14 @@ function errorHint(error) {
     pairing_network_error: "check your internet connection and the Receiver address, then try again",
     workspace_directory_unavailable: "choose a readable folder or pass --codex-cd /absolute/path",
     workspace_selection_cancelled: "run the command again when you are ready to choose a workspace",
-    device_authorization_expired: "run `re-entry connect` again and approve within ten minutes",
-    device_authorization_denied: "run `re-entry connect` again when you are ready to approve this Mac",
+    device_authorization_expired: `run \`${cliCommand("connect")}\` again and approve within ten minutes`,
+    device_authorization_denied: `run \`${cliCommand("connect")}\` again when you are ready to approve this Mac`,
     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",
-    connector_test_prompt_missing: "use `re-entry test \"Reply with: Re-entry is working.\"`",
+    connector_service_load_failed: `run \`${cliCommand("install")}\` again; if it still fails, inspect the Connector error log`,
+    connector_uninstall_confirmation_required: `run \`${cliCommand("uninstall")}\` interactively and type DELETE, or pass \`--yes\` in a deliberate script`,
+    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_activation_timeout_invalid: "use an activation timeout between 100 and 60000 milliseconds",
   };