@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 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
- # Temporary Holding Version
1
+ # The Drive AI device helper
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.