qraftai-runner 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +91 -0
- package/dist/index.js +1299 -0
- package/package.json +38 -0
package/README.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# QraftAI Runner — bring your own device
|
|
2
|
+
|
|
3
|
+
Run QraftAI's mobile automation on **your own** Android emulator or phone, driven
|
|
4
|
+
by your QraftAI workspace in the cloud. The runner dials **out** to QraftAI (no
|
|
5
|
+
inbound ports, firewall-friendly) and executes device actions locally — the AI
|
|
6
|
+
agent, LLM calls, and billing stay on the QraftAI server. It never sees an API key.
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
Your browser ──▶ QraftAI (cloud) ──runner tunnel──▶ this runner ──▶ your device
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Prerequisites (on this machine)
|
|
13
|
+
|
|
14
|
+
Same toolchain as a local QraftAI mobile setup:
|
|
15
|
+
|
|
16
|
+
| Tool | Install (macOS) |
|
|
17
|
+
|---|---|
|
|
18
|
+
| JDK 17+ | `brew install openjdk` |
|
|
19
|
+
| Android SDK (`adb` + `emulator`) | [Android Studio](https://developer.android.com/studio) — sets `ANDROID_HOME` |
|
|
20
|
+
| Appium 2 | `npm i -g appium` |
|
|
21
|
+
| UiAutomator2 driver | `appium driver install uiautomator2` |
|
|
22
|
+
| A device | an emulator (AVD) **or** a USB phone with USB debugging on |
|
|
23
|
+
|
|
24
|
+
Make sure `adb` and `emulator` are on `PATH` and `ANDROID_HOME` is set. Verify:
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
adb devices # your phone/emulator shows "device"
|
|
28
|
+
appium --version
|
|
29
|
+
emulator -list-avds
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Run it
|
|
33
|
+
|
|
34
|
+
1. In QraftAI open the **Mobile** tab → **Local** → **Connect your machine**.
|
|
35
|
+
2. Copy the command it shows (it embeds a token scoped to your workspace):
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
npx qraftai-runner --server wss://app.qraftai.com/runner-stream --token <token>
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
From this repo you can instead run it directly:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
node runner/index.js --server wss://<host>/runner-stream --token <token>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
3. Leave it running. Your emulators/phones now appear in the Mobile tab's device
|
|
48
|
+
dropdown. Pick one, choose an app, and Run — the live view, save, replay, and
|
|
49
|
+
reports all work as usual.
|
|
50
|
+
|
|
51
|
+
### Options
|
|
52
|
+
|
|
53
|
+
| Flag | Env | Meaning |
|
|
54
|
+
|---|---|---|
|
|
55
|
+
| `--server`, `-s` | `QRAFTAI_SERVER` | `wss://<host>/runner-stream` |
|
|
56
|
+
| `--token`, `-t` | `QRAFTAI_TOKEN` | org-scoped runner token from the Mobile tab |
|
|
57
|
+
| `--name`, `-n` | `QRAFTAI_RUNNER_NAME` | a label for this machine, shown in the app |
|
|
58
|
+
|
|
59
|
+
The runner auto-reconnects if the connection drops. Stop it with `Ctrl-C`.
|
|
60
|
+
|
|
61
|
+
## App under test
|
|
62
|
+
|
|
63
|
+
The app can be:
|
|
64
|
+
- an **app you upload in QraftAI** — it's streamed to the runner and installed for the run,
|
|
65
|
+
- an **already-installed** package on the device, or
|
|
66
|
+
- a local **`.apk` path** on this machine.
|
|
67
|
+
|
|
68
|
+
## Notes
|
|
69
|
+
|
|
70
|
+
- **Android only** today (matches the rest of QraftAI mobile).
|
|
71
|
+
- The token is a bearer credential for your workspace's device sessions — treat it
|
|
72
|
+
like a password; regenerate it from the Mobile tab to revoke an old one.
|
|
73
|
+
|
|
74
|
+
## Publishing (maintainers)
|
|
75
|
+
|
|
76
|
+
The published package is a **single self-contained bundle** — `esbuild` inlines the
|
|
77
|
+
device layer (`../server/mobile/*`) at build time, so the tarball has no repo
|
|
78
|
+
dependency (only `ws`, `webdriverio`, `dotenv` as normal npm deps). Only `dist/` +
|
|
79
|
+
`README.md` are shipped (see `files` in `package.json`); `dist/` is gitignored and
|
|
80
|
+
rebuilt on publish via `prepublishOnly`.
|
|
81
|
+
|
|
82
|
+
```sh
|
|
83
|
+
cd runner
|
|
84
|
+
npm install # installs esbuild (build) + declared deps
|
|
85
|
+
npm run build # optional: build dist/index.js locally to inspect
|
|
86
|
+
npm pack --dry-run # optional: preview the tarball contents
|
|
87
|
+
npm login # your npm account/org
|
|
88
|
+
npm publish --access public
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
After publishing, `npx qraftai-runner …` works on any machine with Node 18+.
|