@mainwave/cli 0.15.0 → 0.16.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 CHANGED
@@ -3,7 +3,7 @@
3
3
  Setup wizard that connects third-party coding tools to [Mainwave AI](https://mainwave.com), so their
4
4
  OpenTelemetry traces land in your dashboard, attributed to you.
5
5
 
6
- Installs as the `mainwave-cli` command. Requires Node 22.13 or newer.
6
+ Installs as the `mainwave-cli` command. Requires Node 22.22 or newer on 22.x, 24.15 or newer on 24.x, or Node 26 and later.
7
7
 
8
8
  ## Supported tools
9
9
 
@@ -539,6 +539,12 @@ preview lists every file the removal changes, and each one gets a backup beside
539
539
  marks each backup that still holds your API key. When no Codex setup is left, the removal also takes Mainwave's instructions out
540
540
  of `<codex home>/AGENTS.md`. Run it with the same `CODEX_HOME` you ran setup with.
541
541
 
542
+ A Codex app-server daemon that was already running keeps the settings it loaded when it started, and
543
+ new Codex sessions go through it. After an all-sessions setup or removal it keeps the old settings,
544
+ and after a removal it keeps sending telemetry to Mainwave, until it restarts. Both commands say so;
545
+ run `codex app-server daemon restart`. Profile sessions (`codex --profile`) run without the daemon
546
+ and don't need this.
547
+
542
548
  Plain `--remove` in a home whose only Mainwave setup is a profile's changes nothing, exits with
543
549
  code 1, and names the profile and the `--remove --profile <name>` command. A removal that leaves
544
550
  another setup in the home names that setup and the command that removes it. Running `--remove`
@@ -554,7 +560,8 @@ its own. A profile's report is titled `Codex CLI, profile <name>`, lists the pro
554
560
  authorization header, the metrics exporter and the hook approvals recorded in the profile file. It
555
561
  warns when a home holds Mainwave settings or hooks for all sessions and in a profile at once, and
556
562
  when more than one profile holds a Mainwave setup; `setup codex --profile` says so too when another
557
- profile already holds one. Codex merges `config.toml` under the profile file table by table, so in
563
+ profile already holds one. That warning and setup's both name `mainwave-cli setup codex --remove --profile <other>` as the way
564
+ to remove each other profile's setup. Codex merges `config.toml` under the profile file table by table, so in
558
565
  profile sessions any header or setting of another vendor's `[otel]` exporter in `config.toml` that
559
566
  the profile does not set is also sent to Mainwave's collector. Mainwave's key is not sent to the
560
567
  other collector. `setup codex --profile` and `doctor` both warn about that. Plain `setup codex`
@@ -674,8 +681,8 @@ written into any tool's settings file.
674
681
 
675
682
  ```bash
676
683
  mainwave-cli status [<adapter>] # on-disk config for every tool, or just one
677
- mainwave-cli doctor <adapter> # settings hierarchy + health checks
678
- mainwave-cli doctor <adapter> --validate # also auth-check against the collector
684
+ mainwave-cli doctor <adapter> # settings hierarchy + health checks; exits 1 if the collector rejects the key
685
+ mainwave-cli doctor <adapter> --validate # also exit 1 if the key cannot be checked or the collector cannot be reached
679
686
  mainwave-cli edit <adapter> # open the settings file in $EDITOR
680
687
  mainwave-cli edit <adapter> --global # the user-level file, without the picker (--local: this project's)
681
688
  mainwave-cli env <adapter> # print shell export lines
@@ -694,6 +701,13 @@ needs your email has none — Codex or Copilot, or Claude Code when it isn't sig
694
701
  account (an API key, Bedrock or Vertex, or no sign-in at all) — or `cursor-enterprise` has no team
695
702
  use-case id.
696
703
 
704
+ When the configuration is Mainwave's, plain `doctor` also checks the key with the collector
705
+ (`/v1/whoami`, waiting up to 3 seconds). It skips the check when there is no endpoint or key, or when a
706
+ repository chose the endpoint, it fails on a rejected key, and it only warns when the collector can't
707
+ be reached. When the configuration isn't Mainwave's exporter (another vendor's endpoint and key), plain
708
+ `doctor` skips the check without a message, and `doctor --validate` exits 1 and says "the config isn't
709
+ Mainwave's exporter". `--validate` also exits 1 when there is no endpoint or key to check.
710
+
697
711
  From Claude Code 2.1.282, project and local settings (`.claude/settings.json`,
698
712
  `.claude/settings.local.json`) can no longer turn telemetry on, choose where it goes, or choose what
699
713
  it captures: Claude Code ignores those keys there. `doctor`, `status` and `edit --local` say so, name
@@ -221,8 +221,7 @@ export const profileProcessNote = (profile) => `The profile applies to one Codex
221
221
  `typing the flag, for example \`alias codex-mw='codex --profile ${profile}'\`.`;
222
222
  const profileRuns = (profiles) => profiles.map((p) => `\`codex --profile ${p}\``).join(' or ');
223
223
  const profilesWithFiles = (home, profiles) => profiles.map((p) => `${p} (${profileFile(home, p)})`).join(', ');
224
- const PROFILE_REMOVAL = 'delete the file if it holds nothing else of yours, or remove its [otel.*] tables and the ' +
225
- '[[hooks.<Event>]] tables whose commands name mainwave-hook or install-hooks';
224
+ const removalCommands = (profiles) => profiles.map((p) => `\`mainwave-cli setup codex --remove --profile ${p}\``).join(' and ');
226
225
  export const otherProfileSetupsNote = (home, profile) => {
227
226
  const others = findCodexProfileSetups(home).filter((p) => p !== profile);
228
227
  if (others.length === 0)
@@ -231,15 +230,38 @@ export const otherProfileSetupsNote = (home, profile) => {
231
230
  return (`Codex ${one ? 'profile' : 'profiles'} ${profilesWithFiles(home, others)} already ` +
232
231
  `${one ? 'holds' : 'hold'} a Mainwave setup. This run sets up profile ${profilesWithFiles(home, [profile])} ` +
233
232
  `too and leaves ${others.join(', ')} as ${one ? 'it is' : 'they are'}, so sessions started with ` +
234
- `${profileRuns([...others, profile])} send to Mainwave. To keep only ${profile}, remove Mainwave ` +
235
- `from ${one ? `${others[0]}'s file` : 'the other files'}: ${PROFILE_REMOVAL}.`);
233
+ `${profileRuns([...others, profile])} send to Mainwave. To keep only ${profile}, run ` +
234
+ `${removalCommands(others)}.`);
236
235
  };
237
- const holdsMainwaveExporter = (env) => Object.keys(env).some((key) => {
236
+ const mainwaveExporterTables = (env) => Object.keys(env).flatMap((key) => {
238
237
  const m = /^(otel\..+)\.headers\.X-Mainwave-Source$/.exec(key);
239
- return (m !== null &&
240
- env[`${m[1]}.endpoint`] !== undefined &&
241
- env[`${m[1]}.headers.Authorization`] !== undefined);
238
+ return m !== null && env[key] === SOURCE_VALUE ? [m[1]] : [];
242
239
  });
240
+ const holdsMainwaveExporter = (env) => mainwaveExporterTables(env).length > 0;
241
+ const holdsMainwaveKey = (env) => mainwaveExporterTables(env).some((t) => (env[`${t}.headers.Authorization`] ?? '') !== '');
242
+ const missingExporterParts = (env) => {
243
+ const tables = mainwaveExporterTables(env);
244
+ const hasEndpoint = (t) => (env[`${t}.endpoint`] ?? '') !== '';
245
+ const hasAuth = (t) => (env[`${t}.headers.Authorization`] ?? '') !== '';
246
+ if (tables.length === 0 || tables.some((t) => hasEndpoint(t) && hasAuth(t)))
247
+ return [];
248
+ const missing = [
249
+ ...(tables.some(hasEndpoint) ? [] : ['endpoint']),
250
+ ...(tables.some(hasAuth) ? [] : ['Authorization header']),
251
+ ];
252
+ return missing.length > 0 ? missing : ['table with both an endpoint and an Authorization header'];
253
+ };
254
+ const brokenProfileIssues = (profile, path) => {
255
+ const env = readConfigEnv(path);
256
+ if (env === undefined)
257
+ return [];
258
+ return missingExporterParts(env).map((part) => ({
259
+ level: 'error',
260
+ message: `Mainwave's setup in ${path} has no ${part}, so sessions started with ` +
261
+ `\`codex --profile ${profile}\` send nothing to Mainwave. ` +
262
+ `Run \`mainwave-cli setup codex --profile ${profile}\` again to write it.`,
263
+ }));
264
+ };
243
265
  const EXPORTER_KEY = /^otel\.(?:exporter|trace_exporter|metrics_exporter)\./;
244
266
  const holdsOtherExporter = (env) => !holdsMainwaveExporter(env) && Object.keys(env).some((k) => EXPORTER_KEY.test(k));
245
267
  export const otherExporterNote = (config, profiles) => `${config} has telemetry settings for another collector. Codex applies config.toml under ` +
@@ -377,8 +399,9 @@ const codexDoctorSetups = (home) => {
377
399
  issues.push({
378
400
  level: 'warn',
379
401
  message: `Mainwave is set up in Codex profiles ${profilesWithFiles(home, profiles)}, so sessions started ` +
380
- `with ${profileRuns(profiles)} send to Mainwave. If you meant to keep one, remove Mainwave ` +
381
- `from the others' files: ${PROFILE_REMOVAL}.`,
402
+ `with ${profileRuns(profiles)} send to Mainwave. ` +
403
+ `To keep one, run \`mainwave-cli setup codex --remove --profile <name>\` for each of the ` +
404
+ `others: ${profiles.join(', ')}.`,
382
405
  });
383
406
  }
384
407
  const perProfileVersion = profiles.length > 1
@@ -517,7 +540,13 @@ const targetParts = (target) => {
517
540
  : []),
518
541
  ];
519
542
  },
520
- kindOnly: { doctorSetups: () => codexDoctorSetups(home) },
543
+ kindOnly: {
544
+ doctorSetups: () => codexDoctorSetups(home),
545
+ lingeringProcess: {
546
+ onSetup: 'Codex CLI: a running Codex app-server daemon keeps the settings it loaded when it started, and new sessions go through it. Run `codex app-server daemon restart` so they use the new settings.',
547
+ onRemove: 'Codex CLI: a running Codex app-server daemon keeps the old settings and keeps sending telemetry to Mainwave until it restarts, and new sessions go through it. Run `codex app-server daemon restart` to stop that.',
548
+ },
549
+ },
521
550
  };
522
551
  case 'profile': {
523
552
  const { profile } = target;
@@ -536,6 +565,7 @@ const targetParts = (target) => {
536
565
  hookArgs: ['--codex-profile', profile],
537
566
  collectChecks: (env) => [
538
567
  ...collectChecks(env),
568
+ ...brokenProfileIssues(profile, own),
539
569
  { level: 'info', message: profileProcessNote(profile) },
540
570
  ...profileVersionIssues([profile]),
541
571
  ],
@@ -630,6 +660,7 @@ export const codexCliFor = (target) => {
630
660
  collectFileChecks,
631
661
  normalizeForGenericChecks,
632
662
  holdsOwnSetup: holdsMainwaveExporter,
663
+ holdsOwnKey: holdsMainwaveKey,
633
664
  removal: { group: 'codex', plan: () => planCodexRemoval(target) },
634
665
  ...parts.kindOnly,
635
666
  markers: {
@@ -342,7 +342,7 @@ export const writePlan = async (plan, dirs = defaultHookDirs(), holdFlat = false
342
342
  }
343
343
  }
344
344
  };
345
- const setupCommand = (adapter) => ['mainwave-cli setup', adapter.name, ...(adapter.setupArgs ?? [])].join(' ');
345
+ export const setupCommand = (adapter) => ['mainwave-cli setup', adapter.name, ...(adapter.setupArgs ?? [])].join(' ');
346
346
  const partialWriteNote = (adapter, done) => {
347
347
  const lines = [
348
348
  '',
@@ -199,7 +199,41 @@ export const withoutHookStates = (toml, keys) => {
199
199
  if (toml.endsWith('\n') && kept.length > 0)
200
200
  kept.push('');
201
201
  }
202
- return { text: kept.join('\n'), dropped: dropped.size };
202
+ const lines = withoutEmptyHeader(withoutEmptyHeader(kept, ['hooks', 'state']), ['hooks']);
203
+ if (lines !== kept && toml.endsWith('\n') && lines[lines.length - 1] !== '') {
204
+ while (lines.length > 0 && lines[lines.length - 1].trim() === '')
205
+ lines.pop();
206
+ if (lines.length > 0)
207
+ lines.push('');
208
+ }
209
+ return { text: lines.join('\n'), dropped: dropped.size };
210
+ };
211
+ const withoutEmptyHeader = (lines, target) => {
212
+ const headerAt = lines.findIndex((l) => {
213
+ const t = l.trim();
214
+ return t.startsWith('[') && !t.startsWith('[[') && tablePath(t)?.join('.') === target.join('.');
215
+ });
216
+ if (headerAt < 0)
217
+ return lines;
218
+ let next = lines.findIndex((l, i) => i > headerAt && l.trim().startsWith('['));
219
+ if (next < 0)
220
+ next = lines.length;
221
+ const body = lines.slice(headerAt + 1, next);
222
+ if (body.some((l) => l.trim() !== '' && !l.trim().startsWith('#')))
223
+ return lines;
224
+ const implied = (l) => {
225
+ const t = l.trim();
226
+ if (!t.startsWith('['))
227
+ return false;
228
+ return new RegExp(String.raw `^\[\[?\s*${target.join(String.raw `\s*\.\s*`)}\s*[.\]]`).test(t);
229
+ };
230
+ if (lines.some((l, i) => i !== headerAt && implied(l)))
231
+ return lines;
232
+ const before = lines.slice(0, headerAt);
233
+ const lastBlank = before.length === 0 || before[before.length - 1].trim() === '';
234
+ const first = lastBlank ? body.findIndex((l) => l.trim() !== '') : 0;
235
+ const carried = next === lines.length || first < 0 ? [] : body.slice(first);
236
+ return [...before, ...carried, ...lines.slice(next)];
203
237
  };
204
238
  const mergedStates = (trustFiles) => {
205
239
  const merged = new Map();
@@ -5,13 +5,14 @@ import { envFileCodec } from './codecs/env-file.js';
5
5
  import { countTrust, readCodexTrust } from './codex-trust.js';
6
6
  import { activeHierarchy, computeEffective, effectiveFrom, flattenEffective, nativeIdentityReason, } from './effective-settings.js';
7
7
  import { ValidateError } from './errors.js';
8
+ import { HEADER_NAME, jsonObjectHeaders, kvPairsHeaders } from './headers.js';
8
9
  import { color, maskForDisplay } from './format.js';
9
10
  import { collectBehaviourHookIssues, scanBehaviourHooks } from './behaviour-hooks.js';
10
11
  import { isManagedIdentityConfig, isManagedLayer, policyState } from './layer-policy.js';
11
12
  import { collectMarkerIssues, DEFAULT_MARKER_TOOL, managedHooksDir, matchersForTool, readPackagedMatchers, scanForMarkers, } from './markers.js';
12
13
  import { flatCopyIssues } from './hook-copies.js';
13
14
  import { readExistingEnv } from './settings.js';
14
- import { hookShellMissingFor, teamUcidStanding } from './apply.js';
15
+ import { hookShellMissingFor, setupCommand, teamUcidStanding } from './apply.js';
15
16
  import { adapterEffective, primaryCarries } from './status.js';
16
17
  import { hasRulesFile, redactionLines, redactionView, sendsUnredactedContent, uncoveredNotice, } from './redaction.js';
17
18
  import { readSettings } from './store.js';
@@ -617,7 +618,28 @@ const skippedMarkerScans = async (effective) => {
617
618
  }
618
619
  return out;
619
620
  };
620
- const runValidate = async (effective, adapter) => {
621
+ const unchecked = (message, probe = 'skipped') => ({
622
+ ok: false,
623
+ message,
624
+ outcome: 'unchecked',
625
+ probe,
626
+ });
627
+ const PLAIN_PROBE_TIMEOUT_MS = 3_000;
628
+ const VALIDATE_PROBE_TIMEOUT_MS = 10_000;
629
+ const keySource = (effective, adapter, apiKey) => Object.values(effective.effective).find((e) => adapter.parseEnv({ [e.key]: e.value }).apiKey === apiKey);
630
+ export const holdsMainwaveConfig = (adapter, env) => {
631
+ const own = adapter.holdsOwnSetup?.(env);
632
+ if (own !== undefined)
633
+ return own;
634
+ const sourceName = HEADER_NAME.source.toLowerCase();
635
+ const headerSets = [
636
+ kvPairsHeaders.decode(env.OTEL_EXPORTER_OTLP_HEADERS ?? ''),
637
+ jsonObjectHeaders.decode(env.otlpHeaders ?? ''),
638
+ ];
639
+ return (headerSets.some((headers) => Object.keys(headers ?? {}).some((name) => name.toLowerCase() === sourceName)) || /(^|,)\s*mainwave\.source=/.test(env.OTEL_RESOURCE_ATTRIBUTES ?? ''));
640
+ };
641
+ const runValidate = async (effective, adapter, options) => {
642
+ const asked = options.validate === true;
621
643
  const fromRepo = (scan) => !isAbsolute(scan.layer.path) || adapter.layerKeyPolicy?.layers.includes(scan.layer.id) === true;
622
644
  const withoutRepo = effectiveFrom(adapter, effective.scans.filter((s) => !fromRepo(s)), effective.policy);
623
645
  const endpoint = adapter.parseEnv(flattenEffective(effective)).collectorUrl;
@@ -625,27 +647,57 @@ const runValidate = async (effective, adapter) => {
625
647
  endpoint !== adapter.parseEnv(flattenEffective(withoutRepo)).collectorUrl) {
626
648
  const repoScan = effective.scans.find((s) => fromRepo(s) && Object.keys(s.env).length > 0);
627
649
  return {
628
- ok: false,
629
- message: `not validating: the collector endpoint comes from ${repoScan?.layer.label ?? 'project settings'}` +
630
- `${repoScan ? ` (${repoScan.path})` : ''}, and the CLI won't send your key to a destination a repository chose`,
650
+ ...unchecked(`not validating: the collector endpoint comes from ${repoScan?.layer.label ?? 'project settings'}` +
651
+ `${repoScan ? ` (${repoScan.path})` : ''}, and the CLI won't send your key to a destination a repository chose`),
652
+ quiet: !asked,
631
653
  };
632
654
  }
633
- const parsed = adapter.parseEnv(flattenEffective(effective));
655
+ const flat = flattenEffective(effective);
656
+ if (!holdsMainwaveConfig(adapter, flat)) {
657
+ return {
658
+ ...unchecked("key check skipped: the config isn't Mainwave's exporter"),
659
+ quiet: !asked,
660
+ };
661
+ }
662
+ const parsed = adapter.parseEnv(flat);
634
663
  if (!parsed.collectorUrl) {
635
- return { ok: false, message: 'no OTEL_EXPORTER_OTLP_ENDPOINT to validate against' };
664
+ return {
665
+ ...unchecked('no OTEL_EXPORTER_OTLP_ENDPOINT to validate against'),
666
+ quiet: !asked,
667
+ };
636
668
  }
637
669
  if (!parsed.apiKey) {
638
- return { ok: false, message: 'no Bearer token in OTEL_EXPORTER_OTLP_HEADERS' };
639
- }
640
- try {
641
- await validateCollector(parsed.collectorUrl, parsed.apiKey);
642
- return { ok: true, message: 'authenticated' };
643
- }
644
- catch (err) {
645
- if (err instanceof ValidateError)
646
- return { ok: false, message: err.message };
647
- throw err;
648
- }
670
+ return { ...unchecked('no Bearer token in OTEL_EXPORTER_OTLP_HEADERS'), quiet: !asked };
671
+ }
672
+ const apiKey = parsed.apiKey;
673
+ const probeKey = `${parsed.collectorUrl}\n${apiKey}`;
674
+ let probe = options.probes.get(probeKey);
675
+ if (probe === undefined) {
676
+ probe = validateCollector(parsed.collectorUrl, apiKey, {
677
+ timeoutMs: asked ? VALIDATE_PROBE_TIMEOUT_MS : PLAIN_PROBE_TIMEOUT_MS,
678
+ }).then(() => undefined, (err) => {
679
+ if (!(err instanceof ValidateError))
680
+ throw err;
681
+ return err;
682
+ });
683
+ options.probes.set(probeKey, probe);
684
+ }
685
+ const err = await probe;
686
+ if (err === undefined)
687
+ return { ok: true, message: 'authenticated', outcome: 'ok', probe: 'ok' };
688
+ if (err.reason !== 'unauthorized')
689
+ return unchecked(err.message, err.reason);
690
+ const source = keySource(effective, adapter, apiKey);
691
+ const where = source ? ` in ${source.source.path}` : '';
692
+ return {
693
+ ok: false,
694
+ outcome: 'rejected',
695
+ probe: 'rejected',
696
+ message: `the collector rejects the Mainwave key${where} (HTTP ${err.status}). ` +
697
+ (source !== undefined && isManagedLayer(source.source.layer)
698
+ ? "Your organization's managed settings supply the key. Ask your admin to update it."
699
+ : `Rerun \`${setupCommand(adapter)}\` with a valid key.`),
700
+ };
649
701
  };
650
702
  const doctorJson = async (adapter, effective, issues, validation, redaction) => ({
651
703
  adapter: adapter.name,
@@ -665,19 +717,24 @@ const doctorJson = async (adapter, effective, issues, validation, redaction) =>
665
717
  })),
666
718
  redaction,
667
719
  issues: issues.map((issue) => ({ level: issue.level, message: issue.message })),
668
- validation,
720
+ validation: validation && {
721
+ ok: validation.ok,
722
+ message: validation.message,
723
+ outcome: validation.probe,
724
+ },
669
725
  });
670
726
  export const runDoctor = async (adapter, options = {}) => {
727
+ const run = { ...options, probes: new Map() };
671
728
  const many = adapter.doctorSetups?.();
672
729
  if (many === undefined) {
673
- return options.json ? runDoctorJson(adapter, options) : reportSetup(adapter, options);
730
+ return options.json ? runDoctorJson(adapter, run) : reportSetup(adapter, run);
674
731
  }
675
732
  const together = many.issues.some((i) => i.level === 'error') ? 1 : 0;
676
733
  if (options.json) {
677
734
  const setups = [];
678
735
  let code = together;
679
736
  for (const { label, adapter: setup } of many.setups) {
680
- const { doc, failed } = await setupJson(setup, options);
737
+ const { doc, failed } = await setupJson(setup, run);
681
738
  setups.push({ setup: label, ...doc });
682
739
  if (failed)
683
740
  code = 1;
@@ -696,7 +753,7 @@ export const runDoctor = async (adapter, options = {}) => {
696
753
  if (i > 0)
697
754
  console.log();
698
755
  const title = `${adapter.displayName}, ${label}`;
699
- if ((await reportSetup(setup, options, title, once?.replaces)) !== 0)
756
+ if ((await reportSetup(setup, run, title, once?.replaces)) !== 0)
700
757
  code = 1;
701
758
  }
702
759
  const togetherIssues = [...many.issues, ...(once?.issues ?? [])];
@@ -734,17 +791,20 @@ const reportSetup = async (adapter, options, title = adapter.displayName, omit =
734
791
  : [];
735
792
  renderChecks([...issues, ...shellEnvIssues, ...markerIssues, ...behaviourHookIssues].filter((i) => !omit(i)));
736
793
  let validateFailed = false;
737
- if (options.validate) {
794
+ const result = await runValidate(effective, adapter, options);
795
+ if (!result.quiet) {
738
796
  console.log();
739
797
  console.log(color.bold('Auth check:'));
740
- const result = await runValidate(effective, adapter);
741
798
  if (result.ok) {
742
799
  console.log(color.green(` ✓ ${result.message}`));
743
800
  }
744
- else {
801
+ else if (result.outcome === 'rejected' || options.validate) {
745
802
  console.log(color.red(` ✗ ${result.message}`));
746
803
  validateFailed = true;
747
804
  }
805
+ else {
806
+ console.log(color.yellow(` ! could not check the key: ${result.message}`));
807
+ }
748
808
  }
749
809
  const hasError = [...issues, ...shellEnvIssues, ...markerIssues, ...behaviourHookIssues].some((i) => i.level === 'error');
750
810
  return hasError || validateFailed ? 1 : 0;
@@ -766,9 +826,11 @@ const setupJson = async (adapter, options) => {
766
826
  ? await collectBehaviourHookIssues(adapter.behaviourHooks, VERSION)
767
827
  : []),
768
828
  ];
769
- const validation = options.validate ? await runValidate(effective, adapter) : undefined;
829
+ const validation = await runValidate(effective, adapter, options);
770
830
  return {
771
- doc: await doctorJson(adapter, effective, issues, validation, redaction),
772
- failed: issues.some((i) => i.level === 'error') || validation?.ok === false,
831
+ doc: await doctorJson(adapter, effective, issues, validation.quiet ? undefined : validation, redaction),
832
+ failed: issues.some((i) => i.level === 'error') ||
833
+ validation.outcome === 'rejected' ||
834
+ (options.validate === true && !validation.ok),
773
835
  };
774
836
  };
@@ -78,6 +78,9 @@ export const runRemove = async (adapters, options = {}) => {
78
78
  }
79
79
  }
80
80
  say(color.dim('Restart open sessions of these tools so they stop loading the hooks.'));
81
+ for (const a of adapters)
82
+ if (a.lingeringProcess)
83
+ say(color.yellow(a.lingeringProcess.onRemove));
81
84
  const problem = await forgetHookRecords(adapters);
82
85
  if (options.json) {
83
86
  emitJson({
@@ -13,7 +13,7 @@ export const planSetupRemoval = async (adapter, options = {}) => {
13
13
  managedKeys: owns ? [...adapter.managedEnvKeys, ...(adapter.retiredEnvKeys ?? [])] : [],
14
14
  codec: adapter.codec,
15
15
  });
16
- const holdsKey = (fileEnv) => fileEnv !== null && adapter.holdsOwnSetup?.(fileEnv) === true;
16
+ const holdsKey = (fileEnv) => fileEnv !== null && (adapter.holdsOwnKey ?? adapter.holdsOwnSetup)?.(fileEnv) === true;
17
17
  const configKey = holdsKey(env);
18
18
  const hooksFile = adapter.markers?.hooksFile;
19
19
  const approvals = options.approvals === true;
@@ -681,6 +681,9 @@ const printRestartNotice = (adapters) => {
681
681
  ' already open keeps the old settings and sends nothing. Quit and reopen each\n' +
682
682
  ' one (including this one, if you ran setup from inside it) before checking\n' +
683
683
  ' for telemetry.'));
684
+ for (const a of adapters)
685
+ if (a.lingeringProcess)
686
+ say(color.yellow(` ${a.lingeringProcess.onSetup}`));
684
687
  };
685
688
  const printPostSetupTips = (adapters) => {
686
689
  const killSwitch = process.env.DISABLE_TELEMETRY === '1'
@@ -33,7 +33,10 @@
33
33
  // length, the date of the account's first Claude Code token, and when
34
34
  // Claude Code fetched the profile;
35
35
  // - from the usage cache, only when it names the same account: the 5-hour and
36
- // 7-day utilization and their reset times; per rate limit, its group,
36
+ // 7-day utilization and their reset times, and the same two figures for each
37
+ // other rolling window Claude Code reports under a key named `five_hour` or
38
+ // `seven_day` plus a suffix (`seven_day_opus`, ...) whose value is an object
39
+ // (a null one is skipped; no other key is read as a window); per rate limit, its group,
37
40
  // percent used, severity, whether it is the active one and its reset time,
38
41
  // and for a scoped limit (one per model) the scope's model id, model name or
39
42
  // surface;
@@ -114,7 +117,9 @@ import {
114
117
  VENDOR_ANTHROPIC,
115
118
  SUBSCRIPTION_LIMIT_FIELDS,
116
119
  SUBSCRIPTION_LIMIT_SCOPED_FIELDS,
120
+ SUBSCRIPTION_USAGE_WINDOW_FIELDS,
117
121
  subscriptionLimitKey,
122
+ subscriptionUsageKey,
118
123
  } from './vocabulary.mjs'
119
124
 
120
125
  const LOG_NAME = 'plan-snapshot.log'
@@ -148,6 +153,13 @@ export const EXIT_GRACE_MS = 250
148
153
  /** At most this many rate-limit entries become keys (the record held 3). */
149
154
  export const MAX_LIMITS = 16
150
155
 
156
+ /** At most this many extra usage windows become keys. */
157
+ export const MAX_USAGE_WINDOWS = 16
158
+
159
+ /** A key of the usage object that names a rolling window beyond the literal
160
+ * five_hour / seven_day pair: those two names plus a `_suffix`. */
161
+ const USAGE_WINDOW_RE = /^(five_hour|seven_day)(_[a-z0-9_]+)?$/
162
+
151
163
  const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v)
152
164
 
153
165
  /** A non-empty string exactly as stored, else undefined. Strings from the
@@ -251,6 +263,36 @@ export const limitAttributes = (limits) => {
251
263
  })
252
264
  }
253
265
 
266
+ /**
267
+ * The typed attributes for the rolling windows of `utilization` other than
268
+ * `five_hour` / `seven_day` (which have literal keys): every key matching
269
+ * `^(five_hour|seven_day)(_[a-z0-9_]+)?$` whose value is a plain object (null
270
+ * and other types are skipped), in sorted key order, at most
271
+ * § `MAX_USAGE_WINDOWS`. Each becomes `usage.<window>.utilization` (double)
272
+ * and `usage.<window>.resets_at` (raw string), each only when usable.
273
+ */
274
+ export const usageWindowAttributes = (usage) => {
275
+ if (!isPlainObject(usage)) return []
276
+ return Object.keys(usage)
277
+ .filter(
278
+ (k) =>
279
+ USAGE_WINDOW_RE.test(k) &&
280
+ k !== 'five_hour' &&
281
+ k !== 'seven_day' &&
282
+ isPlainObject(usage[k]),
283
+ )
284
+ .sort()
285
+ .slice(0, MAX_USAGE_WINDOWS)
286
+ .flatMap((name) => {
287
+ const w = usage[name]
288
+ return SUBSCRIPTION_USAGE_WINDOW_FIELDS.flatMap((field) =>
289
+ field === 'utilization'
290
+ ? typed(doubleAttr, [[subscriptionUsageKey(name, field), finite(w.utilization)]])
291
+ : typed(stringAttr, [[subscriptionUsageKey(name, field), rawString(w.resets_at)]]),
292
+ )
293
+ })
294
+ }
295
+
254
296
  /**
255
297
  * The snapshot in one parsed `.claude.json` document, or `undefined` when it
256
298
  * has no usable `oauthAccount.accountUuid` (no account, nothing to attribute).
@@ -266,7 +308,8 @@ export const limitAttributes = (limits) => {
266
308
  * first-token date — the record's top-level `claudeCodeFirstTokenDate`;
267
309
  * - `extra_usage.enabled`: the usage cache's `is_enabled`, else the account's
268
310
  * `hasExtraUsageEnabled`;
269
- * - everything else — 5-hour / 7-day utilization and resets, per-kind rate
311
+ * - everything else — 5-hour / 7-day utilization and resets, the other rolling
312
+ * windows (§ `usageWindowAttributes`, after the 7-day pair), per-kind rate
270
313
  * limits, the extra-usage figures and flags, the top-level
271
314
  * `cachedExtraUsageDisabledReason`, and `observed_at` (`fetchedAtMs`) —
272
315
  * only when `cachedUsageUtilization` names the same `accountUuid`: another
@@ -328,6 +371,7 @@ export const snapshotFromRecord = (doc) => {
328
371
  ...typed(stringAttr, [
329
372
  [ATTR_USAGE_SEVEN_DAY_RESETS_AT, rawString(window('seven_day').resets_at)],
330
373
  ]),
374
+ ...usageWindowAttributes(usage),
331
375
  ...limitAttributes(usage.limits),
332
376
  ...typed(intAttr, [
333
377
  [ATTR_EXTRA_USAGE_USED_MINOR, count(extra?.used_credits)],
@@ -93,6 +93,9 @@ export const ATTR_ORGANIZATION_ID: string
93
93
  export const SUBSCRIPTION_LIMIT_FIELDS: readonly string[]
94
94
  export const SUBSCRIPTION_LIMIT_SCOPED_FIELDS: readonly string[]
95
95
  export const subscriptionLimitKey: (kind: string, field: string, scope?: string) => string
96
+ export const SUBSCRIPTION_USAGE_PREFIX: string
97
+ export const SUBSCRIPTION_USAGE_WINDOW_FIELDS: readonly string[]
98
+ export const subscriptionUsageKey: (window: string, field: string) => string
96
99
  export const SUBSCRIPTION_SNAPSHOT_KEYS: readonly string[]
97
100
 
98
101
  export const CLAUDE_CODE_STOP_FAILURE: string
@@ -253,6 +253,14 @@ export const ATTR_USAGE_FIVE_HOUR_UTILIZATION = 'mainwave.subscription.usage.fiv
253
253
  export const ATTR_USAGE_FIVE_HOUR_RESETS_AT = 'mainwave.subscription.usage.five_hour.resets_at'
254
254
  export const ATTR_USAGE_SEVEN_DAY_UTILIZATION = 'mainwave.subscription.usage.seven_day.utilization'
255
255
  export const ATTR_USAGE_SEVEN_DAY_RESETS_AT = 'mainwave.subscription.usage.seven_day.resets_at'
256
+ // Further rolling windows the usage cache reports (`seven_day_opus`, ...) go
257
+ // under the generic shape `usage.<window>.<field>`; `five_hour` and `seven_day`
258
+ // stay the literals above and are never sent twice.
259
+ export const SUBSCRIPTION_USAGE_PREFIX = 'mainwave.subscription.usage.'
260
+ export const SUBSCRIPTION_USAGE_WINDOW_FIELDS = ['utilization', 'resets_at']
261
+ /** `mainwave.subscription.usage.<window>.<field>`. */
262
+ export const subscriptionUsageKey = (window, field) =>
263
+ `${SUBSCRIPTION_USAGE_PREFIX}${window}.${field}`
256
264
  export const ATTR_EXTRA_USAGE_ENABLED = 'mainwave.subscription.extra_usage.enabled'
257
265
  export const ATTR_EXTRA_USAGE_USED_MINOR = 'mainwave.subscription.extra_usage.used_minor'
258
266
  export const ATTR_EXTRA_USAGE_LIMIT_MINOR = 'mainwave.subscription.extra_usage.limit_minor'
@@ -389,8 +397,8 @@ export const CODEX_TURN_KEYS = [
389
397
  // The dispatcher drops every span attribute a feature's entry here doesn't
390
398
  // bind, and every span whose name isn't the feature's, before anything is
391
399
  // posted: a key added to a feature without a registered name here never
392
- // leaves the machine. `prefixes` covers the snapshot's per-kind limit keys,
393
- // a registered pattern. Every feature may also send the identity pair, the
400
+ // leaves the machine. `prefixes` covers the snapshot's per-kind limit keys and
401
+ // extra usage-window keys, registered patterns. Every feature may also send the identity pair, the
394
402
  // session id and the calling-span keys (§ COMMON_SPAN_KEYS).
395
403
  export const COMMON_SPAN_KEYS = Object.freeze([
396
404
  'session.id',
@@ -403,7 +411,7 @@ export const FEATURE_EMITS = Object.freeze({
403
411
  'plan-snapshot': {
404
412
  spans: [SUBSCRIPTION_SNAPSHOT],
405
413
  keys: SUBSCRIPTION_SNAPSHOT_KEYS,
406
- prefixes: [SUBSCRIPTION_LIMIT_PREFIX],
414
+ prefixes: [SUBSCRIPTION_LIMIT_PREFIX, SUBSCRIPTION_USAGE_PREFIX],
407
415
  },
408
416
  'github-pr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
409
417
  'glab-mr-marker': { spans: [VCS_OPENED], keys: VCS_MARKER_KEYS, prefixes: [] },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mainwave/cli",
3
- "version": "0.15.0",
3
+ "version": "0.16.0",
4
4
  "description": "Setup wizard for connecting third-party coding tools to Mainwave AI.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -18,7 +18,7 @@
18
18
  "provenance": false
19
19
  },
20
20
  "engines": {
21
- "node": "^22.13.0 || >=23.5.0",
21
+ "node": "^22.22.2 || ^24.15.0 || >=26.0.0",
22
22
  "pnpm": ">=10.0.0"
23
23
  },
24
24
  "packageManager": "pnpm@10.0.0",
@@ -45,18 +45,18 @@
45
45
  "api:generate": "openapi-ts"
46
46
  },
47
47
  "dependencies": {
48
- "@inquirer/prompts": "8.7.5",
48
+ "@inquirer/prompts": "8.8.0",
49
49
  "picocolors": "1.1.1"
50
50
  },
51
51
  "devDependencies": {
52
52
  "@hey-api/openapi-ts": "^0.99.0",
53
53
  "@types/node": "22.20.5",
54
- "knip": "6.45.0",
54
+ "knip": "6.45.1",
55
55
  "lefthook": "2.2.2",
56
56
  "oxlint": "1.93.0",
57
- "prettier": "3.9.10",
57
+ "prettier": "3.10.1",
58
58
  "typescript": "6.0.3",
59
- "vite": "8.3.7",
59
+ "vite": "8.3.8",
60
60
  "vitest": "5.1.0",
61
61
  "yaml": "2.9.1"
62
62
  },