@mainwave/cli 0.8.0 → 0.9.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 +137 -41
- package/dist/adapters/claude-code.js +23 -4
- package/dist/adapters/codex-cli.js +1 -1
- package/dist/adapters/cursor.js +2 -2
- package/dist/core/apply.js +151 -41
- package/dist/core/doctor.js +26 -8
- package/dist/core/effective-settings.js +10 -0
- package/dist/core/entry-script.js +90 -0
- package/dist/core/git-bash.js +40 -0
- package/dist/core/install-hooks.js +126 -43
- package/dist/core/interview.js +53 -3
- package/dist/core/markers.js +678 -140
- package/dist/core/settings.js +16 -5
- package/dist/core/status.js +2 -1
- package/dist/core/wizard.js +46 -1
- package/dist/main.js +16 -9
- package/hooks/cursor-otlp.mjs +1 -1
- package/hooks/github-pr-marker.mjs +35 -22
- package/hooks/glab-mr-marker.mjs +795 -0
- package/hooks/jira-ticket-marker.mjs +27 -15
- package/hooks/linear-ticket-marker.mjs +27 -15
- package/hooks/mainwave-hook-node.mjs +42 -0
- package/hooks/mainwave-hook.mjs +301 -0
- package/hooks/marker-core.mjs +273 -40
- package/hooks/matchers.json +82 -6
- package/hooks/plan-snapshot.mjs +529 -0
- package/hooks/stop-failure.mjs +43 -0
- package/hooks/vocabulary.d.mts +48 -0
- package/hooks/vocabulary.mjs +181 -0
- package/package.json +5 -5
- package/skills/mainwave-instrument/SKILL.md +21 -7
- package/skills/mainwave-instrument/reference/api.md +29 -10
- package/skills/mainwave-instrument/reference/frameworks.md +3 -3
- package/skills/mainwave-instrument/reference/troubleshooting.md +12 -5
- package/skills/mainwave-setup/SKILL.md +47 -12
package/README.md
CHANGED
|
@@ -75,10 +75,12 @@ rather than leaving it stale.
|
|
|
75
75
|
|
|
76
76
|
## What gets captured
|
|
77
77
|
|
|
78
|
-
Setup enables content capture by default: **prompt text**, **shell commands and file paths**,
|
|
79
|
-
**tool result bodies**
|
|
80
|
-
|
|
81
|
-
|
|
78
|
+
Setup enables content capture by default: **prompt text**, **shell commands and file paths**,
|
|
79
|
+
**tool result bodies** and, for Claude Code, **repository names** (`OTEL_METRICS_INCLUDE_REPOSITORY`,
|
|
80
|
+
which stamps the session's repository on Claude Code's own events, metrics and trace spans) are
|
|
81
|
+
sent to your collector alongside the metadata (tool names, tokens, cost, who ran what). The wizard
|
|
82
|
+
says so before it finishes — it is not a question, because what an organization collects is a
|
|
83
|
+
policy decision rather than a per-developer one.
|
|
82
84
|
|
|
83
85
|
To send metadata only:
|
|
84
86
|
|
|
@@ -91,7 +93,8 @@ and per-person activity are all metadata. **Codex is different:** it reports too
|
|
|
91
93
|
approvals only when tool logging is on, so `--opt-in none` leaves Codex's tool views empty. Keep
|
|
92
94
|
`--opt-in tool-details` for Codex if you want those without sending prompt text or tool output.
|
|
93
95
|
|
|
94
|
-
Or pick exactly what you want: `--opt-in tool-details`, `--opt-in prompts,tool-details`,
|
|
96
|
+
Or pick exactly what you want: `--opt-in tool-details`, `--opt-in prompts,tool-details`,
|
|
97
|
+
`--opt-in tool-details,repository`, and so on.
|
|
95
98
|
Re-running with a different `--opt-in` removes the flags it no longer wants rather than leaving them
|
|
96
99
|
stale.
|
|
97
100
|
|
|
@@ -129,18 +132,18 @@ mainwave-cli setup claude-code codex \
|
|
|
129
132
|
--opt-in none --no-markers --yes --json
|
|
130
133
|
```
|
|
131
134
|
|
|
132
|
-
| Flag
|
|
133
|
-
|
|
|
134
|
-
| `--api-key <k>`
|
|
135
|
-
| `--collector-url <u>` / `--api-url <u>`
|
|
136
|
-
| `--ucid <id\|url>` / `--use-case <name>` / `--no-use-case`
|
|
137
|
-
| `--email <e>`
|
|
138
|
-
| `--opt-in prompts,tool-details,tool-content` (or `all` / `none`) | content capture (default: all on; `none` sends metadata only) |
|
|
139
|
-
| `--no-markers`
|
|
140
|
-
| `--new-key`
|
|
141
|
-
| `--yes`
|
|
142
|
-
| `--no-verify` / `--verify-timeout <s>`
|
|
143
|
-
| `--skills` / `--no-skills`
|
|
135
|
+
| Flag | Answers |
|
|
136
|
+
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
137
|
+
| `--api-key <k>` | the collector key (otherwise minted for you when signed in) |
|
|
138
|
+
| `--collector-url <u>` / `--api-url <u>` | which deployment |
|
|
139
|
+
| `--ucid <id\|url>` / `--use-case <name>` / `--no-use-case` | pin one use case, or `--no-use-case` to unpin (default: none) |
|
|
140
|
+
| `--email <e>` | attribution identity for tools that need it injected |
|
|
141
|
+
| `--opt-in prompts,tool-details,tool-content,repository` (or `all` / `none`) | content capture (default: all on; `none` sends metadata only; `repository` is Claude Code's repository names) |
|
|
142
|
+
| `--no-markers` | skip the Mainwave hooks (installed by default): the ticket & PR markers and the Claude plan snapshot |
|
|
143
|
+
| `--new-key` | mint a fresh machine key instead of reusing this machine's |
|
|
144
|
+
| `--yes` | write without the confirmation prompt |
|
|
145
|
+
| `--no-verify` / `--verify-timeout <s>` | the closing first-span check |
|
|
146
|
+
| `--skills` / `--no-skills` | the agent skills payload |
|
|
144
147
|
|
|
145
148
|
Without a terminal the CLI never prompts: it answers from flags and environment, or fails naming the
|
|
146
149
|
flag it needed. `status` and `doctor` also take `--json`.
|
|
@@ -164,7 +167,7 @@ rather than counted as installed.
|
|
|
164
167
|
|
|
165
168
|
The payload is installed at user scope, like the telemetry config — the skills teach an agent how to
|
|
166
169
|
use Mainwave anywhere, so a copy per repo would be pure duplication. Re-running setup refreshes them,
|
|
167
|
-
the same way it refreshes the
|
|
170
|
+
the same way it refreshes the hook scripts.
|
|
168
171
|
|
|
169
172
|
```bash
|
|
170
173
|
mainwave-cli setup claude-code --skills-only # instructions, no telemetry config
|
|
@@ -182,38 +185,113 @@ mainwave-cli login --device
|
|
|
182
185
|
|
|
183
186
|
For Claude Code, setup also installs **ticket & PR markers**: small post-tool hooks that emit one
|
|
184
187
|
event when a Linear or Jira issue is filed and one when a pull request is opened with
|
|
185
|
-
`gh pr create
|
|
188
|
+
`gh pr create` or a GitLab merge request is opened with `glab mr create` (or a `glab api` POST to a
|
|
189
|
+
project's `merge_requests` endpoint). Claude Code starts the pull-request hooks only for a Bash
|
|
190
|
+
command that begins with `gh` or `glab` (a wrapper or a path, such as `env gh …` or
|
|
191
|
+
`/usr/local/bin/glab …`, isn't matched), and runs every Mainwave hook in the background, so none of
|
|
192
|
+
them adds time to a tool call. They are what populates "Tickets filed" and "PRs created" on the use case — without
|
|
186
193
|
them those counts read zero, which is why they are on by default rather than a question.
|
|
187
194
|
|
|
188
195
|
What leaves your machine: the issue key, whether it was a create or an update, and the PR's
|
|
189
|
-
url/number/title plus aggregate diff counts.
|
|
196
|
+
url/number/title plus aggregate diff counts. For a GitLab merge request that is the url, number,
|
|
197
|
+
title, project id and the changed-file count. Never ticket bodies, never diff content. The hooks fail
|
|
190
198
|
open — a telemetry problem can never block or slow a coding session — and count forward only from
|
|
191
199
|
when you enable them.
|
|
192
200
|
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
201
|
+
For Claude Code, the same install adds a **Claude plan snapshot**: a hook on Claude Code's
|
|
202
|
+
`UserPromptSubmit` event (each prompt you submit) that reads Claude Code's local account record (`.claude.json`) and sends one event every time
|
|
203
|
+
it runs. What leaves your machine: your Claude account id, organization id and email (the identity
|
|
204
|
+
Claude Code's own telemetry already carries); from your account profile, exactly as Claude Code
|
|
205
|
+
stores them, the plan's organization type, seat tier, rate-limit tier and billing type, your
|
|
206
|
+
organization and workspace roles, when the subscription started, the trial's end date and length,
|
|
207
|
+
the date of your first Claude Code use, and when Claude Code fetched that profile; from Claude
|
|
208
|
+
Code's usage cache, your 5-hour and 7-day usage and when they reset, each rate limit's percent used,
|
|
209
|
+
group, severity, whether it is the active one and when it resets (and, for a limit Claude Code
|
|
210
|
+
applies per model, which model it is, by the name Claude Code stores), whether extra usage is on, the
|
|
211
|
+
extra-usage amount spent and monthly limit, their currency, whether the spend limit is reached,
|
|
212
|
+
whether and why extra usage is disabled, and when Claude Code fetched those figures. Each event also
|
|
213
|
+
carries which event sent it, the prompt id, the
|
|
214
|
+
session id, the ids of the turn's trace and span, and the session's OpenTelemetry resource attributes, as the
|
|
215
|
+
other markers do. Never your prompt, and nothing else in that file. A figure Claude Code hasn't
|
|
216
|
+
recorded is left out, not sent as zero; Claude Code refreshes its usage figures only when you open
|
|
217
|
+
its usage view, so the same figures repeat until then, each with the time Claude Code fetched it. Figures
|
|
218
|
+
refreshed by a `/usage` just before you quit reach Mainwave at your next prompt, since Claude Code
|
|
219
|
+
keeps them on disk. Nothing is sent when a session ends.
|
|
220
|
+
It runs only in sessions signed in with a Claude account, keeps no state it reads back (a one-line
|
|
221
|
+
timestamp file, `~/.mainwave/logs/plan-snapshot.log.ok`, records the last successful send for `doctor`),
|
|
222
|
+
and never makes a
|
|
223
|
+
prompt wait: Claude Code runs it in the background without waiting for it, and it gives up on the
|
|
224
|
+
send after 4 seconds. Under `claude -p`, Claude Code stops a snapshot that is still sending when the
|
|
225
|
+
run ends, so that snapshot is lost. Setup says that it is on, and what it sends, on every run.
|
|
226
|
+
It has no switch of its own: it installs wherever setup installs the Mainwave hooks for Claude Code,
|
|
227
|
+
and `--no-markers`, which installs no Mainwave hooks at all, leaves it out too.
|
|
228
|
+
Where Claude Code runs only the hooks your organization's managed settings deliver
|
|
229
|
+
(`allowManagedHooksOnly`), or a settings file turns hooks off (`disableAllHooks`), and the managed
|
|
230
|
+
settings don't send the snapshot themselves, your own copy can't run; setup says so and names the
|
|
231
|
+
setting.
|
|
232
|
+
|
|
233
|
+
It comes with one smaller Claude account event. When a turn ends on an API error (a rate
|
|
234
|
+
limit, a billing error, an overloaded API, a sign-in that stopped working), one event carries the
|
|
235
|
+
error type only — never the error details or message. It also carries the session id, the prompt id,
|
|
236
|
+
the turn's trace ids and, when the session is signed in with a Claude account, your Claude account id
|
|
237
|
+
and email, so it lines up with the plan snapshot. Unlike the snapshot, it is sent from any Claude
|
|
238
|
+
Code session.
|
|
239
|
+
|
|
240
|
+
Mechanics: every Mainwave hook group in your settings runs one small shell entry,
|
|
241
|
+
`~/.mainwave/hooks/managed/mainwave-hook.sh`, with the event it is for (`claude-code PostToolUse gh`,
|
|
242
|
+
`claude-code UserPromptSubmit`, …). The entry prints nothing, never reads the hook input itself
|
|
243
|
+
(only Codex's one Bash hook does, to skip commands that can't open a PR or MR), and exits 0 whatever
|
|
244
|
+
happens; it runs the current release's scripts, kept in `~/.mainwave/hooks/managed/versions/`.
|
|
245
|
+
Setup also adds a session-start hook that runs
|
|
246
|
+
`{ cd "$HOME" && npx -y --registry=https://registry.npmjs.org @mainwave/cli@latest install-hooks --quiet; } >/dev/null 2>&1; exit 0`
|
|
247
|
+
in the background when a session starts, resumes or forks — its output discarded and exit 0
|
|
248
|
+
whatever happens, so an unreachable npm registry never shows up as a failed hook: it installs the latest release's scripts
|
|
249
|
+
and points the entry at them, and keeps the hooks setup installed in your user settings current —
|
|
250
|
+
on the events setup told you about only. A release that adds a new kind of hook waits for your next
|
|
251
|
+
setup run, which says what it sends. It is written only when at least one hook is on, so
|
|
252
|
+
`--no-markers` writes no hooks at all. Your `--no-markers` choice is also recorded as a file
|
|
253
|
+
under `~/.mainwave/hooks/off/`, which the entry reads, so a hook you turned off sends nothing even
|
|
254
|
+
from a copy setup didn't write (unless your organization's managed settings deliver it, which you
|
|
255
|
+
can't turn off). Re-running setup removes hooks written by an earlier CLI version, and the scripts
|
|
256
|
+
an earlier version copied into `~/.mainwave/hooks/` once nothing runs them. To disable the hooks,
|
|
257
|
+
the plan snapshot included, re-run setup with `--no-markers` — the entries are removed cleanly. `doctor` checks that the entry is installed, that it names an installed release with every
|
|
258
|
+
script, and that every Mainwave hook group is in the background and narrowed by its matcher.
|
|
259
|
+
|
|
260
|
+
On Windows, the Claude Code hooks need Git for Windows. Claude Code runs hook commands through Git
|
|
261
|
+
Bash, and through PowerShell when it finds none, where the entry's shell command can't run. Without
|
|
262
|
+
Git Bash, setup installs no Claude Code hooks and says why, and `doctor` reports it as an error;
|
|
263
|
+
hooks an earlier CLI version installed that run `node` directly are kept. Claude Code looks for Git
|
|
264
|
+
Bash at `CLAUDE_CODE_GIT_BASH_PATH`, then Git for Windows' default install paths, then beside the
|
|
265
|
+
`git` on your `PATH`, and setup looks in the same places: if yours is elsewhere, set
|
|
266
|
+
`CLAUDE_CODE_GIT_BASH_PATH` to its `bash.exe` and re-run setup.
|
|
198
267
|
|
|
199
268
|
Organizations that configure Claude Code centrally (managed settings from the Claude admin console,
|
|
200
|
-
or an MDM `managed-settings.json`) deliver the markers
|
|
201
|
-
starts or
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
269
|
+
or an MDM `managed-settings.json`) deliver the markers and the Claude plan snapshot without anyone
|
|
270
|
+
running setup: when a session starts, resumes or forks (not on `/clear` or a compaction), the
|
|
271
|
+
managed settings run the same `install-hooks` command — from your home directory, so a repository's
|
|
272
|
+
own `.npmrc` or `node_modules` can't choose what runs — which installs or refreshes the scripts in
|
|
273
|
+
`~/.mainwave/hooks/managed/` with no prompts, no sign-in and no network calls of its own. `@latest`
|
|
274
|
+
means each new release reaches your machine at its next session start, whatever copy of the CLI you
|
|
275
|
+
have installed: npx asks the registry for the current release each time, and while you're offline
|
|
276
|
+
the scripts already installed keep working. Each release's scripts sit in their own directory and
|
|
277
|
+
the entry is switched to a new one only once it is complete, so two installs racing never mix
|
|
278
|
+
releases. The org-wide payload writes exactly the hook commands setup writes, so on a machine with
|
|
279
|
+
both, Claude Code runs each hook once. Managed settings your admin pasted before the entry existed
|
|
280
|
+
run one script per hook, in the foreground, and have no plan snapshot; they keep working, and get
|
|
281
|
+
the current hooks only when your admin pastes the current version from Mainwave's Org-wide setup,
|
|
282
|
+
since `install-hooks` refreshes the scripts, not your organization's managed settings. An admin who
|
|
283
|
+
adds the current version without removing the earlier one gets every marker twice; `doctor` flags
|
|
284
|
+
both being present. When managed settings deliver the
|
|
285
|
+
hooks, `install-hooks` also removes your user settings' copy of each hook they deliver, so each ticket and PR is marked once and each prompt sends one plan snapshot, and `setup` itself leaves
|
|
286
|
+
out any hook your managed settings already run. Your own session-start hook stays: while the
|
|
287
|
+
managed settings run the same command Claude Code runs it once (a payload pasted before the
|
|
288
|
+
silent form runs beside it until your admin re-pastes — harmless), and if they stop delivering the
|
|
289
|
+
hooks it puts back the ones setup installed for you. It never edits project settings; `doctor` lists
|
|
212
290
|
every settings file that installs the hooks and warns when two of them would fire for the same
|
|
213
291
|
ticket or PR. The org-wide setup follows how Claude Code 2.1.282 and later apply managed settings;
|
|
214
292
|
`doctor` warns on an older install.
|
|
215
293
|
|
|
216
|
-
Two kinds of session don't get the admin console's markers:
|
|
294
|
+
Two kinds of session don't get the admin console's markers or plan snapshot:
|
|
217
295
|
|
|
218
296
|
- A session that skips server-managed settings: one started with a `CLAUDE_CODE_USE_*` provider
|
|
219
297
|
variable or a non-Anthropic `ANTHROPIC_BASE_URL` in your shell or user settings. Once the org's
|
|
@@ -231,9 +309,10 @@ Two kinds of session don't get the admin console's markers:
|
|
|
231
309
|
Under the org's settings, which carry no use case of their own, a marker is attributed through the
|
|
232
310
|
Claude account the session is signed in with. A session signed in another way (an API key, a
|
|
233
311
|
`CLAUDE_CODE_OAUTH_TOKEN`, a cloud provider through MDM delivery) sends markers no developer is
|
|
234
|
-
attached to.
|
|
312
|
+
attached to, and no plan snapshot.
|
|
235
313
|
|
|
236
|
-
Markers are available only for tools with a hooks mechanism (today: Claude Code
|
|
314
|
+
Markers are available only for tools with a hooks mechanism (today: Claude Code and Codex; the plan
|
|
315
|
+
snapshot is Claude Code only). For other tools
|
|
237
316
|
the wizard says so instead of appearing to succeed.
|
|
238
317
|
|
|
239
318
|
## Signing in
|
|
@@ -278,7 +357,7 @@ mainwave-cli doctor <adapter> # settings hierarchy + health checks
|
|
|
278
357
|
mainwave-cli doctor <adapter> --validate # also auth-check against the collector
|
|
279
358
|
mainwave-cli edit <adapter> # open the settings file in $EDITOR
|
|
280
359
|
mainwave-cli env <adapter> # print shell export lines
|
|
281
|
-
mainwave-cli install-hooks [--quiet] # install or refresh the
|
|
360
|
+
mainwave-cli install-hooks [--quiet] # install or refresh the Mainwave hook entry and the latest release's scripts
|
|
282
361
|
mainwave-cli --help
|
|
283
362
|
```
|
|
284
363
|
|
|
@@ -315,6 +394,23 @@ permissions in your home directory — never inside a repository. `status` shows
|
|
|
315
394
|
knows about, masked; `doctor <adapter>` walks the full hierarchy, including repo-local files an
|
|
316
395
|
older CLI or a colleague may have written.
|
|
317
396
|
|
|
397
|
+
## Removing Mainwave
|
|
398
|
+
|
|
399
|
+
Deleting `~/.mainwave` is safe. Every Mainwave hook checks that its script is there and exits
|
|
400
|
+
quietly when it isn't, so nothing reaches your coding sessions. Where your organization delivers
|
|
401
|
+
Mainwave through Claude Code's managed settings, the next session start reinstalls what the hooks
|
|
402
|
+
run and telemetry resumes on its own. A setup you ran yourself stays off until you run
|
|
403
|
+
`mainwave-cli setup` again — signed in, that creates a new key, since the record of the old one
|
|
404
|
+
lived there — and Cursor and VS Code Copilot Chat stop sending until then.
|
|
405
|
+
|
|
406
|
+
To stop entirely, also remove the Mainwave entries from your tools' settings — for Claude Code,
|
|
407
|
+
`mainwave-cli setup claude-code --no-markers` removes its hooks, or delete the hook groups that
|
|
408
|
+
name `mainwave-hook.sh`, `install-hooks` or `--managed-by @mainwave/cli` from
|
|
409
|
+
`~/.claude/settings.json`, along with the `OTEL_*` telemetry keys setup wrote. Hooks delivered
|
|
410
|
+
through your organization's managed settings stay until your Claude admin removes them. Hooks
|
|
411
|
+
now log under `~/.mainwave/logs/`; releases before that logged to `~/.mainwave-*.log` files in your
|
|
412
|
+
home directory, which are left for you to delete.
|
|
413
|
+
|
|
318
414
|
## License
|
|
319
415
|
|
|
320
416
|
Apache-2.0
|
|
@@ -19,6 +19,7 @@ const MANAGED_ENV_KEYS = [
|
|
|
19
19
|
'OTEL_LOG_USER_PROMPTS',
|
|
20
20
|
'OTEL_LOG_TOOL_DETAILS',
|
|
21
21
|
'OTEL_LOG_TOOL_CONTENT',
|
|
22
|
+
'OTEL_METRICS_INCLUDE_REPOSITORY',
|
|
22
23
|
];
|
|
23
24
|
const buildResourceAttrs = (ucid, userEmail) => {
|
|
24
25
|
const deploymentEnv = process.env.MAINWAVE_DEPLOYMENT_ENV ?? 'production';
|
|
@@ -79,6 +80,7 @@ const parseEnv = (env) => {
|
|
|
79
80
|
userPrompts: env.OTEL_LOG_USER_PROMPTS === '1',
|
|
80
81
|
toolDetails: env.OTEL_LOG_TOOL_DETAILS === '1',
|
|
81
82
|
toolContent: env.OTEL_LOG_TOOL_CONTENT === '1',
|
|
83
|
+
repository: env.OTEL_METRICS_INCLUDE_REPOSITORY === '1',
|
|
82
84
|
};
|
|
83
85
|
return out;
|
|
84
86
|
};
|
|
@@ -100,6 +102,8 @@ const buildEnv = ({ ucid, collectorUrl, apiKey, optIns, userEmail, }) => {
|
|
|
100
102
|
env.OTEL_LOG_TOOL_DETAILS = '1';
|
|
101
103
|
if (optIns.toolContent)
|
|
102
104
|
env.OTEL_LOG_TOOL_CONTENT = '1';
|
|
105
|
+
if (optIns.repository)
|
|
106
|
+
env.OTEL_METRICS_INCLUDE_REPOSITORY = '1';
|
|
103
107
|
return env;
|
|
104
108
|
};
|
|
105
109
|
const collectChecks = (env) => {
|
|
@@ -160,11 +164,11 @@ const managedSettingsDir = (() => {
|
|
|
160
164
|
return 'C:\\Program Files\\ClaudeCode';
|
|
161
165
|
return '/etc/claude-code';
|
|
162
166
|
})();
|
|
163
|
-
const
|
|
167
|
+
const hierarchyFor = (userDir) => [
|
|
164
168
|
{
|
|
165
169
|
id: 'managed-server',
|
|
166
170
|
label: 'Managed (server, cached)',
|
|
167
|
-
path: join(
|
|
171
|
+
path: join(userDir, 'remote-settings.json'),
|
|
168
172
|
kind: 'file',
|
|
169
173
|
managedSource: 'server',
|
|
170
174
|
},
|
|
@@ -197,10 +201,11 @@ const HIERARCHY = [
|
|
|
197
201
|
{
|
|
198
202
|
id: 'user',
|
|
199
203
|
label: 'User (global)',
|
|
200
|
-
path: join(
|
|
204
|
+
path: join(userDir, 'settings.json'),
|
|
201
205
|
kind: 'file',
|
|
202
206
|
},
|
|
203
207
|
];
|
|
208
|
+
const HIERARCHY = hierarchyFor(USER_DIR);
|
|
204
209
|
const EXPORTER_SELECTORS = ['OTEL_TRACES_EXPORTER', 'OTEL_METRICS_EXPORTER', 'OTEL_LOGS_EXPORTER'];
|
|
205
210
|
const OFF_SWITCH_CONTENT_KEYS = [
|
|
206
211
|
'OTEL_LOG_USER_PROMPTS',
|
|
@@ -446,6 +451,20 @@ export const claudeCode = {
|
|
|
446
451
|
label: 'skill directory',
|
|
447
452
|
},
|
|
448
453
|
markers: {
|
|
449
|
-
disclosure: 'Sends Linear/Jira issue ids and GitHub PR urls to the collector — never ticket bodies or diff content.',
|
|
454
|
+
disclosure: 'Sends Linear/Jira issue ids and GitHub PR / GitLab MR urls to the collector — never ticket bodies or diff content.',
|
|
455
|
+
planSnapshotDisclosure: 'On each prompt it sends, from your Claude account: its email, account id and organization id; ' +
|
|
456
|
+
"the plan's tier names and roles; the subscription start date, trial end date and length, first-use date and profile refresh time; " +
|
|
457
|
+
'your usage against its rate limits; whether extra usage is on, its amount, limit and currency, whether the limit is reached and why it is off; ' +
|
|
458
|
+
'when Claude Code fetched those figures; and the session id, prompt id and turn trace and span ids. ' +
|
|
459
|
+
"It never includes prompt text; prompt text reaches Mainwave only through Claude Code's own telemetry, when prompt capture is on (it is by default) or raw API body logging is enabled. " +
|
|
460
|
+
'When a turn ends on an API error, it sends only the error type ' +
|
|
461
|
+
'(never its message) with the same identity and ids.',
|
|
450
462
|
},
|
|
451
463
|
};
|
|
464
|
+
export const claudeCodeFor = (userDir) => ({
|
|
465
|
+
...claudeCode,
|
|
466
|
+
paths: { ...claudeCode.paths, global: join(userDir, 'settings.json') },
|
|
467
|
+
detect: () => hasPath(userDir) || hasBinary('claude'),
|
|
468
|
+
hierarchy: hierarchyFor(userDir),
|
|
469
|
+
instructionSurface: { ...claudeCode.instructionSurface, global: join(userDir, 'skills') },
|
|
470
|
+
});
|
|
@@ -189,7 +189,7 @@ export const codexCli = {
|
|
|
189
189
|
collectFileChecks,
|
|
190
190
|
normalizeForGenericChecks,
|
|
191
191
|
markers: {
|
|
192
|
-
disclosure: 'Sends Linear/Jira issue ids and GitHub PR urls to the collector — never ticket bodies or diff content.',
|
|
192
|
+
disclosure: 'Sends Linear/Jira issue ids and GitHub PR / GitLab MR urls to the collector — never ticket bodies or diff content.',
|
|
193
193
|
hooksFile: {
|
|
194
194
|
path: join(homedir(), '.codex', 'hooks.json'),
|
|
195
195
|
localPath: join('.codex', 'hooks.json'),
|
package/dist/adapters/cursor.js
CHANGED
|
@@ -5,7 +5,7 @@ import { cursorHooksJsonCodec } from '../core/codecs/cursor-hooks-json.js';
|
|
|
5
5
|
import { envFileCodec } from '../core/codecs/env-file.js';
|
|
6
6
|
import { hasBinary, hasPath } from '../core/detect.js';
|
|
7
7
|
import { buildHeaders, HEADER_NAME, headerBearerToken, kvPairsHeaders } from '../core/headers.js';
|
|
8
|
-
import {
|
|
8
|
+
import { buildScriptHookCommand, installedHooksDir } from '../core/markers.js';
|
|
9
9
|
import { isSamePath } from '../core/settings.js';
|
|
10
10
|
import { VERSION } from '../core/version.js';
|
|
11
11
|
const SOURCE_VALUE = 'coding_agent.cursor';
|
|
@@ -34,7 +34,7 @@ const ALWAYS_EVENTS = [
|
|
|
34
34
|
const PROMPT_EVENT = 'beforeSubmitPrompt';
|
|
35
35
|
const hookKey = (event) => `hooks.${event}`;
|
|
36
36
|
const HOOKS_MANAGED_KEYS = [...ALWAYS_EVENTS, PROMPT_EVENT].map(hookKey);
|
|
37
|
-
const hookCommand = () =>
|
|
37
|
+
const hookCommand = () => buildScriptHookCommand(join(installedHooksDir(), 'cursor-otlp.mjs'), VERSION);
|
|
38
38
|
const stripTrailingSlash = (url) => url.replace(/\/+$/, '');
|
|
39
39
|
const buildHeadersValue = (apiKey, ucid) => kvPairsHeaders.encode(buildHeaders({ apiKey, ucid, source: SOURCE_VALUE }));
|
|
40
40
|
const parseHeaders = (raw) => kvPairsHeaders.decode(raw) ?? {};
|
package/dist/core/apply.js
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
import { randomUUID } from 'node:crypto';
|
|
2
|
-
import {
|
|
2
|
+
import { dirname, resolve } from 'node:path';
|
|
3
3
|
import { adapters } from '../adapters/index.js';
|
|
4
|
-
import { activeHierarchy } from './effective-settings.js';
|
|
4
|
+
import { activeHierarchy, effectiveEnv } from './effective-settings.js';
|
|
5
5
|
import { color, renderDiff } from './format.js';
|
|
6
|
-
import {
|
|
6
|
+
import { claudeHookShellMissing, GIT_BASH_FIX, GIT_BASH_MISSING_REASON } from './git-bash.js';
|
|
7
|
+
import { activeManagedScans, BOOTSTRAP_KEY, commandGeneration, copyHookScripts, DEFAULT_MARKER_TOOL, describeMarkersPlan, hooksBlocked, hostRunsBootstrap, installedHooksDir, isPlanSnapshot, isPlanSnapshotRoute, legacyCommandSends, managedDeliversEntry, managedDeliversPlanSnapshot, managedHooksDir, managedMarkerDeliveries, matchersForTool, packagedHooksDir, planMarkers, prepareMarkersFile, readPackagedMatchers, routeLabel, scanForMarkers, scanRoutes, selectHookMatchers, syncManagedHooks, syncOrgDelivered, userHookGroups, writeOptOutFlags, } from './markers.js';
|
|
7
8
|
import { isManagedLayer } from './layer-policy.js';
|
|
8
9
|
import { adapterEffective } from './status.js';
|
|
9
10
|
import { applyUpdate, prepareUpdate, readExistingEnv } from './settings.js';
|
|
@@ -92,19 +93,38 @@ export const planAdapter = async (adapter, answers, context = {}) => {
|
|
|
92
93
|
codec: adapter.codec,
|
|
93
94
|
});
|
|
94
95
|
const markersOn = adapter.markers ? answers.markers : null;
|
|
96
|
+
let planSnapshotOn = null;
|
|
97
|
+
let planSnapshotOrgDelivered = false;
|
|
95
98
|
let markersPlan = null;
|
|
96
|
-
let hookFiles = [];
|
|
97
99
|
let separateMarkersUpdate = null;
|
|
98
100
|
let markersCarrier = null;
|
|
101
|
+
let hookHost = null;
|
|
102
|
+
let stageHooks = false;
|
|
103
|
+
let hookEvents = [];
|
|
104
|
+
let orgDeliversEntry = false;
|
|
105
|
+
let hookShellMissing = false;
|
|
99
106
|
if (markersOn !== null) {
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
const
|
|
106
|
-
|
|
107
|
-
|
|
107
|
+
hookHost = adapter.markers?.runtimeTool ?? DEFAULT_MARKER_TOOL;
|
|
108
|
+
const hosted = matchersForTool(await readPackagedMatchers(), hookHost);
|
|
109
|
+
if (hosted.some(isPlanSnapshot))
|
|
110
|
+
planSnapshotOn = markersOn;
|
|
111
|
+
hookShellMissing = await hookShellMissingFor(adapter, async () => effectiveEnv(adapter, adapter.codec.readEnv(primaryUpdate.next)));
|
|
112
|
+
const on = { markers: markersOn };
|
|
113
|
+
const selected = hookShellMissing ? [] : selectHookMatchers(hosted, on);
|
|
114
|
+
stageHooks = selected.length > 0;
|
|
115
|
+
hookEvents = [
|
|
116
|
+
...new Set([
|
|
117
|
+
...(stageHooks && hostRunsBootstrap(hookHost) ? ['SessionStart'] : []),
|
|
118
|
+
...selected.map((m) => m.event),
|
|
119
|
+
]),
|
|
120
|
+
];
|
|
121
|
+
const managedScans = adapter.markers?.hooksFile
|
|
122
|
+
? []
|
|
123
|
+
: await scanForMarkers((await activeHierarchy(adapter)).filter(isManagedLayer));
|
|
124
|
+
const delivered = managedMarkerDeliveries(managedScans);
|
|
125
|
+
orgDeliversEntry = managedDeliversEntry(managedScans);
|
|
126
|
+
planSnapshotOrgDelivered = planSnapshotOn !== null && managedDeliversPlanSnapshot(managedScans);
|
|
127
|
+
const groups = hookShellMissing ? [] : userHookGroups(hosted, on, delivered, hookHost);
|
|
108
128
|
const hooksFile = adapter.markers?.hooksFile;
|
|
109
129
|
if (hooksFile) {
|
|
110
130
|
const prepared = await prepareMarkersFile(hooksFile.path, hooksFile.codec, groups);
|
|
@@ -113,7 +133,14 @@ export const planAdapter = async (adapter, answers, context = {}) => {
|
|
|
113
133
|
markersCarrier = prepared.update;
|
|
114
134
|
}
|
|
115
135
|
else {
|
|
116
|
-
|
|
136
|
+
const keepRunnable = (o, g) => !(markersOn &&
|
|
137
|
+
o === 'cli' &&
|
|
138
|
+
commandGeneration(g.command) === 'legacy' &&
|
|
139
|
+
legacyCommandSends(g.command) &&
|
|
140
|
+
/^node "/.test(g.command));
|
|
141
|
+
markersPlan = hookShellMissing
|
|
142
|
+
? planMarkers(primaryUpdate.next, groups, keepRunnable)
|
|
143
|
+
: planMarkers(primaryUpdate.next, groups);
|
|
117
144
|
primaryUpdate.next = markersPlan.next;
|
|
118
145
|
markersCarrier = primaryUpdate;
|
|
119
146
|
}
|
|
@@ -143,14 +170,59 @@ export const planAdapter = async (adapter, answers, context = {}) => {
|
|
|
143
170
|
input,
|
|
144
171
|
changed,
|
|
145
172
|
markersOn,
|
|
173
|
+
planSnapshotOn,
|
|
174
|
+
planSnapshotOrgDelivered,
|
|
146
175
|
markersPlan,
|
|
147
176
|
markersCarrier,
|
|
148
|
-
|
|
177
|
+
hookHost,
|
|
178
|
+
stageHooks,
|
|
179
|
+
hookEvents,
|
|
180
|
+
orgDeliversEntry,
|
|
181
|
+
hookShellMissing,
|
|
149
182
|
...(teamUcid ? { teamUcid } : {}),
|
|
150
183
|
...(keptPin ? { keptPin: pin } : {}),
|
|
151
184
|
};
|
|
152
185
|
};
|
|
186
|
+
export const hookShellMissingFor = async (adapter, settingsEnv) => {
|
|
187
|
+
if (process.platform !== 'win32')
|
|
188
|
+
return false;
|
|
189
|
+
const markers = adapter.markers;
|
|
190
|
+
if (markers === undefined || markers.hooksFile !== undefined)
|
|
191
|
+
return false;
|
|
192
|
+
if ((markers.runtimeTool ?? DEFAULT_MARKER_TOOL) !== DEFAULT_MARKER_TOOL)
|
|
193
|
+
return false;
|
|
194
|
+
return claudeHookShellMissing({ ...process.env, ...((await settingsEnv()) ?? {}) });
|
|
195
|
+
};
|
|
196
|
+
export const managedSnapshotDelivery = async (adapter) => {
|
|
197
|
+
if (!adapter.markers?.planSnapshotDisclosure || adapter.markers.hooksFile)
|
|
198
|
+
return false;
|
|
199
|
+
const managed = (await activeHierarchy(adapter)).filter(isManagedLayer);
|
|
200
|
+
return managedDeliversPlanSnapshot(await scanForMarkers(managed));
|
|
201
|
+
};
|
|
202
|
+
export const planSnapshotBlocked = async (adapter) => {
|
|
203
|
+
if (!adapter.markers?.planSnapshotDisclosure || adapter.markers.hooksFile)
|
|
204
|
+
return undefined;
|
|
205
|
+
if (await hookShellMissingFor(adapter, () => effectiveEnv(adapter))) {
|
|
206
|
+
return { reason: GIT_BASH_MISSING_REASON, fix: GIT_BASH_FIX, notInstalled: true };
|
|
207
|
+
}
|
|
208
|
+
const scans = await scanForMarkers(await activeHierarchy(adapter));
|
|
209
|
+
const blocked = hooksBlocked(scans);
|
|
210
|
+
if (blocked.developer === undefined)
|
|
211
|
+
return undefined;
|
|
212
|
+
if (blocked.managed === undefined && managedDeliversPlanSnapshot(scans))
|
|
213
|
+
return undefined;
|
|
214
|
+
const fix = blocked.managed !== undefined
|
|
215
|
+
? 'Only your Claude admin can turn hooks back on.'
|
|
216
|
+
: blocked.managedOnly
|
|
217
|
+
? 'Ask your Claude admin to deliver it through managed settings.'
|
|
218
|
+
: 'Remove disableAllHooks from that file to let it run.';
|
|
219
|
+
return { reason: blocked.developer, fix };
|
|
220
|
+
};
|
|
153
221
|
export const renderPlan = (plan) => {
|
|
222
|
+
for (const { message } of plan.markersPlan?.skipped ?? []) {
|
|
223
|
+
say('');
|
|
224
|
+
say(color.yellow(`! ${plan.adapter.displayName}: ${message}`));
|
|
225
|
+
}
|
|
154
226
|
if (plan.changed.length === 0) {
|
|
155
227
|
say('');
|
|
156
228
|
say(color.dim(`${plan.adapter.displayName}: no changes needed in ${plan.primaryPath}.`));
|
|
@@ -175,17 +247,30 @@ export const renderPlan = (plan) => {
|
|
|
175
247
|
}
|
|
176
248
|
};
|
|
177
249
|
export const planHasChanges = (plans) => plans.some((p) => p.changed.length > 0);
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
250
|
+
const defaultHookDirs = () => ({
|
|
251
|
+
managedDir: managedHooksDir(),
|
|
252
|
+
flatDir: installedHooksDir(),
|
|
253
|
+
});
|
|
254
|
+
export const userHooksPath = (adapter) => adapter.markers?.hooksFile?.path ?? adapter.paths.global;
|
|
255
|
+
export const writePlan = async (plan, dirs = defaultHookDirs()) => {
|
|
256
|
+
if (plan.stageHooks) {
|
|
257
|
+
const updated = await syncManagedHooks(await readPackagedMatchers(), packagedHooksDir(), dirs.managedDir, VERSION);
|
|
185
258
|
say('');
|
|
186
|
-
say(
|
|
187
|
-
? color.dim(`Hook scripts
|
|
188
|
-
: color.green(`✓ Hook scripts installed to ${
|
|
259
|
+
say(updated.length === 0
|
|
260
|
+
? color.dim(`Hook scripts in ${dirs.managedDir} are current.`)
|
|
261
|
+
: color.green(`✓ Hook scripts installed to ${dirs.managedDir}`));
|
|
262
|
+
}
|
|
263
|
+
if (plan.hookHost !== null) {
|
|
264
|
+
await writeOptOutFlags(plan.hookHost, { markers: plan.markersOn ?? undefined }, resolve(dirs.managedDir, '..'));
|
|
265
|
+
if (plan.hookHost === DEFAULT_MARKER_TOOL) {
|
|
266
|
+
await syncOrgDelivered(plan.orgDeliversEntry, dirname(plan.adapter.paths.global), dirs.managedDir);
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
const bundled = plan.adapter.bundledHookScripts ?? [];
|
|
270
|
+
if (bundled.length > 0) {
|
|
271
|
+
const dest = await copyHookScripts(bundled, packagedHooksDir(), dirs.flatDir);
|
|
272
|
+
say('');
|
|
273
|
+
say(color.dim(`Hook scripts refreshed in ${dest}.`));
|
|
189
274
|
}
|
|
190
275
|
for (const { update } of plan.changed) {
|
|
191
276
|
const result = await applyUpdate(update);
|
|
@@ -202,10 +287,7 @@ export const printMarkerCoexistenceNotes = async (adapter, targetPath, markersOn
|
|
|
202
287
|
const blockedBy = hooksBlocked(scans);
|
|
203
288
|
const blocked = blockedBy.developer;
|
|
204
289
|
const targetHasMarkers = scans.some((s) => resolve(s.path) === resolve(targetPath) && s.groups.some((g) => g.ownership === 'cli'));
|
|
205
|
-
if (
|
|
206
|
-
blocked !== undefined &&
|
|
207
|
-
targetHasMarkers &&
|
|
208
|
-
adapter.markers?.hooksFile === undefined) {
|
|
290
|
+
if (blocked !== undefined && targetHasMarkers && adapter.markers?.hooksFile === undefined) {
|
|
209
291
|
say('');
|
|
210
292
|
say(color.yellow(`Note: Claude Code won't run the marker hooks in ${targetPath}: ${blocked}.`));
|
|
211
293
|
}
|
|
@@ -217,16 +299,33 @@ export const printMarkerCoexistenceNotes = async (adapter, targetPath, markersOn
|
|
|
217
299
|
for (const s of others) {
|
|
218
300
|
const hasInternal = cliRuns && runs(s) && s.groups.some((g) => g.ownership === 'internal');
|
|
219
301
|
const hasCli = s.groups.some((g) => g.ownership === 'cli');
|
|
220
|
-
const
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
if (hasCli && s.managed) {
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
302
|
+
const routes = scanRoutes(s).filter((k) => k !== BOOTSTRAP_KEY);
|
|
303
|
+
const leftOut = markersOn ? routes : [];
|
|
304
|
+
const stillRun = markersOn ? [] : routes;
|
|
305
|
+
if (hasCli && s.managed && routes.length === 0) {
|
|
306
|
+
}
|
|
307
|
+
else if (hasCli && s.managed) {
|
|
308
|
+
if (leftOut.length > 0) {
|
|
309
|
+
const leftMarkers = leftOut.some((k) => !isPlanSnapshotRoute(k));
|
|
310
|
+
const leftSnapshot = leftOut.some(isPlanSnapshotRoute);
|
|
311
|
+
const twice = [
|
|
312
|
+
...(leftMarkers ? ['marking each ticket and PR'] : []),
|
|
313
|
+
...(leftSnapshot ? ['sending the plan snapshot'] : []),
|
|
314
|
+
].join(' or ');
|
|
315
|
+
say('');
|
|
316
|
+
say(color.dim(`Note: your organization's managed settings (${s.path}) deliver ${leftOut.map(routeLabel).join(', ')},\n` +
|
|
317
|
+
`so setup left those out of your user settings to avoid ${twice} twice.`));
|
|
318
|
+
}
|
|
319
|
+
if (stillRun.length > 0) {
|
|
320
|
+
const markerRun = stillRun.some((k) => !isPlanSnapshotRoute(k));
|
|
321
|
+
const snapshotRun = stillRun.some(isPlanSnapshotRoute);
|
|
322
|
+
say('');
|
|
323
|
+
say(color.dim(`Note: your organization's managed settings (${s.path}) still run the ${markerRun
|
|
324
|
+
? snapshotRun
|
|
325
|
+
? 'marker hooks and the plan snapshot'
|
|
326
|
+
: 'marker hooks'
|
|
327
|
+
: 'plan snapshot'};\n--no-markers removes only the copy in your user settings.`));
|
|
328
|
+
}
|
|
230
329
|
}
|
|
231
330
|
else if (hasInternal) {
|
|
232
331
|
say('');
|
|
@@ -237,17 +336,28 @@ export const printMarkerCoexistenceNotes = async (adapter, targetPath, markersOn
|
|
|
237
336
|
}
|
|
238
337
|
else if (hasCli) {
|
|
239
338
|
say('');
|
|
240
|
-
say(color.dim(`Note: ${s.path} also carries CLI-managed
|
|
339
|
+
say(color.dim(`Note: ${s.path} also carries CLI-managed Mainwave hooks. Identical handlers run\n` +
|
|
241
340
|
'once, so counts stay correct; `mainwave-cli doctor` flags them if they drift.'));
|
|
242
341
|
}
|
|
243
342
|
}
|
|
244
343
|
};
|
|
245
344
|
export const printPostSetup = (plan) => {
|
|
246
|
-
if (plan.markersOn === true
|
|
345
|
+
if (plan.hookShellMissing && plan.markersOn === true) {
|
|
346
|
+
say('');
|
|
347
|
+
say(color.yellow(`No Mainwave hooks installed for ${plan.adapter.displayName}: ${GIT_BASH_MISSING_REASON}. ${GIT_BASH_FIX}`));
|
|
348
|
+
}
|
|
349
|
+
else if (plan.markersOn === true && plan.adapter.markers) {
|
|
247
350
|
say('');
|
|
248
351
|
say(color.dim(`Ticket & PR markers installed for ${plan.adapter.displayName}. ` +
|
|
249
352
|
`${plan.adapter.markers.disclosure}\n` +
|
|
250
|
-
`Remove them
|
|
353
|
+
`Remove them${plan.planSnapshotOn === true ? ' and the Claude plan snapshot' : ''} with ` +
|
|
354
|
+
`\`mainwave-cli setup ${plan.adapter.name} --no-markers\`, which installs no Mainwave hooks.`));
|
|
355
|
+
}
|
|
356
|
+
if (plan.hookEvents.includes('SessionStart')) {
|
|
357
|
+
say('');
|
|
358
|
+
say(color.dim(`${plan.adapter.displayName} also runs \`npx @mainwave/cli@latest install-hooks\` in the background when a session ` +
|
|
359
|
+
'starts, resumes or forks: it refreshes the hook scripts from the latest release and keeps the hooks above ' +
|
|
360
|
+
'current, on the same events only — a new kind of hook waits for your next setup run.'));
|
|
251
361
|
}
|
|
252
362
|
const snippet = plan.adapter.printPostSetupInstructions?.(plan.input, 'global');
|
|
253
363
|
if (snippet) {
|