@thedriveai/device-helper 0.0.0-stage → 0.1.4
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/LICENSE +21 -0
- package/README.md +97 -2
- package/dist/cli.js +11663 -0
- package/dist/lib.d.ts +800 -0
- package/dist/lib.js +3036 -0
- package/package.json +52 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 The Drive AI
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,98 @@
|
|
|
1
|
-
#
|
|
1
|
+
# The Drive AI device helper
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Shares folders on this machine with [The Drive AI](https://thedrive.ai) agent, which then lists,
|
|
4
|
+
searches, organises and reads them the way it does a connected cloud drive. The files stay where
|
|
5
|
+
they are: the agent keeps a catalog (names, paths, sizes, dates) and the text of documents it reads.
|
|
6
|
+
|
|
7
|
+
Questions or problems: contact@thedrive.ai.
|
|
8
|
+
|
|
9
|
+
## Mac, PC, Linux
|
|
10
|
+
|
|
11
|
+
Needs Node 20 or later.
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
npm install -g @thedriveai/device-helper # once; the command is tdai-device
|
|
15
|
+
tdai-device pair <code> # the code comes from Settings → Devices in the web app
|
|
16
|
+
tdai-device root add ~/Documents # share a folder (repeat for more)
|
|
17
|
+
tdai-device run # keep this running
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
`tdai-device status` shows the pairing and the shared folders; `tdai-device root list` and
|
|
21
|
+
`tdai-device root remove <id>` manage them.
|
|
22
|
+
|
|
23
|
+
`root add` options: `--label "Client files"`, `--read-only`, `--trash none` (the agent will move
|
|
24
|
+
instead of deleting), `--trash dir --trash-dir <folder>`. Deletes go to the OS trash by default
|
|
25
|
+
(Finder's Trash with Put Back, the Recycle Bin, the freedesktop trash on Linux).
|
|
26
|
+
|
|
27
|
+
The Mac desktop app embeds this helper, so on a Mac the app's Settings → Agent → Share a folder is
|
|
28
|
+
the easier route.
|
|
29
|
+
|
|
30
|
+
## NAS (Synology, QNAP, TrueNAS, Unraid)
|
|
31
|
+
|
|
32
|
+
The image is `ghcr.io/thedriveai/device-helper` (amd64 and arm64). Settings → Devices → Pair a
|
|
33
|
+
device gives the command with the code filled in; its shape:
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
docker run -d --name tdai-device --restart unless-stopped \
|
|
37
|
+
-e TDAI_PAIR_CODE=<code from Settings → Devices> \
|
|
38
|
+
-e TDAI_DEVICE_NAME="Office NAS" \
|
|
39
|
+
-e TDAI_TRASH_DIR=#recycle \
|
|
40
|
+
-v /volume1/Clients:/data/Clients \
|
|
41
|
+
-v tdai-device-config:/config \
|
|
42
|
+
ghcr.io/thedriveai/device-helper:latest
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Every folder mounted under `/data` is shared; `/config` keeps the pairing and the journals, so the
|
|
46
|
+
pairing code is used once and ignored after. The container dials out to the service and nothing is
|
|
47
|
+
opened on the NAS. Run it as the share's user (`--user 1026:100` on a Synology, `user:` in compose)
|
|
48
|
+
so files the agent writes or moves belong to that user and share users can edit and delete them
|
|
49
|
+
over SMB as before. The helper needs no privilege of its own.
|
|
50
|
+
|
|
51
|
+
| variable | meaning |
|
|
52
|
+
|---|---|
|
|
53
|
+
| `TDAI_PAIR_CODE` | pairs on first start; ignored once `/config` holds the pairing |
|
|
54
|
+
| `TDAI_DEVICE_NAME` | the name people see ("Office NAS"); without it, the container id |
|
|
55
|
+
| `TDAI_TRASH_DIR` | `#recycle` (or `@Recycle`) = each share's own NAS recycle bin, whichever the NAS keeps: QNAP's `@Recycle` when the share has one, else Synology's `#recycle`; another relative name = that folder in each share; an absolute path = one folder for all; unset = the agent moves instead of deleting. Read at every start, so a change takes effect when the container is recreated. A delete into a NAS bin goes to the nearest one above the item (a whole volume mounted as one folder reaches each share's bin), and its access time is set to now so the bin's retention counts from the delete (QNAP empties by access time). A bin the helper cannot write makes the agent move instead. A trash folder of your own is marked `.thedrive-trash` and never catalogued; an absolute one mounted under `/data` is not shared |
|
|
56
|
+
| `TDAI_SHARED=0` | keep the folders to the person who paired (default: the whole workspace, when an admin paired) |
|
|
57
|
+
| `TDAI_CONTENT=names` | the agent organises by name and date and never reads documents into the index |
|
|
58
|
+
| `TDAI_READ_ONLY=1` | the agent can read but not move, rename or delete |
|
|
59
|
+
|
|
60
|
+
Updating: `docker pull ghcr.io/thedriveai/device-helper:latest` and recreate the container (the
|
|
61
|
+
`/config` volume keeps the pairing), or let an updater such as Watchtower do it.
|
|
62
|
+
|
|
63
|
+
## What it does while running
|
|
64
|
+
|
|
65
|
+
- Walks each shared folder once at start against its last snapshot and reports what changed while
|
|
66
|
+
it was off; then watches for changes (FSEvents / inotify / ReadDirectoryChangesW). On Linux the
|
|
67
|
+
watch is one inotify watch per folder (never per file), under a budget of `TDAI_WATCH_BUDGET`
|
|
68
|
+
folders (20,000); past it, or when the kernel's `fs.inotify.max_user_watches` runs out, the helper
|
|
69
|
+
says so and a periodic rescan is the feed (`--rescan-minutes 60`, the Docker default; a folder
|
|
70
|
+
with no watcher is rescanned every 30 minutes whatever was asked).
|
|
71
|
+
- One helper per config: a second copy on the same `/config` (or `~/.thedrive-device`) refuses to
|
|
72
|
+
start. The container is healthy while connected (`/config/heartbeat`). A share whose mount is
|
|
73
|
+
missing at start is announced as unavailable and paused under the same id until it is back;
|
|
74
|
+
remove it from Settings → Devices if it is gone for good.
|
|
75
|
+
- A rename or a move inside a shared folder is reported as a move, so the agent keeps the file's
|
|
76
|
+
id, its text and everything that refers to it; a deletion is reported a couple of seconds later,
|
|
77
|
+
once no moved twin appeared. A folder whose volume was renumbered (a NAS share remounted, a
|
|
78
|
+
restore) but still holds the shared files is taken as the same folder; `tdai-device root re-adopt
|
|
79
|
+
<id>` says so by hand when it is not obvious.
|
|
80
|
+
- On Linux a delete goes to the volume's own trash (`.Trash-<uid>` at the volume's top, or the home
|
|
81
|
+
trash when the share is on the home volume); a volume with no trash the helper can use answers
|
|
82
|
+
"no trash" and the agent moves instead. In Docker, `TDAI_TRASH_DIR` is the trash.
|
|
83
|
+
- Answers the agent's requests: list, stat, stream a file, create, move, copy, trash. Every path is
|
|
84
|
+
checked to stay inside a shared folder; symlinks pointing out are not followed.
|
|
85
|
+
- Config and journals live in `~/.thedrive-device` (or `/config` in Docker). The device token is
|
|
86
|
+
stored there with mode 0600; rotate it by pairing again. State is per shared folder under
|
|
87
|
+
`state/<rootId>/`; deleting it makes the agent re-enumerate that folder on the next connection,
|
|
88
|
+
which is harmless.
|
|
89
|
+
|
|
90
|
+
## As a library
|
|
91
|
+
|
|
92
|
+
The package also exports the helper for a host that embeds it (the desktop app does): bring a
|
|
93
|
+
shared folder up, build a client over a socket the host owns, and the config helpers. The
|
|
94
|
+
declarations in `dist/lib.d.ts` are the reference.
|
|
95
|
+
|
|
96
|
+
## License
|
|
97
|
+
|
|
98
|
+
MIT.
|