diggylab 0.1.30
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 +104 -0
- package/cli.js +2781 -0
- package/package.json +37 -0
package/README.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# Desktop Agent CLI
|
|
2
|
+
|
|
3
|
+
The Desktop Agent also runs headless as a CLI worker, for customers who scan from a Linux server
|
|
4
|
+
instead of the desktop app. It pairs like any device, receives `DESKTOP` scan jobs, and scans with
|
|
5
|
+
headless Chromium — the Electron app is not involved.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node.js 22+
|
|
10
|
+
- Linux packages: `xvfb`, `x11vnc`, `websockify`, `novnc` (Debian/Ubuntu: `apt install xvfb x11vnc websockify novnc`). The Docker image below bundles them.
|
|
11
|
+
- Chromium for Playwright: `npx playwright install --with-deps chromium`
|
|
12
|
+
|
|
13
|
+
## Install
|
|
14
|
+
|
|
15
|
+
From npm (customers):
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install -g diggylab
|
|
19
|
+
diggylab --help
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
From the repository (development):
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pnpm install
|
|
26
|
+
pnpm --filter jobfinding-desktop-agent cli:build
|
|
27
|
+
node apps/desktop-agent/dist-cli/cli/cli.js --help
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
State lives in `~/.diggylab` (`--config <directory>` or `DIGGYLAB_AGENT_DIR` overrides it).
|
|
31
|
+
|
|
32
|
+
## Publishing the npm package
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pnpm --filter jobfinding-desktop-agent cli:pack
|
|
36
|
+
npm publish apps/desktop-agent/dist-npm --access public
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`cli:pack` bundles the workspace code into a single `cli.js`, so the published package only depends
|
|
40
|
+
on `playwright`, `qrcode-terminal`, and `ws`. Bump the version in `apps/desktop-agent/package.json`
|
|
41
|
+
first — the packed manifest copies it.
|
|
42
|
+
|
|
43
|
+
## Commands
|
|
44
|
+
|
|
45
|
+
| Command | What it does |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| `pair --code <code> [--name <device name>] [--api <origin>]` | Pairs the server as a device. Create the code on `/settings/desktop-agent` in the web app. |
|
|
48
|
+
| `login` | Opens the Facebook login page on a virtual screen and prints a noVNC link + QR code. Log in from your phone; the session is stored encrypted on the server. |
|
|
49
|
+
| `run` | Connects the WebSocket worker, receives assigned scans, scans headlessly, uploads results. |
|
|
50
|
+
| `status` | Shows the config directory, API origin, paired device, and Facebook session state. |
|
|
51
|
+
| `unpair` | Removes device credentials, the Facebook session, and pending scans. |
|
|
52
|
+
|
|
53
|
+
Useful options: `--api <origin>` (default `https://api.diggylab.com`), `--port` / `--bind` /
|
|
54
|
+
`--public-host` for the login screen, `--display <number>` to avoid an Xvfb collision.
|
|
55
|
+
|
|
56
|
+
## How `login` works on a server
|
|
57
|
+
|
|
58
|
+
A server has no screen, so the agent starts `Xvfb` (virtual screen), `x11vnc` (shares it) and
|
|
59
|
+
`websockify` + noVNC (turns it into a web page):
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
Xvfb → Chromium opens Facebook's real login page → noVNC link + QR → phone logs in → session saved
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The noVNC URL carries a one-time token, the port is only open while `login` runs, and everything is
|
|
66
|
+
torn down when the login finishes or times out (10 minutes). If you prefer not to expose a port,
|
|
67
|
+
pass `--bind 127.0.0.1` and forward it over SSH (`ssh -L 6080:127.0.0.1:6080 <server>`).
|
|
68
|
+
|
|
69
|
+
## Security notes
|
|
70
|
+
|
|
71
|
+
- `~/.diggylab/key` (mode `600`) encrypts device credentials, the Facebook session, and the
|
|
72
|
+
scan spool. Treat it like a password: back it up privately, never share it.
|
|
73
|
+
- The Facebook session belongs to the customer's account; run `login` again when `status` reports
|
|
74
|
+
it missing (sessions expire, and a sudden IP change can trigger a Facebook checkpoint).
|
|
75
|
+
- Unmatched or expired payments are unrelated to this worker — the agent only scans.
|
|
76
|
+
|
|
77
|
+
## Run as a service
|
|
78
|
+
|
|
79
|
+
```ini
|
|
80
|
+
[Unit]
|
|
81
|
+
Description=DiggyLab Desktop Agent CLI
|
|
82
|
+
After=network-online.target
|
|
83
|
+
|
|
84
|
+
[Service]
|
|
85
|
+
User=diggylab
|
|
86
|
+
WorkingDirectory=/opt/diggylab
|
|
87
|
+
ExecStart=/usr/bin/node /opt/diggylab/dist-cli/cli/cli.js run
|
|
88
|
+
Restart=always
|
|
89
|
+
Environment=DIGGYLAB_API_URL=https://api.diggylab.com
|
|
90
|
+
|
|
91
|
+
[Install]
|
|
92
|
+
WantedBy=multi-user.target
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Docker
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
docker build -f apps/desktop-agent/Dockerfile.cli -t diggylab .
|
|
99
|
+
docker run -it --rm -p 6080:6080 -v diggylab:/data diggylab pair --code ABC123
|
|
100
|
+
docker run -it --rm -p 6080:6080 -v diggylab:/data diggylab login
|
|
101
|
+
docker run -d --restart unless-stopped -v diggylab:/data diggylab run
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The image sets `DIGGYLAB_AGENT_DIR=/data`, so the volume keeps the key, credentials, and spool.
|