@mainwave/cli 0.11.0 → 0.12.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.
Files changed (39) hide show
  1. package/README.md +168 -13
  2. package/dist/adapters/claude-code.js +3 -3
  3. package/dist/adapters/claude-desktop.js +35 -1
  4. package/dist/adapters/cursor.js +7 -2
  5. package/dist/adapters/kiro.js +13 -8
  6. package/dist/commands.js +217 -0
  7. package/dist/core/apply.js +3 -3
  8. package/dist/core/auth-commands.js +2 -1
  9. package/dist/core/codecs/kiro-hooks-json.js +1 -1
  10. package/dist/core/doctor.js +71 -8
  11. package/dist/core/entry-script.js +2 -3
  12. package/dist/core/format.js +0 -1
  13. package/dist/core/hook-copies.js +157 -0
  14. package/dist/core/install-hooks.js +144 -15
  15. package/dist/core/interview.js +8 -2
  16. package/dist/core/markers.js +86 -22
  17. package/dist/core/redaction.js +179 -0
  18. package/dist/core/skills.js +3 -11
  19. package/dist/core/status.js +21 -1
  20. package/dist/core/store.js +254 -4
  21. package/dist/core/wizard.js +91 -6
  22. package/dist/main.js +163 -162
  23. package/hooks/kiro-otlp.mjs +10 -1
  24. package/hooks/mainwave-hook.mjs +11 -1
  25. package/hooks/marker-core.mjs +56 -2
  26. package/hooks/matchers.json +1 -1
  27. package/hooks/redaction-data.mjs +201 -0
  28. package/hooks/redaction-json.mjs +215 -0
  29. package/hooks/redaction-pattern.mjs +503 -0
  30. package/hooks/redaction.d.mts +84 -0
  31. package/hooks/redaction.mjs +701 -0
  32. package/package.json +3 -1
  33. package/skills/mainwave-instrument/SKILL.md +24 -6
  34. package/skills/mainwave-instrument/reference/frameworks.md +4 -2
  35. package/skills/mainwave-instrument/reference/troubleshooting.md +4 -0
  36. package/skills/mainwave-instrument-node/SKILL.md +83 -38
  37. package/skills/mainwave-instrument-node/reference/api.md +16 -16
  38. package/skills/mainwave-instrument-node/reference/frameworks.md +42 -27
  39. package/skills/mainwave-instrument-node/reference/troubleshooting.md +11 -7
@@ -0,0 +1,701 @@
1
+ // Redaction of hook telemetry before it leaves the machine: the same rules
2
+ // file format, packs and semantics as the Mainwave SDKs' redaction, so one
3
+ // rules file means the same thing in an application and in a coding tool's
4
+ // hooks.
5
+ //
6
+ // The rules object: `packs` (built-in rule packs, off unless listed),
7
+ // `blocked_values` (every match replaced by `[REDACTED:<name>]`, or
8
+ // `[REDACTED]` when the rule has no name), `allowed_values` (a blocked or pack
9
+ // match one of these matches in full is kept), `blocked_key_patterns` (searched
10
+ // in the attribute key; a hit replaces the whole value), `ignored_keys` and
11
+ // `ignored_key_patterns` (never scanned), and `summary` (`info`, the default,
12
+ // stamps `mainwave.redaction.count` on each span that had a replacement;
13
+ // `silent` does not). A rule is a pattern string or `{ name, pattern,
14
+ // case_insensitive }`. Patterns are checked against a fixed grammar and cost
15
+ // limits at load (redaction-pattern.mjs); anything else is a config error
16
+ // naming the rule, pack or key, and a hook never runs on rules it could not
17
+ // load (`loadHookRedaction` reports `error`, and the caller drops the span).
18
+ //
19
+ // What is scanned, per span: its name, its status message, and every string
20
+ // attribute value (and string element of an array value) in its own, its
21
+ // events', its links' and its resource's attributes. Event names, numbers and
22
+ // booleans, and non-string array elements are not. A shape the walk cannot
23
+ // scan (a `kvlistValue`, a `bytesValue`, an array nested in an array, scope
24
+ // attributes) is never passed through: `redactOtlpTraces` throws, so the
25
+ // caller drops the span rather than send what was not checked. A value that is strict JSON
26
+ // is redacted in place (redaction-json.mjs): only its string and number value
27
+ // tokens are scanned, and only a changed token is rewritten. Per attribute:
28
+ // an exempt or ignored key skips everything; then key rules; then value rules,
29
+ // packs first in their fixed order, then `blocked_values`. The span name and
30
+ // status message have no key, so only value rules apply to them.
31
+
32
+ import { readFileSync } from 'node:fs'
33
+ import { homedir } from 'node:os'
34
+ import { isAbsolute, join, resolve } from 'node:path'
35
+
36
+ import { BUILTIN_EXEMPT_KEYS, PACKS } from './redaction-data.mjs'
37
+ import { decodeJsonString, encodeJsonString, tokenizeJson } from './redaction-json.mjs'
38
+ import { PatternError, translatePattern } from './redaction-pattern.mjs'
39
+
40
+ /** A rules object or rules file that cannot be used. The message names the
41
+ * offending rule (its name, else its pattern), pack or top-level key; from
42
+ * `readRedactionFile`, the file too. */
43
+ export class RedactionConfigError extends Error {
44
+ name = 'RedactionConfigError'
45
+ }
46
+
47
+ /** The span attribute that carries the replacement count. */
48
+ export const REDACTION_COUNT_KEY = 'mainwave.redaction.count'
49
+
50
+ /**
51
+ * Present in a `redaction.mjs` that reads the organization's packs from
52
+ * `redaction.org`. `install-hooks`, `status` and `doctor` look for it in the
53
+ * text of a copy already on the machine to tell one from before the packs; it
54
+ * appears nowhere else in this file, so a comment cannot stand in for it.
55
+ */
56
+ export const ORG_PACKS_SUPPORT = 'mainwave:org-redaction-packs/1'
57
+
58
+ /** The built-in pack names, in the order they run. */
59
+ export const REDACTION_PACKS = Object.freeze(Object.keys(PACKS))
60
+
61
+ const TOP_LEVEL_KEYS = [
62
+ 'packs',
63
+ 'blocked_values',
64
+ 'allowed_values',
65
+ 'blocked_key_patterns',
66
+ 'ignored_keys',
67
+ 'ignored_key_patterns',
68
+ 'summary',
69
+ ]
70
+ const RULE_KEYS = new Set(['name', 'pattern', 'case_insensitive'])
71
+
72
+ const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
73
+
74
+ const ruleError = (list, label, reason) =>
75
+ new RedactionConfigError(`redaction: ${list} rule ${JSON.stringify(label)}: ${reason}`)
76
+
77
+ /** The Luhn checksum of the digits in `text`: from the rightmost digit, double
78
+ * every second digit (subtracting 9 above 9) and sum; divisible by 10 passes. */
79
+ const luhnValid = (text) => {
80
+ let sum = 0
81
+ let double = false
82
+ for (let i = text.length - 1; i >= 0; i--) {
83
+ const c = text.charCodeAt(i)
84
+ if (c < 0x30 || c > 0x39) continue
85
+ let digit = c - 0x30
86
+ if (double) {
87
+ digit *= 2
88
+ if (digit > 9) digit -= 9
89
+ }
90
+ sum += digit
91
+ double = !double
92
+ }
93
+ return sum % 10 === 0
94
+ }
95
+
96
+ // ─── Load: check and compile ─────────────────────────────────────────────
97
+
98
+ /** One compiled rule: its replacement token, a global regex (every match), a
99
+ * plain one (key search), an anchored one (`allowed_values`, whole match) and
100
+ * a pack rule's post-match check. */
101
+ const buildRule = (list, index, { name, pattern, caseInsensitive, validate }) => {
102
+ if (typeof pattern !== 'string' || pattern === '') {
103
+ throw ruleError(list, name ?? `#${index}`, 'pattern must be a non-empty string')
104
+ }
105
+ const label = name ?? pattern
106
+ let source
107
+ try {
108
+ source = translatePattern(pattern, caseInsensitive)
109
+ } catch (error) {
110
+ if (error instanceof PatternError) throw ruleError(list, label, error.message)
111
+ // A pattern nested deeper than the parser's stack.
112
+ throw ruleError(list, label, 'the pattern is too complex to check')
113
+ }
114
+ try {
115
+ return {
116
+ token: name === undefined ? '[REDACTED]' : `[REDACTED:${name}]`,
117
+ global: new RegExp(source, 'gu'),
118
+ search: new RegExp(source, 'u'),
119
+ full: new RegExp(`^(?:${source})(?![^])`, 'u'),
120
+ validate,
121
+ }
122
+ } catch (error) {
123
+ throw ruleError(list, label, `does not compile: ${error?.message ?? String(error)}`)
124
+ }
125
+ }
126
+
127
+ /** A user rule: a pattern string or `{ name, pattern, case_insensitive }`.
128
+ * `validate` is for pack rules only, so here it is an unknown key. */
129
+ const compileRule = (list, input, index) => {
130
+ if (typeof input === 'string') {
131
+ return buildRule(list, index, { name: undefined, pattern: input, caseInsensitive: false })
132
+ }
133
+ if (!isRecord(input))
134
+ throw ruleError(list, `#${index}`, 'a rule is a pattern string or an object')
135
+ const label =
136
+ typeof input.name === 'string' && input.name !== ''
137
+ ? input.name
138
+ : typeof input.pattern === 'string'
139
+ ? input.pattern
140
+ : `#${index}`
141
+ for (const key of Object.keys(input)) {
142
+ if (!RULE_KEYS.has(key)) throw ruleError(list, label, `unknown key ${JSON.stringify(key)}`)
143
+ }
144
+ if (input.name !== undefined && (typeof input.name !== 'string' || input.name === '')) {
145
+ throw ruleError(list, label, 'name must be a non-empty string')
146
+ }
147
+ if (input.case_insensitive !== undefined && typeof input.case_insensitive !== 'boolean') {
148
+ throw ruleError(list, label, 'case_insensitive must be a boolean')
149
+ }
150
+ return buildRule(list, index, {
151
+ name: input.name,
152
+ pattern: input.pattern,
153
+ caseInsensitive: input.case_insensitive === true,
154
+ })
155
+ }
156
+
157
+ const compileRules = (rules, list) => {
158
+ const value = rules[list]
159
+ if (value === undefined) return []
160
+ if (!Array.isArray(value)) throw new RedactionConfigError(`redaction: ${list} must be a list`)
161
+ return value.map((entry, index) => compileRule(list, entry, index))
162
+ }
163
+
164
+ const stringList = (rules, key) => {
165
+ const value = rules[key]
166
+ if (value === undefined) return []
167
+ if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || entry === '')) {
168
+ throw new RedactionConfigError(`redaction: ${key} must be a list of non-empty strings`)
169
+ }
170
+ return value
171
+ }
172
+
173
+ /** The packs `packs` turns on, in canonical order (the packs file's, whatever
174
+ * order the rules list them in: a card rule must not read the digits inside
175
+ * a token the secrets pack replaces), and their compiled rules. */
176
+ const compilePacks = (rules) => {
177
+ const value = rules.packs
178
+ if (value === undefined) return { names: [], rules: [] }
179
+ if (!Array.isArray(value)) throw new RedactionConfigError('redaction: packs must be a list')
180
+ const listed = new Set()
181
+ for (const entry of value) {
182
+ if (typeof entry !== 'string') {
183
+ throw new RedactionConfigError('redaction: packs must be a list of pack names (strings)')
184
+ }
185
+ if (!Object.hasOwn(PACKS, entry)) {
186
+ throw new RedactionConfigError(
187
+ `redaction: packs: unknown pack ${JSON.stringify(entry)} (known: ${REDACTION_PACKS.join(', ')})`,
188
+ )
189
+ }
190
+ if (listed.has(entry)) {
191
+ throw new RedactionConfigError(
192
+ `redaction: packs: pack ${JSON.stringify(entry)} is listed twice`,
193
+ )
194
+ }
195
+ listed.add(entry)
196
+ }
197
+ const names = REDACTION_PACKS.filter((name) => listed.has(name))
198
+ const compiled = names.flatMap((name) =>
199
+ PACKS[name].map((rule, index) =>
200
+ buildRule(`pack ${name}`, index, {
201
+ name: `${name}.${rule.name}`,
202
+ pattern: rule.pattern,
203
+ caseInsensitive: rule.case_insensitive,
204
+ validate: rule.validate,
205
+ }),
206
+ ),
207
+ )
208
+ return { names, rules: compiled }
209
+ }
210
+
211
+ // A redactor's compiled passes, kept off the object callers see: one for a
212
+ // rules object, several for the hooks' layered rules (§ `layered`).
213
+ const internals = new WeakMap()
214
+
215
+ /**
216
+ * Checks and compiles a rules object. Returns a frozen `{ packs, summary }`
217
+ * (the enabled packs in canonical order, and the summary mode) that
218
+ * `redactOtlpTraces` accepts. Throws RedactionConfigError naming the
219
+ * offending rule, pack or top-level key. A rules file cannot carry a masking
220
+ * function, so there is none here.
221
+ */
222
+ export const compileRedaction = (rules) => {
223
+ if (!isRecord(rules)) throw new RedactionConfigError('redaction: the rules must be an object')
224
+ for (const key of Object.keys(rules)) {
225
+ if (!TOP_LEVEL_KEYS.includes(key)) {
226
+ throw new RedactionConfigError(
227
+ `redaction: unknown key ${JSON.stringify(key)} (expected ${TOP_LEVEL_KEYS.join(', ')})`,
228
+ )
229
+ }
230
+ }
231
+ // Only an absent key defaults to info: null or any other value is an error.
232
+ const summary = rules.summary === undefined ? 'info' : rules.summary
233
+ if (summary !== 'info' && summary !== 'silent') {
234
+ throw new RedactionConfigError(
235
+ `redaction: summary must be "info" or "silent", got ${JSON.stringify(summary)}`,
236
+ )
237
+ }
238
+ const packs = compilePacks(rules)
239
+ const blocked = compileRules(rules, 'blocked_values')
240
+ const allowed = compileRules(rules, 'allowed_values')
241
+ const keyRules = compileRules(rules, 'blocked_key_patterns')
242
+ const ignoredKeys = stringList(rules, 'ignored_keys')
243
+ const ignoredKeyPatterns = stringList(rules, 'ignored_key_patterns').map((pattern, index) =>
244
+ compileRule('ignored_key_patterns', pattern, index),
245
+ )
246
+ const values = [...packs.rules, ...blocked]
247
+ const redactor = Object.freeze({ packs: Object.freeze(packs.names), summary })
248
+ internals.set(redactor, [
249
+ {
250
+ values,
251
+ allowed,
252
+ keyRules,
253
+ exempt: new Set([...BUILTIN_EXEMPT_KEYS, ...ignoredKeys]),
254
+ ignoredKeyPatterns,
255
+ summary,
256
+ // Only allow or ignore lists change nothing.
257
+ active: values.length > 0 || keyRules.length > 0,
258
+ },
259
+ ])
260
+ return redactor
261
+ }
262
+
263
+ /** One redactor that runs `redactors`' rules as separate passes, in order:
264
+ * each pass scans what the one before it left, so a later pass's
265
+ * `allowed_values` cannot bring back what an earlier one replaced. Its
266
+ * `packs` are every pass's, in canonical order, and its `summary` the last
267
+ * pass's. A single redactor is returned as it is. */
268
+ const layered = (redactors) => {
269
+ if (redactors.length === 1) return redactors[0]
270
+ const packs = REDACTION_PACKS.filter((name) => redactors.some((r) => r.packs.includes(name)))
271
+ const redactor = Object.freeze({
272
+ packs: Object.freeze(packs),
273
+ summary: redactors.at(-1)?.summary ?? 'info',
274
+ })
275
+ internals.set(
276
+ redactor,
277
+ redactors.flatMap((r) => internals.get(r)),
278
+ )
279
+ return redactor
280
+ }
281
+
282
+ // ─── Run ─────────────────────────────────────────────────────────────────
283
+
284
+ /** `text` with every value-rule match replaced, and the number replaced. A
285
+ * match an allow rule keeps, or a pack match that fails its check, stays and
286
+ * is not counted. */
287
+ const scan = (r, text) => {
288
+ let count = 0
289
+ let out = text
290
+ for (const rule of r.values) {
291
+ out = out.replace(rule.global, (match) => {
292
+ if (match === '') return match
293
+ if (rule.validate === 'luhn' && !luhnValid(match)) return match
294
+ if (r.allowed.some((allow) => allow.full.test(match))) return match
295
+ count++
296
+ return rule.token
297
+ })
298
+ }
299
+ return [out, count]
300
+ }
301
+
302
+ const unscanned = (key, shape) => {
303
+ throw new Error(`redaction cannot scan ${shape} in attribute ${JSON.stringify(key)}`)
304
+ }
305
+
306
+ const isExempt = (r, key) =>
307
+ r.exempt.has(key) || r.ignoredKeyPatterns.some((rule) => rule.search.test(key))
308
+
309
+ const keyToken = (r, key) => r.keyRules.find((rule) => rule.search.test(key))?.token
310
+
311
+ /** One span's (or one resource's) worth of redaction; `count` is what it
312
+ * replaced. */
313
+ const session = (r) => {
314
+ const s = { count: 0 }
315
+
316
+ // A plain string: the value rules alone.
317
+ s.leaf = (text) => {
318
+ if (r.values.length === 0 || text === '') return text
319
+ const [out, count] = scan(r, text)
320
+ s.count += count
321
+ return out
322
+ }
323
+
324
+ // A JSON-valued string, redacted in place: each string and number value
325
+ // token on its own, and only a changed token rewritten as a canonical JSON
326
+ // string. undefined when `text` is not JSON.
327
+ const json = (text) => {
328
+ const tokens = tokenizeJson(text)
329
+ if (tokens === undefined) return undefined
330
+ let out = ''
331
+ let last = 0
332
+ for (const token of tokens) {
333
+ const raw = text.slice(token.start, token.end)
334
+ const scanned = token.kind === 'string' ? decodeJsonString(raw) : raw
335
+ const next = s.leaf(scanned)
336
+ if (next === scanned) continue
337
+ out += text.slice(last, token.start) + encodeJsonString(next)
338
+ last = token.end
339
+ }
340
+ return last === 0 ? text : out + text.slice(last)
341
+ }
342
+
343
+ // One string under a key the caller has found not exempt.
344
+ const string = (key, text) => {
345
+ const token = keyToken(r, key)
346
+ if (token !== undefined) {
347
+ s.count++
348
+ // A value that is JSON stays JSON: the token as a JSON string.
349
+ return tokenizeJson(text) === undefined ? token : encodeJsonString(token)
350
+ }
351
+ // With no value rules nothing in a JSON value can change: skip tokenizing.
352
+ return (r.values.length === 0 ? undefined : json(text)) ?? s.leaf(text)
353
+ }
354
+
355
+ // OTLP/JSON `{ key, value }` entries, in place: a `stringValue`, and each
356
+ // `stringValue` element of an `arrayValue`. Numbers, booleans and non-string
357
+ // elements stay; a shape that could hold text the walk does not reach throws.
358
+ s.keyValues = (list) => {
359
+ if (!Array.isArray(list)) return
360
+ for (const kv of list) {
361
+ if (!isRecord(kv) || typeof kv.key !== 'string' || !isRecord(kv.value)) continue
362
+ if (isExempt(r, kv.key)) continue
363
+ const value = kv.value
364
+ for (const shape of ['kvlistValue', 'bytesValue']) {
365
+ if (Object.hasOwn(value, shape)) unscanned(kv.key, shape)
366
+ }
367
+ if (typeof value.stringValue === 'string') {
368
+ value.stringValue = string(kv.key, value.stringValue)
369
+ } else if (isRecord(value.arrayValue) && Array.isArray(value.arrayValue.values)) {
370
+ for (const element of value.arrayValue.values) {
371
+ if (!isRecord(element)) continue
372
+ for (const shape of ['arrayValue', 'kvlistValue', 'bytesValue']) {
373
+ if (Object.hasOwn(element, shape)) unscanned(kv.key, `${shape} element`)
374
+ }
375
+ if (typeof element.stringValue === 'string') {
376
+ element.stringValue = string(kv.key, element.stringValue)
377
+ }
378
+ }
379
+ }
380
+ }
381
+ }
382
+ return s
383
+ }
384
+
385
+ const listOf = (value) => (Array.isArray(value) ? value : [])
386
+
387
+ /** The count on a span's own attributes: replaces an existing entry, else
388
+ * appends one. */
389
+ const stamp = (span, count) => {
390
+ const entry = { key: REDACTION_COUNT_KEY, value: { intValue: String(count) } }
391
+ if (!Array.isArray(span.attributes)) span.attributes = []
392
+ const at = span.attributes.findIndex((kv) => kv?.key === REDACTION_COUNT_KEY)
393
+ if (at === -1) span.attributes.push(entry)
394
+ else span.attributes[at] = entry
395
+ }
396
+
397
+ /**
398
+ * A redacted deep copy of an OTLP/JSON `ExportTraceServiceRequest`; the input
399
+ * is never changed. Each resource's attributes are redacted once and their
400
+ * replacements count toward every span under that resource, so a span's
401
+ * count is the total over its name, status message, own, event, link and
402
+ * resource attributes. A layered redactor (§ `layered`) runs its passes in
403
+ * order over every value, and a span's count is the sum over the passes whose
404
+ * `summary` is `info`. A span whose count is above zero carries it as
405
+ * `mainwave.redaction.count` (an int) on its own attributes; the resource
406
+ * never does.
407
+ */
408
+ export const redactOtlpTraces = (redactor, payload) => {
409
+ const passes = internals.get(redactor)?.filter((r) => r.active)
410
+ if (passes === undefined) throw new TypeError('redactOtlpTraces: not a compiled redactor')
411
+ const out = structuredClone(payload)
412
+ if (passes.length === 0) return out
413
+ for (const resourceSpans of listOf(out?.resourceSpans)) {
414
+ const resource = passes.map((r) => {
415
+ const s = session(r)
416
+ s.keyValues(resourceSpans?.resource?.attributes)
417
+ return s.count
418
+ })
419
+ for (const scopeSpans of listOf(resourceSpans?.scopeSpans)) {
420
+ if (listOf(scopeSpans?.scope?.attributes).length > 0) {
421
+ throw new Error('redaction cannot scan scope attributes')
422
+ }
423
+ for (const span of listOf(scopeSpans?.spans)) {
424
+ if (!isRecord(span)) continue
425
+ let total = 0
426
+ passes.forEach((r, i) => {
427
+ const s = session(r)
428
+ s.count = resource[i]
429
+ if (typeof span.name === 'string') span.name = s.leaf(span.name)
430
+ s.keyValues(span.attributes)
431
+ for (const event of listOf(span.events)) s.keyValues(event?.attributes)
432
+ for (const link of listOf(span.links)) s.keyValues(link?.attributes)
433
+ if (isRecord(span.status) && typeof span.status.message === 'string') {
434
+ span.status.message = s.leaf(span.status.message)
435
+ }
436
+ if (r.summary === 'info') total += s.count
437
+ })
438
+ if (total > 0) stamp(span, total)
439
+ }
440
+ }
441
+ }
442
+ return out
443
+ }
444
+
445
+ // ─── Files ───────────────────────────────────────────────────────────────
446
+
447
+ const reasonOf = (error) =>
448
+ error?.code === 'ENOENT' ? 'no such file' : (error?.message ?? String(error))
449
+
450
+ /** Where a JSON parse failed, from the digits in the engine's message only: the
451
+ * message can quote the file, and a rules file may hold a secret. */
452
+ const jsonPosition = (error) => {
453
+ const message = String(error?.message ?? '')
454
+ // Anchored to the end, where the engine puts the position, so digits in a
455
+ // quoted snippet never match.
456
+ const found = / at position (\d+)(?: \(line (\d+) column (\d+)\))?$/.exec(message)
457
+ if (!found) return ''
458
+ return found[2] ? ` (line ${found[2]}, column ${found[3]})` : ` (at offset ${found[1]})`
459
+ }
460
+
461
+ /** The rules with the `secrets` pack on: appended to a valid `packs` list that
462
+ * lacks it, set when `packs` is absent. Anything else (`packs` of the wrong
463
+ * type, a rules value that is not an object) is left for `compileRedaction`
464
+ * to reject, so the file's own error is the one reported. */
465
+ const withSecretsPack = (rules) => {
466
+ if (!isRecord(rules)) return rules
467
+ if (rules.packs === undefined) return { ...rules, packs: ['secrets'] }
468
+ if (!Array.isArray(rules.packs) || rules.packs.includes('secrets')) return rules
469
+ return { ...rules, packs: [...rules.packs, 'secrets'] }
470
+ }
471
+
472
+ /** Reads, parses and compiles a rules file. Every failure (missing,
473
+ * unreadable, empty, not JSON, invalid rules) throws RedactionConfigError
474
+ * naming the path and the reason. `withSecrets` adds the `secrets` pack when
475
+ * the file does not list it, the way the hooks run a recorded file. */
476
+ export const readRedactionFile = (path, { withSecrets = false } = {}) => {
477
+ const where = `redaction rules file ${JSON.stringify(path)}`
478
+ let text
479
+ try {
480
+ text = readFileSync(path, 'utf8')
481
+ } catch (error) {
482
+ throw new RedactionConfigError(`${where} cannot be read: ${reasonOf(error)}`)
483
+ }
484
+ if (text.trim() === '') throw new RedactionConfigError(`${where} is empty`)
485
+ let rules
486
+ try {
487
+ rules = JSON.parse(text)
488
+ } catch (error) {
489
+ throw new RedactionConfigError(`${where} is not valid JSON${jsonPosition(error)}`)
490
+ }
491
+ try {
492
+ return compileRedaction(withSecrets ? withSecretsPack(rules) : rules)
493
+ } catch (error) {
494
+ throw new RedactionConfigError(`${where}: ${reasonOf(error)}`)
495
+ }
496
+ }
497
+
498
+ // What the hooks run when no rules file is recorded: the `secrets` pack alone,
499
+ // from the packs this module ships. Compiled on first use and kept.
500
+ let defaultRedactor
501
+ const defaultRules = () => {
502
+ defaultRedactor ??= compileRedaction({ packs: ['secrets'] })
503
+ return defaultRedactor
504
+ }
505
+
506
+ /** The CLI's own settings file, where setup records the rules file. */
507
+ const defaultSettingsPath = () => join(homedir(), '.mainwave', 'settings.json')
508
+
509
+ // A settings file that is absent (or under a missing directory) never
510
+ // configured redaction.
511
+ const isMissing = (error) => error?.code === 'ENOENT' || error?.code === 'ENOTDIR'
512
+
513
+ /**
514
+ * The packs an organization's managed settings set, as `install-hooks`
515
+ * records them: `redaction.org`, keyed by Claude config dir (an absolute
516
+ * path), each `{ packs: [<pack name>...] }`. For `configDir`, that dir's
517
+ * packs; with no `configDir` (a hook that cannot tell which Claude config
518
+ * dir it runs for: Cursor's, Kiro's, Codex's) every recorded dir's, merged,
519
+ * so such a hook redacts more, never less. `{ packs }` in canonical order, or
520
+ * `{ error }` for a malformed slot or a pack these hooks do not have (a newer
521
+ * CLI recorded it): the caller drops the span.
522
+ */
523
+ const orgPacks = (config, settingsPath, configDir) => {
524
+ if (!Object.hasOwn(config, 'org')) return { packs: [] }
525
+ const org = config.org
526
+ if (!isRecord(org)) return { error: `${settingsPath}: redaction.org must be an object` }
527
+ const want = configDir === undefined ? undefined : resolve(configDir)
528
+ const named = new Set()
529
+ for (const [dir, entry] of Object.entries(org)) {
530
+ if (
531
+ !isRecord(entry) ||
532
+ !Array.isArray(entry.packs) ||
533
+ entry.packs.some((name) => typeof name !== 'string')
534
+ ) {
535
+ return {
536
+ error: `${settingsPath}: redaction.org[${JSON.stringify(dir)}] must be { "packs": [<pack names>] }`,
537
+ }
538
+ }
539
+ if (want !== undefined && !(isAbsolute(dir) && resolve(dir) === want)) continue
540
+ for (const name of entry.packs) named.add(name)
541
+ }
542
+ const unknown = [...named].filter((name) => !Object.hasOwn(PACKS, name))
543
+ if (unknown.length > 0) {
544
+ return {
545
+ error:
546
+ `${settingsPath}: your organization's redaction packs name ${unknown.map((n) => JSON.stringify(n)).join(', ')}, ` +
547
+ `which these hooks do not have (known: ${REDACTION_PACKS.join(', ')}); a newer mainwave-cli has them`,
548
+ }
549
+ }
550
+ return { packs: REDACTION_PACKS.filter((name) => named.has(name)) }
551
+ }
552
+
553
+ /**
554
+ * Every recorded config dir's organization packs, `{ "<config dir>": [names] }`,
555
+ * for `status` and `doctor`: the entries that have the slot's shape and name a
556
+ * pack, as written. Empty when the file or the slot can't be read; the loader
557
+ * reports that. Never throws.
558
+ */
559
+ export const recordedOrgPacks = ({ settingsPath } = {}) => {
560
+ let settings
561
+ try {
562
+ settings = JSON.parse(readFileSync(settingsPath ?? defaultSettingsPath(), 'utf8'))
563
+ } catch {
564
+ return {}
565
+ }
566
+ const org =
567
+ isRecord(settings) && isRecord(settings.redaction) ? settings.redaction.org : undefined
568
+ if (!isRecord(org)) return {}
569
+ const out = {}
570
+ for (const [dir, entry] of Object.entries(org)) {
571
+ if (!isRecord(entry) || !Array.isArray(entry.packs)) continue
572
+ const packs = entry.packs.filter((name) => typeof name === 'string')
573
+ if (packs.length > 0) out[dir] = packs
574
+ }
575
+ return out
576
+ }
577
+
578
+ /**
579
+ * The rules the hooks run, from the CLI's settings file (`~/.mainwave/
580
+ * settings.json` unless `settingsPath` says otherwise), key `redaction:
581
+ * { file?: "<absolute path>", secrets?: false, org?: { "<config dir>":
582
+ * { packs } } }`. `configDir` is the Claude config dir the hook runs for, when
583
+ * it can tell (§ `orgPacks`). Synchronous; never throws.
584
+ *
585
+ * Up to two passes. The first runs the organization's packs and only those
586
+ * (`org`, which `install-hooks` records from the org's managed settings and
587
+ * nothing else writes), and is absent when there are none; it always stamps
588
+ * its count. The second is the developer's own rules, exactly as they run when
589
+ * no organization chose packs: the recorded file's rules plus the `secrets`
590
+ * pack, or `secrets` alone with no file, or nothing when `secrets` is off and
591
+ * no file is recorded. It scans what the first pass left, so nothing in it,
592
+ * `allowed_values` included, brings back a value the first pass replaced.
593
+ * `secrets` is in the first pass only when the organization lists it. One of:
594
+ * - `{ state: 'on', source: 'default', org, secrets, redactor }`: no rules
595
+ * file. With no settings at all that is the `secrets` pack alone; it also
596
+ * covers a settings file with no `redaction` key, and one that is not JSON
597
+ * and never mentions `"redaction"` (a mangled unrelated file must not turn
598
+ * redaction off);
599
+ * - `{ state: 'on', source: 'file', file, org, secrets, redactor }`: the
600
+ * organization's packs, then the recorded rules file's rules;
601
+ * - `{ state: 'off' }`: `redaction.secrets` is `false`, and no rules file
602
+ * and no organization packs are recorded;
603
+ * - `{ state: 'error', file?, org?, reason }`: the settings file exists but
604
+ * cannot be read, or is not JSON and mentions `"redaction"`; the key is
605
+ * there but malformed; the organization's packs cannot be loaded (`org:
606
+ * true`); or the rules file cannot be loaded. The caller drops the span:
607
+ * redaction that was asked for never silently turns off.
608
+ * `org` is the organization's packs this hook runs, in canonical order, and
609
+ * `secrets` whether the default is on.
610
+ * The hooks do not read `MAINWAVE_REDACTION_FILE`, the SDKs' variable: the
611
+ * settings file setup writes is the one source of truth, and a hook's
612
+ * environment is partly the repository's to set.
613
+ */
614
+ export const loadHookRedaction = ({ settingsPath, configDir } = {}) => {
615
+ let text
616
+ try {
617
+ settingsPath ??= defaultSettingsPath()
618
+ text = readFileSync(settingsPath, 'utf8')
619
+ } catch (error) {
620
+ if (isMissing(error)) return defaultOn()
621
+ return {
622
+ state: 'error',
623
+ reason: `${settingsPath ?? 'settings file'} cannot be read: ${error?.code ?? reasonOf(error)}: ${reasonOf(error)}`,
624
+ }
625
+ }
626
+ let settings
627
+ try {
628
+ settings = JSON.parse(text)
629
+ } catch {
630
+ settings = undefined
631
+ }
632
+ if (!isRecord(settings)) {
633
+ // A file we cannot parse may still hold redaction the developer set up (a
634
+ // hand-edit left a trailing comma), so it fails closed when it mentions the
635
+ // key. One that never did gets the default: a mangled file must neither
636
+ // drop every hook span nor switch the default off.
637
+ if (text.includes('"redaction"')) {
638
+ return {
639
+ state: 'error',
640
+ reason: `${settingsPath} is not valid JSON, so its redaction settings cannot be read`,
641
+ }
642
+ }
643
+ return defaultOn()
644
+ }
645
+ if (!Object.hasOwn(settings, 'redaction')) return defaultOn()
646
+ const config = settings.redaction
647
+ if (!isRecord(config)) {
648
+ return { state: 'error', reason: `${settingsPath}: redaction must be an object` }
649
+ }
650
+ if (Object.hasOwn(config, 'secrets') && typeof config.secrets !== 'boolean') {
651
+ return {
652
+ state: 'error',
653
+ reason: `${settingsPath}: redaction.secrets must be true or false, got ${JSON.stringify(config.secrets)}`,
654
+ }
655
+ }
656
+ const secrets = config.secrets !== false
657
+ const org = orgPacks(config, settingsPath, configDir)
658
+ if (org.error !== undefined) return { state: 'error', org: true, reason: org.error }
659
+ // The organization's pass, then the developer's own (§ above).
660
+ const first = () => (org.packs.length > 0 ? [compileRedaction({ packs: org.packs })] : [])
661
+ if (!Object.hasOwn(config, 'file')) {
662
+ if (org.packs.length === 0) return secrets ? defaultOn() : { state: 'off' }
663
+ return on('default', { org: org.packs, secrets }, () => [
664
+ ...first(),
665
+ ...(secrets ? [defaultRules()] : []),
666
+ ])
667
+ }
668
+ const file = config.file
669
+ if (typeof file !== 'string' || file === '' || !isAbsolute(file)) {
670
+ return {
671
+ state: 'error',
672
+ ...(typeof file === 'string' && file !== '' ? { file } : {}),
673
+ reason: `${settingsPath}: redaction.file must be an absolute path, got ${JSON.stringify(file)}`,
674
+ }
675
+ }
676
+ let developer
677
+ try {
678
+ developer = readRedactionFile(file, { withSecrets: secrets })
679
+ } catch (error) {
680
+ return { state: 'error', file, reason: reasonOf(error) }
681
+ }
682
+ return on('file', { file, org: org.packs, secrets }, () => [...first(), developer])
683
+ }
684
+
685
+ /** An `on` loader result over the passes `build` compiles. The packs ship in
686
+ * this package, so compiling them does not fail in practice; if the packaged
687
+ * data were ever broken it fails closed rather than send unchecked spans. */
688
+ const on = (source, fields, build) => {
689
+ try {
690
+ return { state: 'on', source, ...fields, redactor: layered(build()) }
691
+ } catch (error) {
692
+ return {
693
+ state: 'error',
694
+ ...(fields.file === undefined ? {} : { file: fields.file }),
695
+ reason: `the redaction packs cannot be loaded: ${reasonOf(error)}`,
696
+ }
697
+ }
698
+ }
699
+
700
+ /** The default rules as a loader result: the `secrets` pack alone. */
701
+ const defaultOn = () => on('default', { org: [], secrets: true }, () => [defaultRules()])