worktrust 0.11.6 → 0.11.8
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/CHANGELOG.md +346 -0
- package/README.md +211 -283
- package/cli-colour.mjs +86 -0
- package/cli-menu-remote.mjs +148 -0
- package/cli-menu.mjs +245 -0
- package/engine-release.json +1 -1
- package/folder-picker.mjs +85 -0
- package/node-guide.mjs +134 -0
- package/package-release.json +1 -1
- package/package.json +12 -2
- package/remote-adapter-claude-code.mjs +27 -7
- package/remote-admin.mjs +109 -0
- package/remote-approvals.mjs +2 -2
- package/remote-cli.mjs +66 -58
- package/remote-connections.mjs +91 -0
- package/remote-countdown.mjs +52 -0
- package/remote-daemon.mjs +56 -7
- package/remote-inventory.mjs +28 -0
- package/remote-pairing.mjs +22 -9
- package/remote-policy.mjs +15 -0
- package/remote-projects.mjs +39 -1
- package/remote-protocol.mjs +253 -4
- package/remote-run.mjs +14 -7
- package/remote-service.mjs +36 -2
- package/remote-sessions.mjs +15 -9
- package/remote-settings.mjs +191 -0
- package/remote-store.mjs +4 -1
- package/worktrust.mjs +50 -15
package/README.md
CHANGED
|
@@ -1,301 +1,214 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
## 0.11.6: approve a computer with your phone
|
|
4
|
-
|
|
5
|
-
**Two roads to approve this computer for Remote Agent.** `npx worktrust remote app` shows the approval as a QR code in
|
|
6
|
-
the terminal, without opening a browser: scan it with the WorkTrust app, check the code and key, accept Remote Agent's
|
|
7
|
-
terms and approve with your authenticator code. `npx worktrust remote web` opens the approval page in your browser, as
|
|
8
|
-
before. `npx worktrust remote enable` asks which one you want. A request lives ten minutes; the page and the app count
|
|
9
|
-
it down and tell you when to run the command again.
|
|
10
|
-
|
|
11
|
-
**A command the CLI does not know** now says so ("Unknown command: …") before the help, and ends with a failure code.
|
|
12
|
-
|
|
13
|
-
No measure change: the measure rules stay 4.
|
|
14
|
-
|
|
15
|
-
## 0.11.5: Remote Agent (the new name), and a link needs your authenticator
|
|
16
|
-
|
|
17
|
-
**Remote Agent.** What was called MOCHI is now called Remote Agent everywhere you read it: in this CLI's messages, in
|
|
18
|
-
Settings › Remote Agent on app.worktrust.io and on your phone, where its tab is Devs. Its terms moved to
|
|
19
|
-
worktrust.io/remote-agent-terms; the old address forwards there. Nothing it does changed.
|
|
20
|
-
|
|
21
|
-
**A link needs your authenticator.** Approving this computer on app.worktrust.io, and adding a new phone or browser, now
|
|
22
|
-
asks for a code from your authenticator app; an e-mailed code no longer does. A link stays with the account and the phone
|
|
23
|
-
that made it, and it ends when you remove that authenticator. A phone asked by code is still confirmed at this keyboard:
|
|
24
|
-
`npx worktrust remote phones confirm <fingerprint>`. What is measured for the passport is unchanged: the measure rules
|
|
25
|
-
stay 4.
|
|
26
|
-
|
|
27
|
-
## 0.11.4: local models measured, confidential client work, OpenCode in Remote Agent
|
|
28
|
-
|
|
29
|
-
**Local models, used directly.** The Ollama app's chats and Open WebUI's are now read like every other database client:
|
|
30
|
-
the model, the time of each turn and, for Open WebUI, the token counts it kept (the Ollama app keeps none, so none are
|
|
31
|
-
sent or estimated). Never a title, a message, a file or a prompt. A model used through OpenCode, Goose, Hermes or OpenClaw
|
|
32
|
-
was already measured with that client. Because these are days no earlier version measured, the measure rules become 4:
|
|
33
|
-
`npx worktrust update` on a computer measured by rules 3 offers the re-measure once and says why.
|
|
34
|
-
|
|
35
|
-
**Confidential client work.** `npx worktrust project confidential [folder]` marks a client's repository: its hours and
|
|
36
|
-
token counts still count, under one fixed marker, and no repository name, branch, remote, path, commit or app title
|
|
37
|
-
leaves the computer. Your passport names that share inside your verified hours as "Confidential client work".
|
|
38
|
-
`npx worktrust project exclude [folder]` leaves a folder out entirely, `project normal` undoes either, and `project list`
|
|
39
|
-
shows what you set. Only you change these at your keyboard; an agent's shell may only list them.
|
|
40
|
-
|
|
41
|
-
**OpenCode in Remote Agent.** Your phone can steer OpenCode on this computer, and through it a local model such as Qwen on
|
|
42
|
-
Ollama. Like Codex it is off by default: `npx worktrust remote opencode on` says what OpenCode can do without asking and
|
|
43
|
-
asks for a typed yes; `off` switches it off again. Its runs ask your phone before every command, edit and fetch, and a
|
|
44
|
-
remote-steered session never counts as your hours.
|
|
45
|
-
|
|
46
|
-
**The import window.** An AI app on this computer is shown the `import_history` tool only in the hour after you copy the
|
|
47
|
-
import prompt in Sources on app.worktrust.io, so it no longer costs every session the tool's description.
|
|
48
|
-
`npx worktrust history` is unchanged.
|
|
49
|
-
|
|
50
|
-
## 0.11.3: every device off this computer at once
|
|
51
|
-
|
|
52
|
-
`npx worktrust remote phones remove --all` disconnects every phone and browser from this computer in one act, after one
|
|
53
|
-
confirmation at the keyboard. The computer refuses them from their next message. Sessions they started keep running here:
|
|
54
|
-
stop them with `npx worktrust remote disable`, or pause everything with `npx worktrust remote pause`. To end their keys for
|
|
55
|
-
your whole account too, use Settings › Remote Agent on app.worktrust.io or Remote Agent settings on your phone. What is measured for the
|
|
56
|
-
passport is unchanged: remote-steered sessions never count as your hours, and the measure rules stay 3.
|
|
57
|
-
|
|
58
|
-
## 0.11.2: your phone adds a browser
|
|
59
|
-
|
|
60
|
-
A browser where you use app.worktrust.io can steer this computer's agents without a walk to its keyboard: the browser
|
|
61
|
-
shows a code, your phone scans it and asks Face ID, and this computer adds the browser only if you allowed it here once
|
|
62
|
-
(`npx worktrust remote phones allow-endorse on`, off by default), only for a browser of your own account, and only within
|
|
63
|
-
five minutes. The terminal says when a browser was added and `npx worktrust remote phones` lists which phone added it;
|
|
64
|
-
each one stays revocable. The Passport's issuer key stays pinned. What is measured for the passport is unchanged:
|
|
65
|
-
remote-steered sessions never count as your hours, and the measure rules stay 3.
|
|
66
|
-
|
|
67
|
-
## 0.11.1: terminal sessions, and the live preview you can touch
|
|
68
|
-
|
|
69
|
-
`npx worktrust remote terminal on` lets the phone start Claude Code in a terminal session on WorkTrust's own tmux socket
|
|
70
|
-
(off until you turn it on), which you can also join at the desk with `npx worktrust remote attach <id>`. The phone reads
|
|
71
|
-
the session's screen, is sent it when it changes while someone follows it, and answers a dialog the agent shows only
|
|
72
|
-
when the screen still looks the way it did when you read it. The local preview can now be live: the page itself, on the
|
|
73
|
-
phone, touchable, through this computer's own browser. Codex gets the same three planning tools as Claude Code. What is
|
|
74
|
-
measured for the passport is unchanged: remote-steered sessions never count as your hours, and the measure rules stay 3.
|
|
75
|
-
|
|
76
|
-
## 0.11.0: steer your own agents from your phone
|
|
77
|
-
|
|
78
|
-
`npx worktrust remote` pairs this computer with the WorkTrust app and lets the phone steer the coding agents that run
|
|
79
|
-
here (Claude Code and Codex): start a chat in a project, choose the agent and its model from the ones this computer
|
|
80
|
-
reports, send photos and files into the project's inbox (at most 25 MB a file), approve what the agent asks, and follow
|
|
81
|
-
its work. Everything between the phone and this computer is sealed end to end; the relay passes it without reading it.
|
|
82
|
-
The local agent plans its own work with three tools on its session (a release, its tasks, their state and estimate), so
|
|
83
|
-
the phone's Status shows one table of what runs, what waits ("after release 22") and what ended. A session reports its
|
|
84
|
-
active time, the background jobs an agent left running, and, inside a git worktree, the repository it belongs to. A
|
|
85
|
-
local preview renders a dev server you allowed, as desktop, tablet or phone, with this computer's own browser. A phone
|
|
86
|
-
app from before this version cannot read what 0.11.0 sends: update both. What is measured for the passport is unchanged:
|
|
87
|
-
remote-steered sessions never count as your hours, and the measure rules stay 3.
|
|
88
|
-
|
|
89
|
-
## 0.10.38: an export says what it can about its own clock
|
|
90
|
-
|
|
91
|
-
`npx worktrust history --export` now sends, beside each run's timeline, the facts WorkTrust checks to tell an edited
|
|
92
|
-
ChatGPT or Claude-on-the-web export from one as the vendor made it: every model slug of the run (`models`), how many kept
|
|
93
|
-
steps are dated more than ten minutes before the step they follow (`tree_inversions`), and, for a ChatGPT conversation
|
|
94
|
-
whose id carries a clock, how far its creation time sits from that clock (`id_skew`). Once per export batch it sends the
|
|
95
|
-
export's envelope: its kind (a zip, several zips, a folder or a bare file), the moment the vendor's zip name gives, the
|
|
96
|
-
first and last write time of its conversations entries, its last message, and whether its shape is the vendor's (no extra
|
|
97
|
-
field but zip64's, no data descriptor, no Finder litter, parts in order). Never a conversation's id, title or text, never
|
|
98
|
-
the archive's file name. A line whose clock does not hold up goes to Review with its reason named, never refused or
|
|
99
|
-
deleted; a re-zipped export alone is only a label. Lines that arrived from 0.10.37 or older are not judged again. One new
|
|
100
|
-
module, `export-facts.mjs`. What is measured is unchanged: the measure rules stay 3.
|
|
101
|
-
|
|
102
|
-
## 0.10.37: an export arrives whole; progress, Ctrl+C and the reason in WorkTrust's words; CLI active and updating itself
|
|
103
|
-
|
|
104
|
-
An export send no longer stops at WorkTrust's upload budget per minute: the person's own send waits it out (at most 90
|
|
105
|
-
seconds a wait) and goes on, and a batch WorkTrust stored in part is sent again at once until it holds every line; a line
|
|
106
|
-
already received is kept once. Every long step shows how far it is, and Ctrl+C stops cleanly, keeping what has not arrived
|
|
107
|
-
for the next run. A batch that did not arrive is said in WorkTrust's own words instead of "Not all of it arrived". The
|
|
108
|
-
receipt after an export names its hours as reconstructed by WorkTrust, beside the measured ones, never as measured.
|
|
109
|
-
CLI active per computer: a pause set in Sources › Devices is kept by the computer at its next session, and turning it back
|
|
110
|
-
on lets the computer update itself, verified (SECURITY.md, "Updating itself when you turn it on"). A computer on 0.10.36
|
|
111
|
-
or older updates once by hand: `npx worktrust@latest update`. What is measured is unchanged: the measure rules stay 3.
|
|
112
|
-
|
|
113
|
-
## 0.10.36: large and cut-off ChatGPT exports; hours only with `mcp off`; a re-measure reported whole or not at all
|
|
114
|
-
|
|
115
|
-
`npx worktrust history --export` now reads a ChatGPT export of any size: a zip64 archive (an export over 4 GB), and a
|
|
116
|
-
download that stopped part way, which is read up to the last whole `conversations-NNN.json` part and said as such ("The
|
|
117
|
-
archive was cut off after conversations-NNN.json; this is not the whole export"), so you decide whether to send what was
|
|
118
|
-
read before the cut. ChatGPT's loose `conversations-NNN.json` parts, a folder of them or one part beside its siblings, are
|
|
119
|
-
read as one export in part order; a missing part is refused by its name. An empty element in an export is counted and
|
|
120
|
-
left out instead of refusing the whole export. What is sent from an export is unchanged: hours and tokens per day, never
|
|
121
|
-
text. (The reader can also count an export's file kinds, searches and model switches between model families, but nothing
|
|
122
|
-
asks for them and nothing of them is sent.)
|
|
123
|
-
|
|
124
|
-
`npx worktrust mcp off` keeps the hours and takes the WorkTrust door out of every AI app here; `mcp on` puts it back (see
|
|
125
|
-
"Hours only, or also work lines" below). A choice made for this computer in Sources › Devices is done by the computer
|
|
126
|
-
at its next session. `update` no longer takes Codex's door out on every second run at the same version.
|
|
127
|
-
|
|
128
|
-
A re-measure says "Re-measured" only when WorkTrust holds every batch of the run; otherwise it says how many it holds and
|
|
129
|
-
gives WorkTrust's own reason for a refused batch, and the session hook exits with an error. What is measured is
|
|
130
|
-
unchanged, so the measure rules stay 3 and no re-measure is offered.
|
|
131
|
-
|
|
132
|
-
## 0.10.35: Gemini CLI read; every earlier line can name its AI app
|
|
133
|
-
|
|
134
|
-
Gemini CLI's sessions are read in place, as Copilot's are: the files Gemini CLI records itself under
|
|
135
|
-
`~/.gemini/tmp/<project>/chats/session-*.jsonl` (or an older `.json`), each message's role and clock, the model and
|
|
136
|
-
the token counts, and each tool call's name and status; the messages, the thoughts and the tool calls' arguments and
|
|
137
|
-
results are parsed with the file and never kept or sent. A subagent's session lies inside its parent's and is not
|
|
138
|
-
counted. The project folder is not read, so these lines name no repository. Their lines go as `gemini-cli`.
|
|
139
|
-
|
|
140
|
-
WorkTrust now records which AI app each line came from (Copilot in VS Code, Gemini CLI, Antigravity …), so its AI apps
|
|
141
|
-
table can give them their own rows. Lines measured before carry only their product ("Other apps"). The measure rules
|
|
142
|
-
go to 3: `update` offers the re-measure once, and it sends every day again; WorkTrust replaces only the lines of
|
|
143
|
-
"Other apps" and "App not recorded" that name no app, with the same counted seconds, and keeps every other line as it is.
|
|
144
|
-
`npx worktrust history --rebuild --force-days` does the same at any time: every day of every AI app, even the days
|
|
145
|
-
WorkTrust already holds unchanged (every app at once, so no day loses another app's line).
|
|
146
|
-
|
|
147
|
-
## 0.10.34: your own commits, measured on this computer (`npx worktrust git`)
|
|
148
|
-
|
|
149
|
-
GitHub shows an App that reads commits as "Read access to code", and has no narrower permission. `npx worktrust git`
|
|
150
|
-
reads your own commits HERE instead, with `git log`, only those whose author e-mail is yours (git's `user.email`, plus
|
|
151
|
-
any you add with `git emails add`), in the repositories your AI sessions ran in or that you add with `git add <folder>`.
|
|
152
|
-
It asks once, with the list; Enter and `--yes` are No, and a No is remembered. Each commit's file names are turned into
|
|
153
|
-
the same closed keys the GitHub sync makes (kinds of files, technologies, architecture and security markers, one-way
|
|
154
|
-
markers per folder and file) on this computer, and what is sent is counts, keys and markers: never a file name, a
|
|
155
|
-
message, code, the commit's id or the remote's address. A commit travels as an owner-keyed reference only WorkTrust's
|
|
156
|
-
side can match against what GitHub saw. `git list` shows what is offered and agreed, `git remove <folder>` reads nothing
|
|
157
|
-
more from it, `--dry-run` reads and sends nothing.
|
|
158
|
-
|
|
159
|
-
## 0.10.33: one line per autonomous process per day; a fair-use limit keeps the line
|
|
160
|
-
|
|
161
|
-
A finished headless or scheduled run (a run no person started) is no longer a line of its own. It waits on this
|
|
162
|
-
computer, in `~/.worktrust/process-days`, folded into its process's UTC day: a process is the AI app, how the session
|
|
163
|
-
was started, the timer's opaque reference when a timer started it, and the project folder, as a hash (`process_ref`),
|
|
164
|
-
never a name or a path. Once the day is over and quiet it goes as ONE line with how many runs it holds
|
|
165
|
-
(`process_runs`); the runs' timelines are joined at minute resolution, which keeps every counted second, with each
|
|
166
|
-
run's call outcomes, its turns' length buckets and its subagent runs kept in step (every turn and each minute's first
|
|
167
|
-
completed call stay). A run that
|
|
168
|
-
finishes after its day was sent becomes the day's next part, and once WorkTrust holds its parts it is merged into the
|
|
169
|
-
last one, which goes again whole. When WorkTrust answers a fair-use limit (429 with Retry-After) nothing is lost: the
|
|
170
|
-
line stays where it was and goes after the wait. What is measured is unchanged, so the measure rules stay 2 and no
|
|
171
|
-
re-measure is offered.
|
|
172
|
-
|
|
173
|
-
## 0.10.32: a re-measure sends only the days that changed; which subagents were active at once; each call's outcome
|
|
174
|
-
|
|
175
|
-
Before a re-measure sends anything, the CLI asks WorkTrust, once per AI app, which of this computer's days it holds as
|
|
176
|
-
current. The question carries nothing but the question (`import_history` with `rebuild` and `fingerprint`, no line).
|
|
177
|
-
The answer is the digest this computer sent with each such day, its own submission and never the record: no hours, no
|
|
178
|
-
lines, no figure. A day whose digest on this computer is the same is not sent, so a re-run with nothing new sends
|
|
179
|
-
nothing and says so; one changed day sends that day alone. If the answer is not one (an older WorkTrust, an error, no
|
|
180
|
-
network), every day is sent as before. The digest covers each line as it is sent, without the CLI's own version, so
|
|
181
|
-
an update that measures the same sends nothing. When WorkTrust names where the run waits, the command prints
|
|
182
|
-
`queued, position N, about M min`.
|
|
183
|
-
|
|
184
|
-
A Claude Code session's subagents (the transcripts Claude Code keeps in `<session>/subagents/`) now travel with the day's
|
|
185
|
-
stretch as `agents`: per run, by position only, its kind (`builtin`, `own` for an agent type of your own, `background`,
|
|
186
|
-
`fork`, read from the run's `.meta.json`), when it started in whole seconds from the stretch's start, the stretches of time
|
|
187
|
-
it was active (a gap over five minutes ends one) and how many of its tool steps failed and how many of those a later step
|
|
188
|
-
of the same kind recovered. Never a name, a prompt, a path, a tool or an id. At most 64 runs a stretch, 12 active stretches
|
|
189
|
-
a run and 256 in all; the longest are kept. WorkTrust counts a run only while the session it belongs to is steered by you
|
|
190
|
-
(within 8 hours of your last input), and shows how many agents were active at once beside the sessions at once; it is never
|
|
191
|
-
added to your hours.
|
|
192
|
-
|
|
193
|
-
Beside the timeline, each model answer's outcome travels as one character (`call_outcomes`: completed, failed or not
|
|
194
|
-
known), and in a run no person started (headless or scheduled) the length of each of your own turns as a bucket
|
|
195
|
-
(`input_lengths`: short, medium or long) and, when a timer started the run, its cadence word with an opaque reference
|
|
196
|
-
(`schedule_cadence`, `schedule_ref`). Never a word, a command, a path or the timer's name. WorkTrust credits Agentic Hours
|
|
197
|
-
only for calls recorded as completed.
|
|
198
|
-
|
|
199
|
-
The measure rules go to 2, so `update` offers a re-measure once, naming these changes.
|
|
200
|
-
|
|
201
|
-
The session hook no longer reads a Claude Code transcript from its first byte on every run. Beside each session's
|
|
202
|
-
watermark in `~/.worktrust/sessions.json` it keeps where its last read ended: the file's identity (device and inode), the
|
|
203
|
-
offset, a hash of eight 4 KB samples before it, the offset of the first message not yet sent, and what a full read would
|
|
204
|
-
know at that point (the session's working folder, how it was started, a subagent's first moment). That stays on this
|
|
205
|
-
computer and is never sent. The next run reads from the first unsent message, so a day that spans the offset is read
|
|
206
|
-
again from its start, and gives exactly what a full read gives. A file that was truncated, rewritten, replaced or
|
|
207
|
-
compacted, a new CLI version, other measure rules, or a state without positions is read whole, as before. A re-measure
|
|
208
|
-
(`history`, `history --rebuild`, the offer after an update) always reads everything. Measured: 1 MB appended to a 600 MB
|
|
209
|
-
transcript reads about 1 MB.
|
|
210
|
-
|
|
211
|
-
## 0.10.31: a re-measure is offered only when measuring changed
|
|
212
|
-
|
|
213
|
-
`update` offers to re-measure this computer's sessions only when the new version MEASURES differently from the one it
|
|
214
|
-
replaces: a different timeline, seconds, tokens, steering, session kinds or readers. A release that changes something
|
|
215
|
-
else (consent, coupling, words) offers nothing. The offer lists what changed, one line each. The CLI carries the
|
|
216
|
-
version of its measuring rules beside its own version and records it in `~/.worktrust/installed-release.json` and
|
|
217
|
-
`~/.worktrust/history.json`; an install from before 0.10.31, which did not record it, counts as measuring by 0.10.29's
|
|
218
|
-
rules, so 0.10.29 or 0.10.30 updated to 0.10.31 is offered nothing. A history sent completely by a version with the
|
|
219
|
-
same rules counts as done, so the bare `npx worktrust` does not offer it again either.
|
|
220
|
-
|
|
221
|
-
## 0.10.30: an update asks only what is new
|
|
222
|
-
|
|
223
|
-
`update` remembers what you said yes to. Each AI app's WorkTrust door, the session hook, Codex's `notify` line and
|
|
224
|
-
Antigravity's `Stop` hook that you agreed to are brought onto the new version without a question, each printed as
|
|
225
|
-
`✓ … refreshed (you agreed on <date>)`. Only the launcher's path changes; nothing else about what was agreed. A NEW AI
|
|
226
|
-
app, or a wake hook that is no longer there (you took it out), is shown in full and asked about; `--yes` leaves it as
|
|
227
|
-
it is and lists it as `skipped: new, run without --yes to decide`. A No drops the agreement, and `disconnect` deletes
|
|
228
|
-
the record. It is one small file, `~/.worktrust/consent.json` (see [SECURITY.md](SECURITY.md)). The first update that
|
|
229
|
-
keeps it counts the WorkTrust entries already on this computer as agreed, because only a yes ever wrote them.
|
|
230
|
-
|
|
231
|
-
The re-measure after a new version is one question, asked after its plan (the plan is counted on this computer and
|
|
232
|
-
sends nothing): `Send them (re-measured; …)? [y/N]`. Enter and `--yes` are No. `--rebuild` agrees in advance.
|
|
233
|
-
|
|
234
|
-
One line that updates a computer you coupled before, with no question at all:
|
|
1
|
+
# WorkTrust CLI
|
|
235
2
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
3
|
+
WorkTrust CLI measures the work you do with AI on your own computer and lets you steer your own coding agents from your phone.
|
|
4
|
+
|
|
5
|
+
It counts hours, tokens and tools for your verified AI Passport on [WorkTrust](https://worktrust.io): counts and metadata,
|
|
6
|
+
never your prompts, your code or what the AI answered. With Remote Agent, the same tool lets your phone start and follow
|
|
7
|
+
the coding agents on this computer, inside the folders you allow. You run every command yourself, each one shows its plan
|
|
8
|
+
first, and nothing is sent before you say yes.
|
|
239
9
|
|
|
240
|
-
|
|
241
|
-
- `worktrust@latest`: the newest published version, never a copy npm cached earlier.
|
|
242
|
-
- `update`: this computer onto that version, the same key, no new pairing.
|
|
243
|
-
- `--yes`: every question whose answer is Yes by default. Anything new stays as it is (skipped, and listed).
|
|
244
|
-
- `--rebuild`: yes in advance to re-measuring this computer's sessions with the new version's rules. WorkTrust
|
|
245
|
-
replaces this computer's earlier lines for those days, each withdrawn and kept, never deleted. Leave it out to
|
|
246
|
-
be asked.
|
|
247
|
-
- `--codex` and `--antigravity` say yes in advance to a NEW Codex or Antigravity wake hook as well.
|
|
10
|
+
## What you can do
|
|
248
11
|
|
|
249
|
-
|
|
12
|
+
- **Measure.** A session hook measures each stretch of AI work on this computer: when, how long, which model, how many tokens, what kind of work.
|
|
13
|
+
- **Import history.** Send the earlier sessions your AI apps still hold, or a ChatGPT or Claude data export, as earlier work. It is shown with its origin, never as verified hours.
|
|
14
|
+
- **Preserve evidence.** See how long each AI app keeps its sessions, keep them longer, and write a local, hash-chained record of your measured days. This needs no account and sends nothing.
|
|
15
|
+
- **Remote Agent.** Start, follow and answer the coding agents on this computer from your phone or a browser, end-to-end sealed.
|
|
16
|
+
- **Connect your AI apps.** Give the AI apps on this computer the WorkTrust door, so your AI can log a finished piece of work. Or run hours only, without the door.
|
|
250
17
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
18
|
+
What WorkTrust shows is observed work within a stated period. The scores built on it are not calibrated and are not a
|
|
19
|
+
hiring instrument.
|
|
20
|
+
|
|
21
|
+
## Install and first run
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
npx worktrust
|
|
25
|
+
```
|
|
255
26
|
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
as the person's hours. `--history --dry-run --summary` prints the planned batches and the session kinds, counts only.
|
|
27
|
+
In your own terminal this opens the menu. On a computer that is not connected yet, Check this computer shows the plan,
|
|
28
|
+
asks, and you approve the computer in your browser with your own account and second factor. Before WorkTrust starts,
|
|
29
|
+
npm itself may ask `Ok to proceed?`; `npx -y worktrust` answers that in advance.
|
|
260
30
|
|
|
261
|
-
|
|
31
|
+
**With Python instead.** The Python package runs the same CLI and brings its own Node, so it needs no Node on the computer:
|
|
262
32
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
33
|
+
```sh
|
|
34
|
+
pipx run worktrust
|
|
35
|
+
pip install worktrust
|
|
36
|
+
```
|
|
267
37
|
|
|
268
|
-
|
|
38
|
+
**What you need.**
|
|
269
39
|
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
40
|
+
- Node 18 or later for measuring, importing and preserving. Reading the AI apps that keep their sessions in a database needs Node 22.5 or later.
|
|
41
|
+
- Node 22.4 or later for Remote Agent, or the Python package.
|
|
42
|
+
- macOS, Linux or Windows. Every release is built and tested on six platforms: Linux x64 and arm64, macOS on Intel and Apple silicon, Windows x64 and arm64.
|
|
43
|
+
- A WorkTrust account for everything except `preserve`, which is for everyone.
|
|
273
44
|
|
|
274
|
-
|
|
45
|
+
**If your Node is older than 22.4.** Measuring keeps working. A `remote` command, and the menu's Remote Agent item, say so
|
|
46
|
+
and show the ways forward, each with its exact command:
|
|
275
47
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
48
|
+
1. Update this computer's Node. The CLI reads how Node is installed here and shows the matching command (nvm, fnm, Volta,
|
|
49
|
+
asdf, Homebrew, winget, or the installer from nodejs.org). For fnm, Volta and Homebrew it can run the command for you,
|
|
50
|
+
after showing it and only when you type yes. It never uses sudo and never runs a system package manager. Afterwards it
|
|
51
|
+
runs `npx worktrust update`, so the session hook and your AI apps point at the new Node, and continues what you started.
|
|
52
|
+
2. Use the Python package, which brings its own Node: `pipx run worktrust remote app`.
|
|
279
53
|
|
|
280
|
-
|
|
281
|
-
an activity upload. Pending metadata batches can be resumed with `worktrust history --resume`,
|
|
282
|
-
even after an AI app removed the original session files. Review-held revisions need review;
|
|
283
|
-
reconnecting does not approve them. Keep archives for work that was never queued.
|
|
54
|
+
Without a terminal nothing is asked and nothing runs: the same text is printed and the command ends with a failure code.
|
|
284
55
|
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
Retiring a device preserves earlier data. Existing accounts above the limit are preserved but
|
|
288
|
-
cannot add another identity. Version labels and device signatures are not independent evidence
|
|
289
|
-
of time or correctness. A CLI update does not automatically publish a passport.
|
|
56
|
+
**Update.** `npx worktrust@latest update` brings this computer's hook and AI-app doors to the newest version. Your key and
|
|
57
|
+
pairing stay.
|
|
290
58
|
|
|
59
|
+
**Stop.** `npx worktrust disconnect` takes WorkTrust out of every AI app here and removes the key. Then revoke the
|
|
60
|
+
computer in WorkTrust under Sources, Devices. More under [Undo](#undo).
|
|
291
61
|
|
|
292
|
-
|
|
293
|
-
record of the work you do with AI without anyone reading that work: it receives metadata only.
|
|
62
|
+
## The menu
|
|
294
63
|
|
|
295
64
|
```
|
|
296
|
-
|
|
65
|
+
WorkTrust CLI 0.11.8
|
|
66
|
+
Connected as you@example.com · Remote Agent on
|
|
67
|
+
|
|
68
|
+
> 1 Update WorkTrust · up to date (0.11.8) npx worktrust update
|
|
69
|
+
Brings this computer's hook and AI-app doors to this version again; your key and pairing stay.
|
|
70
|
+
2 Check this computer npx worktrust
|
|
71
|
+
Shows what is coupled here and finishes what still waits; a change asks first.
|
|
72
|
+
3 Remote Agent › npx worktrust remote …
|
|
73
|
+
Opens the choices for steering this computer's agents from your phone. Nothing changes yet.
|
|
74
|
+
4 Import earlier history › npx worktrust history …
|
|
75
|
+
Opens the ways to send earlier sessions as history. Each one shows its plan and asks first.
|
|
76
|
+
5 Preserve evidence › npx worktrust preserve …
|
|
77
|
+
Opens the ways to keep your AI history on this computer. Nothing is sent.
|
|
78
|
+
6 WorkTrust in your AI apps: On npx worktrust mcp off
|
|
79
|
+
Takes the WorkTrust door out of every AI app here; the session hook keeps measuring your hours.
|
|
80
|
+
7 Status npx worktrust status
|
|
81
|
+
Shows the key, the hook, the door and what this computer measured. It only reads.
|
|
82
|
+
8 Disconnect this computer npx worktrust disconnect
|
|
83
|
+
Takes WorkTrust out of every AI app here and ends this computer's key. It asks first.
|
|
84
|
+
9 Help · all commands npx worktrust help
|
|
85
|
+
Lists every command and option. Tip: npx -y worktrust skips npm's own "Ok to proceed?" question.
|
|
86
|
+
Quit q
|
|
87
|
+
Leaves the menu. Nothing keeps running.
|
|
88
|
+
|
|
89
|
+
↑/↓ move · Enter open · q quit · 1-9 jump
|
|
297
90
|
```
|
|
298
91
|
|
|
92
|
+
Every item shows the command it runs, so you can type it next time. Without a terminal (a script, a hook, the MCP door)
|
|
93
|
+
there is no menu and nothing waits for a key.
|
|
94
|
+
|
|
95
|
+
## Commands
|
|
96
|
+
|
|
97
|
+
| Command | What it does |
|
|
98
|
+
|---|---|
|
|
99
|
+
| `npx worktrust` | In your terminal: the menu. Without a terminal, or with any option: connects this computer (shows the plan, asks, you approve in your browser), or shows what is connected. |
|
|
100
|
+
| `npx worktrust connect` | Connects this computer again, also when it is already connected. Asks first. |
|
|
101
|
+
| `npx worktrust update` | Brings this computer onto the newest CLI: same key, no new pairing. Something new is asked about. |
|
|
102
|
+
| `npx worktrust history` | Sends this computer's earlier sessions as history. `--rebuild` measures them again, `--export <path>` reads a ChatGPT or Claude export, `--from-archive` and `--from-folder <dir>` read your own copies. Always shows the plan and asks. |
|
|
103
|
+
| `npx worktrust disconnect` | Takes WorkTrust out of every AI app here. Asks first. |
|
|
104
|
+
| `npx worktrust status` | Shows what is connected here. It only reads. |
|
|
105
|
+
| `npx worktrust project` | Sets a folder's mode: exclude (nothing read), confidential (hours and tokens count; no name, branch, path or commit is sent) or normal. `project list` shows them. |
|
|
106
|
+
| `npx worktrust remote` | Remote Agent: `app` or `web` approve this computer, `pair` links a phone, then `status`, `pause`, `resume`, `disable`, `connections`, `disconnect`, `projects`, `roots` and `modes`. |
|
|
107
|
+
| `npx worktrust mcp off` | Hours only: the WorkTrust door out of every AI app here. The session hook keeps measuring. |
|
|
108
|
+
| `npx worktrust mcp on` | The door back in, so your AI can log finished work. |
|
|
109
|
+
| `npx worktrust mcp` | Says which of the two this computer is in. |
|
|
110
|
+
| `npx worktrust protect-key` | After an update: moves the key's protection into the operating system's vault. Asks first. |
|
|
111
|
+
| `npx worktrust orchestration report --file recording.jsonl` | Inspects a local recording of agent metadata. Sends nothing. |
|
|
112
|
+
| `npx worktrust mod` | The WorkTrust mod for Claude Code: what it counts and whether it is on. `mod install` turns it on, `mod remove` turns it off. |
|
|
113
|
+
| `npx worktrust git` | Sends your own commits as counts and kinds, measured on this computer: never a file name, a message, code or the commit's id. Asks once. |
|
|
114
|
+
| `npx worktrust preserve` | Keeps your AI history: the report, then `--apply` (keep sessions longer), `--archive`, `--verify` and `--summary` for the local record. For everyone, with or without an account. |
|
|
115
|
+
|
|
116
|
+
`npx worktrust help` prints these with every option. `--dry-run` shows a plan and stops; `--no-color` or `NO_COLOR` turns
|
|
117
|
+
colours off.
|
|
118
|
+
|
|
119
|
+
## How it works
|
|
120
|
+
|
|
121
|
+
1. **A plan, then a question.** A command lists what it found and what it would change, and asks. Nothing is written or sent before you answer.
|
|
122
|
+
2. **You approve the computer in your browser**, signed in to WorkTrust with your second factor. The terminal never sees a password and cannot choose an account.
|
|
123
|
+
3. **A session hook measures** each stretch of AI work when a session ends, and sends the measurement.
|
|
124
|
+
|
|
125
|
+
**What it reads.** Your AI apps' own session files on this computer, to take clocks, token counts, model names and the
|
|
126
|
+
kind of work from them.
|
|
127
|
+
|
|
128
|
+
**What it sends.** Per stretch of work: its timeline, token counts, the model's name, the kind of work and closed
|
|
129
|
+
technology keywords. For a repository on GitHub, GitLab or Bitbucket also its owner/name and the hashes of the commits
|
|
130
|
+
made; for any other repository a code that names nothing. The full list is in
|
|
131
|
+
[What it reads, writes and sends](#what-it-reads-writes-and-sends).
|
|
132
|
+
|
|
133
|
+
**What it never sends.** Your prompts, the AI's answers, your code, file contents or file paths.
|
|
134
|
+
|
|
135
|
+
**Where the key lives.** In a private file on this computer, and after `protect-key` wrapped by the operating system's
|
|
136
|
+
vault (Keychain, Credential Manager or the Secret Service). See [Credential protection](#credential-protection).
|
|
137
|
+
|
|
138
|
+
**What you can check.** The package has no dependencies and is published with provenance. Each release is signed, and the
|
|
139
|
+
launcher checks the package's files against that signature before it starts. A signature shows that a release is ours. It
|
|
140
|
+
does not prove that work happened: see [Why you can check it](#why-you-can-check-it) and
|
|
141
|
+
[Release signatures and the limits of verification](#release-signatures-and-the-limits-of-verification).
|
|
142
|
+
|
|
143
|
+
The long versions start at [What happens](#what-happens).
|
|
144
|
+
|
|
145
|
+
## Remote Agent
|
|
146
|
+
|
|
147
|
+
Remote Agent lets your phone, or a browser, steer the coding agents on this computer. It is off until you turn it on at
|
|
148
|
+
this keyboard, and it has its own key, apart from the measuring key.
|
|
149
|
+
|
|
150
|
+
**Pairing in three steps.**
|
|
151
|
+
|
|
152
|
+
1. `npx worktrust remote app` shows a QR code here. You scan it with the WorkTrust app and approve this computer with your authenticator. `npx worktrust remote web` does the same in your browser.
|
|
153
|
+
2. `npx worktrust remote projects add <folder>` allows a folder. A phone can start an agent only in folders you allowed here.
|
|
154
|
+
3. `npx worktrust remote pair` shows a QR code for a phone: five minutes, one phone, once.
|
|
155
|
+
|
|
156
|
+
**What a phone can do.** Start an agent in an allowed folder, follow it, answer it, and approve by class: a file edit
|
|
157
|
+
inside the project, a test, build or lint command from a short reviewed list, and a message an agent wants to send, shown
|
|
158
|
+
whole.
|
|
159
|
+
|
|
160
|
+
**What a phone cannot do.** Install from the network, push, deploy, delete outside the project, read secret files or
|
|
161
|
+
grant an "always allow". Those are decided at this keyboard or not at all.
|
|
162
|
+
|
|
163
|
+
**Modes with a ceiling.** Manual and Plan are always there. Edit automatically and Auto exist only once you allow them
|
|
164
|
+
here with `remote modes allow`. The computer refuses a mode above what you allowed.
|
|
165
|
+
|
|
166
|
+
**Sealed end to end.** The computer holds one outbound connection and opens no port. Messages are sealed between your
|
|
167
|
+
phone and this computer; the relay passes them on and cannot read a prompt, a file, a path, an output or a model name.
|
|
168
|
+
|
|
169
|
+
A session steered from a phone is recorded as an agent run. It never counts as your AI Hours.
|
|
170
|
+
|
|
171
|
+
The details: [Remote Agent: steer this computer's agents](#remote-agent-steer-this-computers-agents-from-your-phone-or-browser-npx-worktrust-remote).
|
|
172
|
+
|
|
173
|
+
## The phone app
|
|
174
|
+
|
|
175
|
+
The WorkTrust app is coming to the App Store and Google Play. It is in TestFlight testing now, and there is no date yet.
|
|
176
|
+
News is on [worktrust.io](https://worktrust.io). Until then, Remote Agent also works from a browser at app.worktrust.io.
|
|
177
|
+
|
|
178
|
+
## Supported AI apps and agents
|
|
179
|
+
|
|
180
|
+
- **Measured** (their sessions are read): Claude Code, Codex, Gemini CLI, Antigravity, Cursor, Copilot in VS Code, Hermes Agent, Goose, OpenCode, OpenClaw, the Ollama app and Open WebUI.
|
|
181
|
+
- **Connected** (they can get the WorkTrust door): Claude Code, Codex CLI, Gemini CLI, Cursor, VS Code (Copilot agent mode), Windsurf, Mistral Vibe, Antigravity, Grok Build, Zed, Cline, Goose, OpenCode and OpenClaw.
|
|
182
|
+
- **Steered by Remote Agent:** Claude Code, Codex, OpenCode and a terminal session.
|
|
183
|
+
|
|
184
|
+
Only what is on this computer is found. Which sessions can be read depends on the format each app keeps.
|
|
185
|
+
|
|
186
|
+
## Privacy and security
|
|
187
|
+
|
|
188
|
+
- Counts and metadata only. No prompt, answer, code or file content leaves this computer.
|
|
189
|
+
- Nothing is written or sent before you say yes, and `--dry-run` shows any plan without doing it.
|
|
190
|
+
- An AI agent cannot run these commands for you: they stop in an agent's shell. See [AGENTS.md](AGENTS.md).
|
|
191
|
+
- The key stays on this computer, and you can revoke it in WorkTrust at any time.
|
|
192
|
+
- A signature proves a release is ours and that a key was present. It is not independent proof of the work.
|
|
193
|
+
|
|
194
|
+
The threat model and the known limits are in [SECURITY.md](SECURITY.md). To report a vulnerability, write to
|
|
195
|
+
**hello@worktrust.io** with "security" in the subject. Please keep credentials, transcripts and account data out of
|
|
196
|
+
public issues.
|
|
197
|
+
|
|
198
|
+
## Links
|
|
199
|
+
|
|
200
|
+
- [worktrust.io](https://worktrust.io): the site. [worktrust.io/preserve](https://worktrust.io/preserve): keeping your history, with or without an account.
|
|
201
|
+
- [What changed in each version](CHANGELOG.md)
|
|
202
|
+
- [SECURITY.md](SECURITY.md) and [AGENTS.md](AGENTS.md)
|
|
203
|
+
- [Licence](#licence): the WorkTrust CLI Licence, in [LICENSE](LICENSE)
|
|
204
|
+
- The reference below: everything above, in full.
|
|
205
|
+
|
|
206
|
+
## Reference
|
|
207
|
+
|
|
208
|
+
The long versions of what is above. The headings are the ones other pages link to.
|
|
209
|
+
|
|
210
|
+
## The npm package and the Python package, in full
|
|
211
|
+
|
|
299
212
|
**The official npm package** is `worktrust`, published by the npm account **worktrustio** with
|
|
300
213
|
provenance from this repository (github.com/fhomey/worktrust-cli). Check it on npmjs.com before you run
|
|
301
214
|
it; a package of another name or from another publisher is not ours. Use the complete package:
|
|
@@ -785,20 +698,35 @@ Then revoke the key in WorkTrust: Sources → Devices → this computer → Revo
|
|
|
785
698
|
|
|
786
699
|
## Remote Agent: steer this computer's agents from your phone or browser (`npx worktrust remote`)
|
|
787
700
|
|
|
788
|
-
Off until you run `npx worktrust remote
|
|
789
|
-
except `status`.
|
|
701
|
+
Off until you run `npx worktrust remote app` (or `remote web`) at this keyboard; an AI agent's shell is refused every
|
|
702
|
+
`remote` command except `status`.
|
|
790
703
|
|
|
791
|
-
- `
|
|
704
|
+
- `app` and `web` make a REMOTE key pair for this computer (Ed25519 and X25519, files of mode 0600 in `~/.worktrust/remote/`),
|
|
792
705
|
never the measurement key, and has it approved in WorkTrust with your second factor; then it starts a service while you
|
|
793
706
|
are logged in (launchd on macOS, a systemd user unit on Linux, linger off; on Windows `npx worktrust remote run` in a
|
|
794
707
|
terminal) and draws a QR code for the WorkTrust app. `pair` draws a new one: five minutes, one phone, once. A phone
|
|
795
708
|
that scanned it is confirmed; one that typed the code instead waits for `npx worktrust remote phones confirm`.
|
|
796
709
|
- Two roads to approve the computer's key: `npx worktrust remote app` shows the approval as a QR code here (no browser);
|
|
797
710
|
the WorkTrust app scans it and you approve with your authenticator code. `npx worktrust remote web` opens the approval
|
|
798
|
-
page in your browser.
|
|
711
|
+
page in your browser. Both take `--gateway` and `--device`; `remote enable` (0.11.6 and before) is gone since 0.11.7.
|
|
799
712
|
- `projects add <folder>` grants a folder (its real path; never your home folder, the disk's root or a folder holding
|
|
800
713
|
keys, keychains, browser profiles or wallets). A phone starts agents only in granted folders, several at once (four by
|
|
801
714
|
default).
|
|
715
|
+
- `connections` lists every phone and browser linked to this computer (name, kind, fingerprint, since, last seen) and
|
|
716
|
+
this computer's own link. `disconnect <number|name|fingerprint>` closes one after two confirmations (y, then the start
|
|
717
|
+
of its fingerprint or its name typed); `disconnect --all` closes every one after you type `close all`. Without a
|
|
718
|
+
terminal both refuse. `phones remove` does the same removal. End a key for your whole account in WorkTrust, Settings,
|
|
719
|
+
Remote Agent.
|
|
720
|
+
- `roots add <folder> [--git-init]` adds a folder your projects live in (the same rules). A phone may open the git
|
|
721
|
+
projects already directly inside it (the most recently changed first, thirty in all with the granted ones) and create
|
|
722
|
+
one new, empty project folder in it. A phone names a project by the id this computer gave it, never by a path. In the
|
|
723
|
+
menu (Remote Agent, Roots) you tick suggested folders or use your system's folder picker instead of typing.
|
|
724
|
+
- `modes allow|deny edit|auto` and `modes status`: the agent modes a phone may start here. Manual and Plan always; Edit
|
|
725
|
+
automatically and Auto only once allowed here (Auto includes Edit). The computer refuses a mode above what you allowed.
|
|
726
|
+
`admin on|off`: whether a change made in the WorkTrust app or on the web (allowed modes, folders, roots, connections)
|
|
727
|
+
is taken here. On by default; each such change asks your authenticator there, carries WorkTrust's signature on that
|
|
728
|
+
exact change for this computer (five minutes, one use), is checked here against the keys built into this CLI, and is
|
|
729
|
+
said in the `remote run` terminal. `admin off` keeps every change at this keyboard. The switch itself changes only here.
|
|
802
730
|
- From a phone you may approve: a file edit inside the project, a test, build or lint command from a short reviewed list,
|
|
803
731
|
and a message an agent sends through a connector, shown whole (channel, every recipient, subject, text, attachment
|
|
804
732
|
names). Everything else is decided at this keyboard or not at all: installs from the network, `git push`, deploys,
|
package/cli-colour.mjs
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* COLOUR WITH MEANING (CLI 0.11.8, owner 2026-11-13). One small module, no dependency, used by the menu (cli-menu.mjs) and by
|
|
3
|
+
* the commands' status lines (worktrust.mjs `say`, so update, check, status, remote and the rest speak the same way):
|
|
4
|
+
*
|
|
5
|
+
* accent a spinner while something runs green a success line (✓, Done)
|
|
6
|
+
* yellow a warning (!) red an error (✗, `worktrust: …` on stderr; the exit code stays as it was)
|
|
7
|
+
* dim secondary text: the command an item runs, a hint bold a title
|
|
8
|
+
*
|
|
9
|
+
* NEVER COLOUR ALONE: a colour only wraps a line that already carries its word or symbol; with colours off the text is byte
|
|
10
|
+
* for byte what it was before 0.11.8. And colours are OFF (colourWanted) for anything a program reads: a hook, the MCP door,
|
|
11
|
+
* a pipe, CI. In order: a hook or the MCP door never, whatever is set; `--no-color` and NO_COLOR turn them off; FORCE_COLOR
|
|
12
|
+
* turns them on (0 or false: off); otherwise only on a terminal whose TERM is not `dumb`. Windows: Node's console layer
|
|
13
|
+
* translates these sequences on a real terminal from Windows 10 on; an older console stays plain.
|
|
14
|
+
*/
|
|
15
|
+
import { release } from "node:os";
|
|
16
|
+
|
|
17
|
+
/** Whether this stream gets colours. Pure: the caller passes what it knows. `machine`: a hook or the MCP door is speaking. */
|
|
18
|
+
export function colourWanted({ env = {}, args = [], isTTY = false, platform = "", osRelease = "", machine = false } = {}) {
|
|
19
|
+
if (machine || env.WORKTRUST_HOOK_INPUT || env.WORKTRUST_MCP_TOKEN) return false;
|
|
20
|
+
if (args.includes("--no-color") || args.includes("--no-colour")) return false;
|
|
21
|
+
if (env.NO_COLOR) return false;
|
|
22
|
+
if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "") return !["0", "false"].includes(String(env.FORCE_COLOR).toLowerCase());
|
|
23
|
+
if (!isTTY || env.TERM === "dumb") return false;
|
|
24
|
+
if (platform === "win32" && Number(String(osRelease).split(".")[0]) < 10) return false;
|
|
25
|
+
return true;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
const SGR = { bold: "1", dim: "2", inverse: "7", red: "31", green: "32", yellow: "33", accent: "36" };
|
|
29
|
+
|
|
30
|
+
/** The painters for one answer of colourWanted. Off, each returns its text unchanged. */
|
|
31
|
+
export function painter(on) {
|
|
32
|
+
const wrap = (code) => (text) => (on ? `\x1b[${code}m${text}\x1b[0m` : text);
|
|
33
|
+
const p = Object.fromEntries(Object.entries(SGR).map(([name, code]) => [name, wrap(code)]));
|
|
34
|
+
/** A whole status line by the symbol or word it already carries; any other line is returned as it is. */
|
|
35
|
+
const status = (line) => {
|
|
36
|
+
if (!on || typeof line !== "string" || line === "") return line;
|
|
37
|
+
if (/^\s*✓ /.test(line) || /^\s*Done\b/.test(line)) return p.green(line);
|
|
38
|
+
if (/^\s*! /.test(line)) return p.yellow(line);
|
|
39
|
+
if (/^\s*✗ /.test(line) || /^worktrust: /.test(line)) return p.red(line);
|
|
40
|
+
if (/^\s*WorkTrust · /.test(line)) return p.bold(line);
|
|
41
|
+
return line;
|
|
42
|
+
};
|
|
43
|
+
return { on: Boolean(on), ...p, status };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** The painters for a stream of this process (stdout by default), by this process's own environment and arguments. */
|
|
47
|
+
export function coloursFor(stream = process.stdout, { machine = false } = {}) {
|
|
48
|
+
return painter(colourWanted({ env: process.env, args: process.argv.slice(2), isTTY: Boolean(stream?.isTTY), platform: process.platform, osRelease: release(), machine }));
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** What a person sees of a text: its length without the colour sequences. */
|
|
52
|
+
export const visibleLength = (text) => [...String(text).replace(/\x1b\[[0-9;]*m/g, "")].length;
|
|
53
|
+
|
|
54
|
+
/** A text cut to `width` visible characters (… at the cut), its colour sequences kept and closed. A line never wraps. */
|
|
55
|
+
export function clip(text, width) {
|
|
56
|
+
if (width < 1 || visibleLength(text) <= width) return text;
|
|
57
|
+
let out = "", seen = 0;
|
|
58
|
+
for (const part of String(text).split(/(\x1b\[[0-9;]*m)/)) {
|
|
59
|
+
if (part.startsWith("\x1b[")) { out += part; continue; }
|
|
60
|
+
for (const char of part) { if (seen === width - 1) return `${out}…${text.includes("\x1b[") ? "\x1b[0m" : ""}`; out += char; seen += 1; }
|
|
61
|
+
}
|
|
62
|
+
return out;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* A spinner in the accent colour while something runs: → stop(). Only on a real terminal with colours on; anywhere else it
|
|
69
|
+
* writes nothing at all, so a pipe, a hook and CI read the same bytes as before. stop() removes the line it drew.
|
|
70
|
+
* It draws on the line the cursor is on, which must be empty: start it between lines, never in the middle of one.
|
|
71
|
+
*/
|
|
72
|
+
export function spinner(words, { stream = process.stdout, paint = coloursFor(stream), interval = 80, delay = 150 } = {}) {
|
|
73
|
+
if (!paint.on || !stream?.isTTY) return () => {};
|
|
74
|
+
let at = 0, shown = false, stopped = false, timer = null;
|
|
75
|
+
const frame = () => { shown = true; stream.write(`\r ${paint.accent(FRAMES[at % FRAMES.length])} ${paint.dim(words)}\x1b[K`); at += 1; };
|
|
76
|
+
// Work that ends at once shows no spinner at all: a line that flashes is worse than none.
|
|
77
|
+
const wait = setTimeout(() => { frame(); timer = setInterval(frame, interval); timer.unref?.(); }, delay);
|
|
78
|
+
wait.unref?.();
|
|
79
|
+
return () => { if (stopped) return; stopped = true; clearTimeout(wait); clearInterval(timer); if (shown) stream.write("\r\x1b[K"); };
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** Run `work` behind a spinner; the spinner is gone before anything else is said, also when the work fails. */
|
|
83
|
+
export async function busyWith(words, work, options) {
|
|
84
|
+
const stop = spinner(words, options);
|
|
85
|
+
try { return await work(); } finally { stop(); }
|
|
86
|
+
}
|