devicerent 0.2.0 → 0.2.1

package/README.md

@@ -1,135 +1,135 @@
-# devicerent
-
-DeviceRent from your terminal. Rent a **real** Android phone by the minute,
-install your APK, run a Quick test or Espresso, get a hosted Appium URL, or hand
-the phone to DeviceyAI — everything the website does except show you the live
-screen. You don't need to know how to code to use it.
-
-## Start here
-
-You need [Node.js](https://nodejs.org) 22 or newer (the LTS download). Then open
-a terminal — on Windows press Start and type **Terminal**, on a Mac press ⌘-Space
-and type **Terminal** — and type:
-
-```bash
-npx devicerent
-```
-
-That opens a guided session:
-
-```
-╭──────────────────────────────────────────────────╮
-│ ✻ Welcome to DeviceRent                          │
-│   Real Android phones, rented by the minute.     │
-│   you@example.com · Pro · Wallet €12.50          │
-╰──────────────────────────────────────────────────╯
-╭──────────────────────────────────────────────────╮
-│ > rent a phone                                   │
-╰──────────────────────────────────────────────────╯
-  / for commands · ? for help          no phone rented
-```
-
-Then just say what you want, in plain words:
-
-| Type | What happens |
-| --- | --- |
-| `rent` | Pick a phone from a menu; it shows **your** price and asks before billing starts |
-| *drag your `.apk` onto the window* | Installs it on the rented phone, then offers to open it |
-| `test my app` | The Quick test: opens your app, taps around, reports any crash |
-| `take a screenshot` | Saves a picture of the phone's screen to Downloads and opens it |
-| `open Settings and turn on dark mode` | Anything else in plain words goes to DeviceyAI, which does it on the phone (it asks first, and uses AI credits) |
-| `I'm done` | Stops the rental (it asks first; the phone is wiped afterwards) |
-| `balance` · `topup` · `plans` | Your wallet and plan; payment opens Stripe in your browser |
-| `/` | Every command, with a live menu — ↑↓ to choose, Enter to run |
-
-Leaving with a phone still rented asks whether to stop it first. Arrow keys,
-Enter and Esc work in every menu; Ctrl-C stops whatever is running.
-
-## One command at a time (scripts and CI)
-
-Every command also works on its own, exactly as before, and that is what
-scripts and CI should use:
-
-```bash
-npm install -g devicerent      # Node 22 or newer
-devicerent login               # approve in your browser, like `gh auth login`
-devicerent devices             # what is in the rack right now
-devicerent rent "Pixel 7a"     # billing starts now
-devicerent install app-debug.apk --launch
-devicerent test quick com.example.app --report quick-test.md
-devicerent stop
-```
-
-`devicerent` with no command opens the guided session only when a person is at
-a terminal. Piped, with `--json`, under `CI`, or with
-`DEVICERENT_NO_INTERACTIVE=1`, it prints the help text instead, and every
-command's output and exit code are unchanged.
-
-## Signing in
-
-`devicerent login` opens `devicerent.net` in your browser and asks you to
-approve the sign-in. Nothing is typed into the terminal: the page hands the
-terminal a one-time sign-in token, encrypted so that only the waiting
-`devicerent` process can open it. If your account has two-factor turned on, the
-terminal asks for your authenticator code too.
-
-Signing in on a machine without a browser (an SSH session, a VM):
-
-```bash
-devicerent login --no-browser   # open the printed link anywhere, paste the code back
-```
-
-The session is stored in `~/.config/devicerent/` (`%APPDATA%\devicerent` on
-Windows), readable only by you, and is only ever sent to the DeviceRent that
-issued it. `devicerent logout` signs this terminal out and leaves your browser
-sessions alone.
-
-## Commands
-
-| Group | Commands |
-| --- | --- |
-| Account | `whoami`, `wallet [--history]`, `history`, `credits [buy s\|m\|l]`, `topup <eur>`, `subscribe <plus\|pro\|slot> [--yearly]`, `billing`, `keys list\|create\|revoke` |
-| Rentals | `devices [--available]`, `rent <device…>` (up to three), `status`, `stop [rental] \| --all` |
-| Phone | `install <apk…> [--launch]`, `apps`, `launch <pkg>`, `uninstall <pkg>`, `shell [cmd]`, `logcat [-f] [--package] [--level]`, `screenshot [file]`, `push`, `pull`, `ui [--xml]` |
-| Testing | `test espresso [--runner] [--class] [--junit out.xml]`, `test quick <apk\|pkg> [--report] [--fix-prompt]`, `appium [--check]`, `connect [--port]` |
-| DeviceyAI | `ai "<task>" [--allow-actions] [--allow-shell] [--model]`, `ai --models` |
-
-Every command takes `--json` for machine-readable output, and `-h` for help.
-With more than one rental running, pick the phone with `--rental <id or name>`.
-
-Payments always happen in the browser: `topup`, `subscribe`, `credits buy` and
-`billing` print a Stripe link and open it.
-
-## How you are billed
-
-Exactly as on the website. A rental bills per minute from `rent` until `stop`,
-at your plan's rate. A rental with no activity for 30 minutes is stopped for
-you; installing, testing, shell input and DeviceyAI steps count as activity,
-merely holding `logcat -f` or an idle `connect` tunnel open does not.
-DeviceyAI spends AI credits, the same as in the panel.
-
-## Exit codes
-
-`0` success · `1` failure (a test failed, the app crashed, a request was
-refused) · `2` usage error or not signed in · `3` the test run itself broke.
-
-`test espresso` writes JUnit XML with `--junit`, so it drops into a CI report.
-
-## Pointing at another DeviceRent
-
-`--api-base <url>` (or `DEVICERENT_API_BASE`) targets another deployment, for
-example a local `next start` on `http://localhost:3000`. Each deployment keeps
-its own session.
-
-## Security
-
-- The terminal holds an ordinary DeviceRent session for your account — the same
-  identity and the same row-level security as your browser tab. It can do what
-  you can do on the site; admin pages stay browser-only.
-- Phones are reached over the same serial-pinned, ten-minute bridge tokens the
-  session page uses. The Pi never sees your session.
-- Approve a sign-in only if you just ran `devicerent login` yourself, and never
-  send the code from `--no-browser` to anyone.
-
-Source: [`clients/devicerent-cli`](https://github.com/DeviceRent-net/devicerent.net/tree/main/clients/devicerent-cli).
-Design notes: `docs/CLI.md` in the same repository.
+# devicerent
+
+DeviceRent from your terminal. Rent a **real** Android phone by the minute,
+install your APK, run a Quick test or Espresso, get a hosted Appium URL, or hand
+the phone to DeviceyAI — everything the website does except show you the live
+screen. You don't need to know how to code to use it.
+
+## Start here
+
+You need [Node.js](https://nodejs.org) 22 or newer (the LTS download). Then open
+a terminal — on Windows press Start and type **Terminal**, on a Mac press ⌘-Space
+and type **Terminal** — and type:
+
+```bash
+npx devicerent
+```
+
+That opens a guided session:
+
+```
+╭──────────────────────────────────────────────────╮
+│ ✻ Welcome to DeviceRent                          │
+│   Real Android phones, rented by the minute.     │
+│   you@example.com · Pro · Wallet €12.50          │
+╰──────────────────────────────────────────────────╯
+╭──────────────────────────────────────────────────╮
+│ > rent a phone                                   │
+╰──────────────────────────────────────────────────╯
+  / for commands · ? for help          no phone rented
+```
+
+Then just say what you want, in plain words:
+
+| Type | What happens |
+| --- | --- |
+| `rent` | Pick a phone from a menu; it shows **your** price and asks before billing starts |
+| *drag your `.apk` onto the window* | Installs it on the rented phone, then offers to open it |
+| `test my app` | The Quick test: opens your app, taps around, reports any crash |
+| `take a screenshot` | Saves a picture of the phone's screen to Downloads and opens it |
+| `open Settings and turn on dark mode` | Anything else in plain words goes to DeviceyAI, which does it on the phone (it asks first, and uses AI credits) |
+| `I'm done` | Stops the rental (it asks first; the phone is wiped afterwards) |
+| `balance` · `topup` · `plans` | Your wallet and plan; payment opens Stripe in your browser |
+| `/` | Every command, with a live menu — ↑↓ to choose, Enter to run |
+
+Leaving with a phone still rented asks whether to stop it first. Arrow keys,
+Enter and Esc work in every menu; Ctrl-C stops whatever is running.
+
+## One command at a time (scripts and CI)
+
+Every command also works on its own, exactly as before, and that is what
+scripts and CI should use:
+
+```bash
+npm install -g devicerent      # Node 22 or newer
+devicerent login               # approve in your browser, like `gh auth login`
+devicerent devices             # what is in the rack right now
+devicerent rent "Pixel 7a"     # billing starts now
+devicerent install app-debug.apk --launch
+devicerent test quick com.example.app --report quick-test.md
+devicerent stop
+```
+
+`devicerent` with no command opens the guided session only when a person is at
+a terminal. Piped, with `--json`, under `CI`, or with
+`DEVICERENT_NO_INTERACTIVE=1`, it prints the help text instead, and every
+command's output and exit code are unchanged.
+
+## Signing in
+
+`devicerent login` opens `devicerent.net` in your browser and asks you to
+approve the sign-in. Nothing is typed into the terminal: the page hands the
+terminal a one-time sign-in token, encrypted so that only the waiting
+`devicerent` process can open it. If your account has two-factor turned on, the
+terminal asks for your authenticator code too.
+
+Signing in on a machine without a browser (an SSH session, a VM):
+
+```bash
+devicerent login --no-browser   # open the printed link anywhere, paste the code back
+```
+
+The session is stored in `~/.config/devicerent/` (`%APPDATA%\devicerent` on
+Windows), readable only by you, and is only ever sent to the DeviceRent that
+issued it. `devicerent logout` signs this terminal out and leaves your browser
+sessions alone.
+
+## Commands
+
+| Group | Commands |
+| --- | --- |
+| Account | `whoami`, `wallet [--history]`, `history`, `credits [buy s\|m\|l]`, `topup <eur>`, `subscribe <plus\|pro\|slot> [--yearly]`, `billing`, `keys list\|create\|revoke` |
+| Rentals | `devices [--available]`, `rent <device…>` (up to three), `status`, `stop [rental] \| --all` |
+| Phone | `install <apk…> [--launch]`, `apps`, `launch <pkg>`, `uninstall <pkg>`, `shell [cmd]`, `logcat [-f] [--package] [--level]`, `screenshot [file]`, `push`, `pull`, `ui [--xml]` |
+| Testing | `test espresso [--runner] [--class] [--junit out.xml]`, `test quick <apk\|pkg> [--report] [--fix-prompt]`, `appium [--check]`, `connect [--port]` |
+| DeviceyAI | `ai "<task>" [--allow-actions] [--allow-shell] [--model]`, `ai --models` |
+
+Every command takes `--json` for machine-readable output, and `-h` for help.
+With more than one rental running, pick the phone with `--rental <id or name>`.
+
+Payments always happen in the browser: `topup`, `subscribe`, `credits buy` and
+`billing` print a Stripe link and open it.
+
+## How you are billed
+
+Exactly as on the website. A rental bills per minute from `rent` until `stop`,
+at your plan's rate. A rental with no activity for 30 minutes is stopped for
+you; installing, testing, shell input and DeviceyAI steps count as activity,
+merely holding `logcat -f` or an idle `connect` tunnel open does not.
+DeviceyAI spends AI credits, the same as in the panel.
+
+## Exit codes
+
+`0` success · `1` failure (a test failed, the app crashed, a request was
+refused) · `2` usage error or not signed in · `3` the test run itself broke.
+
+`test espresso` writes JUnit XML with `--junit`, so it drops into a CI report.
+
+## Pointing at another DeviceRent
+
+`--api-base <url>` (or `DEVICERENT_API_BASE`) targets another deployment, for
+example a local `next start` on `http://localhost:3000`. Each deployment keeps
+its own session.
+
+## Security
+
+- The terminal holds an ordinary DeviceRent session for your account — the same
+  identity and the same row-level security as your browser tab. It can do what
+  you can do on the site; admin pages stay browser-only.
+- Phones are reached over the same serial-pinned, ten-minute bridge tokens the
+  session page uses. The Pi never sees your session.
+- Approve a sign-in only if you just ran `devicerent login` yourself, and never
+  send the code from `--no-browser` to anyone.
+
+Source: [`clients/devicerent-cli`](https://github.com/DeviceRent-net/devicerent.net/tree/main/clients/devicerent-cli).
+Design notes: `docs/CLI.md` in the same repository.

package/bin/devicerent.mjs

@@ -7,11 +7,14 @@
 // import (a static one would be hoisted above the check): on an old Node the
 // bundle dies with an error nobody can act on, and the people this tool is
 // for are told what to install instead.
-import { nodeTooOld, tooOldMessage } from "./nodeCheck.mjs";
+import { loadFailedMessage, nodeTooOld, tooOldMessage } from "./nodeCheck.mjs";
 
 if (nodeTooOld(process.version)) {
   process.stderr.write(tooOldMessage(process.version));
   process.exitCode = 1;
 } else {
-  import("../dist/devicerent.mjs");
+  import("../dist/devicerent.mjs").catch((err) => {
+    process.stderr.write(loadFailedMessage(err));
+    process.exitCode = 1;
+  });
 }

package/bin/nodeCheck.mjs

@@ -19,3 +19,18 @@ export function tooOldMessage(version) {
     "Install the LTS version from https://nodejs.org, open a new terminal, then run: npx devicerent\n"
   );
 }
+
+/**
+ * The bundle itself failed to load: a file missing from a broken install, or
+ * a dependency whose download did not finish. One sentence and what to do,
+ * not a stack trace.
+ */
+export function loadFailedMessage(err) {
+  var first = String((err && err.message) || err).split("\n")[0];
+  return (
+    "DeviceRent could not start: " +
+    first +
+    "\n" +
+    "Reinstall it and try again: npx devicerent@latest  (or, if you installed it: npm install -g devicerent@latest)\n"
+  );
+}