advisers 0.2.3 → 0.3.1

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 (70) hide show
  1. package/LICENSE +0 -0
  2. package/NOTICE +0 -0
  3. package/README-zh.md +15 -6
  4. package/README.md +22 -6
  5. package/THIRD-PARTY-NOTICES.md +1 -1
  6. package/bin/advisers.js +3323 -222
  7. package/index.js +1 -1
  8. package/lib/agent.js +0 -0
  9. package/lib/attachments.js +0 -0
  10. package/lib/audit-anchor.js +683 -0
  11. package/lib/backup.js +1345 -0
  12. package/lib/capture.js +0 -0
  13. package/lib/context-window.js +0 -0
  14. package/lib/digest.js +0 -0
  15. package/lib/doc-review.js +0 -0
  16. package/lib/egress.js +0 -0
  17. package/lib/error-codes.js +1373 -0
  18. package/lib/evidence.js +202 -26
  19. package/lib/fs-safe.js +70 -7
  20. package/lib/ical.js +0 -0
  21. package/lib/imap.js +6 -2
  22. package/lib/importers.js +0 -0
  23. package/lib/learning.js +0 -0
  24. package/lib/ledger-read.js +608 -0
  25. package/lib/mcp-server.js +294 -38
  26. package/lib/model.js +0 -0
  27. package/lib/node-warning-filter.js +15 -0
  28. package/lib/notify.js +13 -3
  29. package/lib/nudge.js +0 -0
  30. package/lib/ocr.js +0 -0
  31. package/lib/pdf.js +0 -0
  32. package/lib/pet-brief-store.js +0 -0
  33. package/lib/pet-brief.js +102 -39
  34. package/lib/receipt-verify.js +213 -15
  35. package/lib/relative-date.js +0 -0
  36. package/lib/remind.js +91 -36
  37. package/lib/research.js +0 -0
  38. package/lib/review.js +0 -0
  39. package/lib/routine.js +0 -0
  40. package/lib/safety/classifier.js +0 -0
  41. package/lib/safety/explain.js +0 -0
  42. package/lib/safety/index.js +0 -0
  43. package/lib/safety/redact.js +0 -0
  44. package/lib/safety/rules.js +0 -0
  45. package/lib/scheduler.js +0 -0
  46. package/lib/source.js +0 -0
  47. package/lib/sqlite.js +1214 -24
  48. package/lib/sync.js +0 -0
  49. package/lib/text-safe.js +229 -0
  50. package/lib/timestamp.js +0 -0
  51. package/lib/tos/index.js +1 -1
  52. package/lib/tos/manifest.json +6 -6
  53. package/lib/tos/privacy.zh-CN.md +12 -9
  54. package/lib/tos/safety.zh-CN.md +4 -3
  55. package/lib/tos/summary.zh-CN.md +3 -3
  56. package/lib/tos/terms.zh-CN.md +8 -6
  57. package/lib/tui/color.js +164 -0
  58. package/lib/tui/index.js +33 -0
  59. package/lib/tui/json.js +124 -0
  60. package/lib/tui/labels.js +50 -0
  61. package/lib/tui/policy.js +108 -0
  62. package/lib/tui/render.js +371 -0
  63. package/lib/tui/sanitize.js +142 -0
  64. package/lib/tui/text-file.js +116 -0
  65. package/lib/tui/width.js +577 -0
  66. package/lib/ui.js +0 -0
  67. package/lib/undo.js +0 -0
  68. package/lib/untrusted.js +0 -0
  69. package/lib/vault.js +0 -0
  70. package/package.json +6 -5
@@ -0,0 +1,371 @@
1
+ /**
2
+ * Pure renderers for the 0.3.0 output kernel: status line, result/error/confirm blocks
3
+ * and the read-only snapshot. No I/O, no readline, no clock, no store access.
4
+ *
5
+ * The same functions serve three consumers, which is the point of the kernel:
6
+ * - the future interactive shell (0.3.1) and the existing CLI human output;
7
+ * - --once / redirected / --plain / --accessible byte snapshots;
8
+ * - golden unit tests.
9
+ *
10
+ * Layout rules (docs/TUI.md):
11
+ * - append-only lines, no borders, no tabs, no full-width padding;
12
+ * - every line is display width <= the requested width (prefix included);
13
+ * - prefixes are stable: '> ', ' - ', ' 文件:', ' 校验:', ' ! ',
14
+ * ' 下一步:', '! 没做成:', '! 需要确认:', '[状态] ';
15
+ * - sanitisation happens before measurement/wrapping: model output, tool results,
16
+ * IMAP subjects and webhook bodies are untrusted text and are treated as data;
17
+ * - colour (when enabled) only ever uses the 16-colour SGR whitelist and never
18
+ * carries the only meaning - every line keeps its textual prefix.
19
+ *
20
+ * Options accepted by every renderer: { width, color, accessible, labels, ... }.
21
+ * A resolveOutputPolicy() object can be spread into the options; width is normally
22
+ * clampColumns(process.stdout.columns).
23
+ */
24
+ import { styleText } from './color.js'
25
+ import { DEFAULT_LABELS } from './labels.js'
26
+ import { sanitizeDisplay } from './sanitize.js'
27
+ import { clampColumns, strWidth, truncateMiddle, truncateToWidth, wrap } from './width.js'
28
+
29
+ const ROLE_PREFIX = Object.freeze({
30
+ fact: 'indent',
31
+ body: 'indent',
32
+ item: 'itemPrefix',
33
+ check: 'checkPrefix',
34
+ warning: 'warningPrefix',
35
+ next: 'nextPrefix',
36
+ reason: 'reasonPrefix',
37
+ kept: 'keptPrefix',
38
+ write: 'writePrefix',
39
+ summary: 'summaryPrefix',
40
+ digest: 'digestPrefix',
41
+ code: 'codePrefix',
42
+ })
43
+
44
+ const ROLE_STYLE = Object.freeze({
45
+ warning: 'yellow',
46
+ next: 'dim',
47
+ code: 'dim',
48
+ })
49
+
50
+ /**
51
+ * Format a byte count for an artifact line (`23.4 KB`).
52
+ *
53
+ * @param {number} bytes
54
+ * @returns {string}
55
+ */
56
+ export function formatBytes(bytes) {
57
+ if (!Number.isFinite(bytes) || bytes < 0) return ''
58
+ if (bytes < 1024) return `${Math.floor(bytes)} B`
59
+ const units = ['KB', 'MB', 'GB', 'TB']
60
+ let value = bytes / 1024
61
+ let index = 0
62
+ while (value >= 1024 && index < units.length - 1) {
63
+ value /= 1024
64
+ index += 1
65
+ }
66
+ const rounded = Math.round(value * 10) / 10
67
+ return `${rounded} ${units[index]}`
68
+ }
69
+
70
+ /**
71
+ * Format a duration for the verbose duration line (`320ms`, `1.2s`, `2m5s`).
72
+ *
73
+ * @param {number} milliseconds
74
+ * @returns {string}
75
+ */
76
+ export function formatDuration(milliseconds) {
77
+ if (!Number.isFinite(milliseconds) || milliseconds < 0) return ''
78
+ if (milliseconds < 1000) return `${Math.round(milliseconds)}ms`
79
+ if (milliseconds < 60000) return `${Math.round(milliseconds / 100) / 10}s`
80
+ const totalSeconds = Math.round(milliseconds / 1000)
81
+ return `${Math.floor(totalSeconds / 60)}m${totalSeconds % 60}s`
82
+ }
83
+
84
+ /**
85
+ * Render the one-line status. Returns a single string, never a multi-line block.
86
+ *
87
+ * Kinds: idle (default), busy, confirm, error, offline. With `accessible: true` the
88
+ * symbol is replaced by `[状态] ` (screen-reader friendly) and colour is disabled.
89
+ * When the width is too small, right-most segments are dropped in order (hint, model,
90
+ * today summary), then the line is truncated with an ellipsis.
91
+ *
92
+ * @param {{
93
+ * kind?: 'idle' | 'busy' | 'confirm' | 'error' | 'offline',
94
+ * today?: { due?: number, overdue?: number },
95
+ * model?: string | null, local?: boolean,
96
+ * hint?: string | null, seconds?: number, reason?: string,
97
+ * }} [status]
98
+ * @param {{ width?: number, color?: boolean, accessible?: boolean, labels?: object }} [options]
99
+ * @returns {string}
100
+ */
101
+ export function renderStatus(status = {}, options = {}) {
102
+ const { width, color, accessible, labels } = renderOptions(options)
103
+ const value = status ?? {}
104
+ const kind = typeof value.kind === 'string' ? value.kind : 'idle'
105
+ const segments = []
106
+ let symbol = '*'
107
+ let style = 'dim'
108
+ let dropFront = false
109
+ if (kind === 'busy') {
110
+ symbol = '~'
111
+ style = 'yellow'
112
+ segments.push(Number.isFinite(value.seconds) ? labels.statusBusy(Math.max(0, Math.floor(value.seconds))) : labels.statusBusyNoTimer)
113
+ } else if (kind === 'confirm') {
114
+ symbol = '!'
115
+ style = 'yellow'
116
+ segments.push(labels.statusConfirm)
117
+ } else if (kind === 'error') {
118
+ symbol = '!'
119
+ style = 'red'
120
+ const reason = sanitizeDisplay(value.reason === undefined || value.reason === null || value.reason === '' ? labels.statusUnknownReason : value.reason, { singleLine: true })
121
+ segments.push(labels.statusError(reason))
122
+ } else if (kind === 'offline') {
123
+ style = 'yellow'
124
+ // Degrade from the front: dropping the offline signal would claim health.
125
+ dropFront = true
126
+ segments.push(labels.statusReady)
127
+ segments.push(labels.statusOffline)
128
+ } else {
129
+ segments.push(labels.statusReady)
130
+ if (value.today && typeof value.today === 'object') {
131
+ const due = toCount(value.today.due)
132
+ const overdue = toCount(value.today.overdue)
133
+ segments.push(due === 0 && overdue === 0 ? labels.statusTodayClear : labels.statusToday(due, overdue))
134
+ }
135
+ if (value.local === true || value.model === 'local') segments.push(labels.statusLocalModel)
136
+ else if (typeof value.model === 'string' && value.model.length > 0) segments.push(sanitizeDisplay(value.model, { singleLine: true }))
137
+ const hint = value.hint === undefined ? labels.statusHelpHint : value.hint
138
+ if (hint !== null && hint !== undefined && hint !== '') segments.push(sanitizeDisplay(hint, { singleLine: true }))
139
+ }
140
+ const prefix = accessible ? labels.statusAccessiblePrefix : `${symbol} `
141
+ const compose = () => prefix + segments.join(labels.statusSeparator)
142
+ while (segments.length > 1 && strWidth(compose()) > width) {
143
+ if (dropFront) segments.shift()
144
+ else segments.pop()
145
+ }
146
+ let line = compose()
147
+ if (strWidth(line) > width) line = truncateToWidth(line, width)
148
+ if (color && !accessible) line = styleText(prefix, style) + line.slice(prefix.length)
149
+ return line
150
+ }
151
+
152
+ /**
153
+ * Render a result/error/notice block as display lines (append-only, no trailing newline).
154
+ *
155
+ * @param {{
156
+ * kind?: 'result' | 'error' | 'notice',
157
+ * prompt?: string,
158
+ * headline?: string,
159
+ * summary?: string,
160
+ * lines?: Array<string | { text: string, role?: string }>,
161
+ * artifacts?: Array<{ path: string, bytes?: number, verified?: boolean | null }>,
162
+ * checks?: string[],
163
+ * warnings?: string[],
164
+ * next?: string,
165
+ * durationMs?: number,
166
+ * tools?: Array<{ name: string, ok: boolean }>,
167
+ * code?: string,
168
+ * }} [block]
169
+ * @param {{ width?: number, color?: boolean, accessible?: boolean, labels?: object, maxLines?: number, maxItems?: number, verbose?: boolean }} [options]
170
+ * @returns {string[]}
171
+ */
172
+ export function renderResult(block = {}, options = {}) {
173
+ const { width, color, labels, maxLines, maxItems, verbose } = renderOptions(options)
174
+ const value = block ?? {}
175
+ const kind = value.kind === 'error' ? 'error' : value.kind === 'notice' ? 'notice' : 'result'
176
+ const out = []
177
+ if (value.prompt !== undefined && value.prompt !== null && value.prompt !== '') {
178
+ const text = sanitizeDisplay(value.prompt, { singleLine: true })
179
+ const available = Math.max(1, width - strWidth(labels.userPrefix))
180
+ const line = labels.userPrefix + truncateToWidth(text, available)
181
+ out.push(color ? styleText(line, 'dim') : line)
182
+ }
183
+ if (kind === 'error') {
184
+ pushField(out, value.headline ?? value.title ?? '', { prefix: labels.errorPrefix, width, color, style: 'red' })
185
+ } else if (value.headline !== undefined && value.headline !== null && value.headline !== '') {
186
+ pushField(out, value.headline, { prefix: labels.indent, width })
187
+ }
188
+ if (value.summary !== undefined && value.summary !== null && value.summary !== '') pushSummary(out, value.summary, { width, maxLines, labels })
189
+ let itemCount = 0
190
+ for (const raw of Array.isArray(value.lines) ? value.lines : []) {
191
+ const line = typeof raw === 'string' ? { text: raw } : raw
192
+ if (line === null || typeof line !== 'object' || line.text === undefined || line.text === null) continue
193
+ if (typeof line.text === 'string' && line.text.trim() === '') continue
194
+ const role = typeof line.role === 'string' && ROLE_PREFIX[line.role] !== undefined ? line.role : 'fact'
195
+ if (role === 'item') {
196
+ itemCount += 1
197
+ if (itemCount > maxItems) continue
198
+ }
199
+ const prefix = labels[ROLE_PREFIX[role]]
200
+ const style = ROLE_STYLE[role]
201
+ pushField(out, line.text, { prefix, width, color: color && style !== undefined, style })
202
+ }
203
+ if (itemCount > maxItems) out.push(labels.overflowItems(itemCount - maxItems))
204
+ for (const artifact of Array.isArray(value.artifacts) ? value.artifacts : []) {
205
+ if (artifact === null || typeof artifact !== 'object') continue
206
+ if (typeof artifact.path !== 'string' || artifact.path === '') continue
207
+ pushField(out, artifactLine(artifact, width, labels), { prefix: labels.filePrefix, width })
208
+ }
209
+ for (const check of Array.isArray(value.checks) ? value.checks : []) {
210
+ if (check === undefined || check === null || String(check).trim() === '') continue
211
+ pushField(out, check, { prefix: labels.checkPrefix, width })
212
+ }
213
+ const warnings = Array.isArray(value.warnings) ? value.warnings.filter((warning) => warning !== undefined && warning !== null && warning !== '') : []
214
+ if (warnings.length > 0) {
215
+ const suffix = warnings.length > 1 ? labels.warningOverflow(warnings.length - 1) : ''
216
+ pushField(out, `${warnings[0]}${suffix}`, { prefix: labels.warningPrefix, width, color, style: 'yellow' })
217
+ }
218
+ if (value.next !== undefined && value.next !== null && value.next !== '') pushField(out, value.next, { prefix: labels.nextPrefix, width, color, style: 'dim' })
219
+ if (kind === 'error' && value.code !== undefined && value.code !== null && value.code !== '') pushField(out, value.code, { prefix: labels.codePrefix, width, color, style: 'dim' })
220
+ if (verbose) {
221
+ for (const tool of Array.isArray(value.tools) ? value.tools : []) {
222
+ if (tool === null || typeof tool !== 'object') continue
223
+ const name = sanitizeDisplay(tool.name ?? 'tool', { singleLine: true })
224
+ out.push(labels.verboseTool(name, tool.ok === true))
225
+ }
226
+ if (Number.isFinite(value.durationMs)) out.push(labels.verboseDuration(formatDuration(value.durationMs)))
227
+ }
228
+ return out
229
+ }
230
+
231
+ /**
232
+ * Render a failure block: `! 没做成:<what>` + 原因 / 已保留 / 下一步 / 代码.
233
+ *
234
+ * @param {{ title?: string, what?: string, reason?: string, kept?: string, next?: string, code?: string, lines?: Array<string | object>, warnings?: string[], prompt?: string }} [error]
235
+ * @param {object} [options] same options as renderResult
236
+ * @returns {string[]}
237
+ */
238
+ export function renderError(error = {}, options = {}) {
239
+ const value = error ?? {}
240
+ const lines = []
241
+ if (value.reason !== undefined && value.reason !== null && value.reason !== '') lines.push({ role: 'reason', text: value.reason })
242
+ for (const extra of Array.isArray(value.lines) ? value.lines : []) lines.push(extra)
243
+ if (value.kept !== undefined && value.kept !== null && value.kept !== '') lines.push({ role: 'kept', text: value.kept })
244
+ return renderResult({
245
+ kind: 'error',
246
+ prompt: value.prompt,
247
+ headline: value.title ?? value.what ?? '',
248
+ lines,
249
+ warnings: value.warnings,
250
+ next: value.next,
251
+ code: value.code,
252
+ }, options)
253
+ }
254
+
255
+ /**
256
+ * Render a confirmation block. Default answer is always No; the caller renders the
257
+ * outcome and passes the digest back to policy (the shell only renders/echoes it).
258
+ *
259
+ * @param {{ title?: string, what?: string, reason?: string, write?: string, summary?: string, digest?: string, prompt?: string }} [confirm]
260
+ * @param {object} [options] same options as renderResult
261
+ * @returns {string[]}
262
+ */
263
+ export function renderConfirm(confirm = {}, options = {}) {
264
+ const { width, color, labels } = renderOptions(options)
265
+ const value = confirm ?? {}
266
+ const out = []
267
+ pushField(out, value.title ?? value.what ?? '', { prefix: labels.confirmPrefix, width, color, style: 'yellow' })
268
+ if (value.reason !== undefined && value.reason !== null && value.reason !== '') pushField(out, value.reason, { prefix: labels.reasonPrefix, width })
269
+ if (value.write !== undefined && value.write !== null && value.write !== '') pushField(out, value.write, { prefix: labels.writePrefix, width })
270
+ if (value.summary !== undefined && value.summary !== null && value.summary !== '') pushField(out, value.summary, { prefix: labels.summaryPrefix, width })
271
+ if (value.digest !== undefined && value.digest !== null && value.digest !== '') pushField(out, value.digest, { prefix: labels.digestPrefix, width })
272
+ const prompt = value.prompt === undefined ? labels.confirmPrompt : value.prompt
273
+ if (prompt !== null && prompt !== undefined && prompt !== '') {
274
+ const text = sanitizeDisplay(prompt, { singleLine: true })
275
+ const available = Math.max(1, width - strWidth(labels.indent))
276
+ const line = labels.indent + truncateToWidth(text, available)
277
+ out.push(color ? styleText(line, 'dim') : line)
278
+ }
279
+ return out
280
+ }
281
+
282
+ /**
283
+ * Render the read-only `tui --once` snapshot shape as display lines.
284
+ *
285
+ * The current dashboard text stays owned by bin/advisers.js until the Wave-2 wiring;
286
+ * this renderer exists so a future snapshot/--plain path shares the same width and
287
+ * sanitisation rules. Sections are rendered in order with a blank line between them.
288
+ *
289
+ * @param {{ title?: string, sections?: Array<{ heading?: string, lines?: string[] }> }} [snapshot]
290
+ * @param {{ width?: number, color?: boolean, labels?: object }} [options]
291
+ * @returns {string[]}
292
+ */
293
+ export function renderSnapshot(snapshot = {}, options = {}) {
294
+ const { width, labels } = renderOptions(options)
295
+ const value = snapshot ?? {}
296
+ const out = []
297
+ if (value.title !== undefined && value.title !== null && value.title !== '') pushField(out, value.title, { prefix: '', width })
298
+ for (const section of Array.isArray(value.sections) ? value.sections : []) {
299
+ if (section === null || typeof section !== 'object') continue
300
+ if (out.length > 0) out.push('')
301
+ if (section.heading !== undefined && section.heading !== null && section.heading !== '') pushField(out, section.heading, { prefix: '', width })
302
+ for (const line of Array.isArray(section.lines) ? section.lines : []) pushField(out, line, { prefix: labels.indent, width })
303
+ }
304
+ return out
305
+ }
306
+
307
+ function renderOptions(options = {}) {
308
+ const value = options ?? {}
309
+ const accessible = value.accessible === true
310
+ return {
311
+ width: clampColumns(value.width),
312
+ color: value.color === true && !accessible,
313
+ accessible,
314
+ labels: value.labels ?? DEFAULT_LABELS,
315
+ maxLines: Number.isInteger(value.maxLines) && value.maxLines >= 0 ? value.maxLines : 20,
316
+ maxItems: Number.isInteger(value.maxItems) && value.maxItems >= 0 ? value.maxItems : 8,
317
+ verbose: value.verbose === true,
318
+ }
319
+ }
320
+
321
+ function pushField(out, value, { prefix = '', width, color = false, style = null }) {
322
+ const text = sanitizeDisplay(value, { singleLine: true, expandTabs: true })
323
+ if (text === '' && prefix === '') return
324
+ const prefixWidth = strWidth(prefix)
325
+ const continuation = ' '.repeat(prefixWidth)
326
+ const bodyWidth = Math.max(1, width - prefixWidth)
327
+ const lines = text === '' ? [''] : wrap(text, bodyWidth)
328
+ for (let index = 0; index < lines.length; index += 1) {
329
+ const line = ((index === 0 ? prefix : continuation) + lines[index]).replace(/ +$/, '')
330
+ out.push(color && style !== null ? styleText(line, style) : line)
331
+ }
332
+ }
333
+
334
+ function pushSummary(out, value, { width, maxLines, labels }) {
335
+ const text = sanitizeDisplay(value, { expandTabs: true })
336
+ const lines = []
337
+ for (const sourceLine of text.split('\n')) {
338
+ if (sourceLine === '') {
339
+ lines.push('')
340
+ continue
341
+ }
342
+ for (const wrapped of wrap(sourceLine, Math.max(1, width - strWidth(labels.indent)))) lines.push(labels.indent + wrapped)
343
+ }
344
+ if (lines.length <= maxLines) {
345
+ out.push(...lines)
346
+ return
347
+ }
348
+ out.push(...lines.slice(0, maxLines))
349
+ out.push(labels.overflowLines(lines.length - maxLines))
350
+ }
351
+
352
+ function artifactLine(artifact, width, labels) {
353
+ const prefixWidth = strWidth(labels.filePrefix)
354
+ const available = Math.max(1, width - prefixWidth)
355
+ const parts = []
356
+ if (Number.isFinite(artifact.bytes)) parts.push(formatBytes(artifact.bytes))
357
+ if (artifact.verified === true) parts.push('结构通过')
358
+ if (artifact.verified === false) parts.push('校验失败')
359
+ const suffix = parts.length > 0 ? `(${parts.join(',')})` : ''
360
+ const path = sanitizeDisplay(artifact.path ?? '', { singleLine: true })
361
+ const pathBudget = available - strWidth(suffix)
362
+ const displayPath = strWidth(path) > pathBudget ? truncateMiddle(path, Math.max(1, pathBudget)) : path
363
+ const line = displayPath + suffix
364
+ return strWidth(line) > available ? truncateMiddle(line, available) : line
365
+ }
366
+
367
+ function toCount(value) {
368
+ const number = typeof value === 'number' ? value : Number.parseInt(String(value ?? ''), 10)
369
+ return Number.isFinite(number) && number > 0 ? Math.floor(number) : 0
370
+ }
371
+
@@ -0,0 +1,142 @@
1
+ /**
2
+ * Display sanitisation policy for terminal output (0.3.0 output kernel).
3
+ *
4
+ * Two distinct jobs, deliberately kept apart:
5
+ *
6
+ * sanitizeDisplay() terminal rendering policy: keep line structure and tabs (so
7
+ * result blocks can be laid out), strip everything that can
8
+ * forge terminal state. Used by every render* function.
9
+ * jsonSafe() display safety for JSON string fields (message/hint/subject
10
+ * and other strings that a human or terminal may echo). It keeps
11
+ * newlines (JSON.stringify escapes them) but strips ESC/C1 and
12
+ * bidi/zero-width marks.
13
+ *
14
+ * Data contract: sanitisation happens at the rendering/emission boundary; it never
15
+ * rewrites database rows or the semantics of a --json field. docs/TUI.md records the
16
+ * boundary, and tests assert both the sanitised view and the untouched data.
17
+ */
18
+ import { stripBom, stripTerminalSequences } from '../text-safe.js'
19
+ import { expandTabs, truncateToWidth } from './width.js'
20
+
21
+ const C0_NO_LINE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g
22
+ const C1_ALL = /[\u0080-\u009F]/g
23
+ // Bidi overrides/isolates plus U+FEFF can reorder or hide rendered text. Unlike the
24
+ // console/log layer, display sanitisation keeps ZWJ/ZWNJ/ZWSP: they are part of
25
+ // legitimate text (emoji ZWJ families, Indic/emoji clusters) and have zero width.
26
+ const BIDI_DISPLAY = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/g
27
+ const UNSAFE_DISPLAY = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/
28
+
29
+ /**
30
+ * Sanitise text for terminal display.
31
+ *
32
+ * Pipeline: CRLF/CR -> LF; strip escape sequences (CSI/OSC/DCS/SOS/PM/APC); strip
33
+ * bidi/zero-width marks; drop remaining C0 (except \n and \t) and all C1. Normal
34
+ * Chinese punctuation, emoji and combining sequences are preserved.
35
+ *
36
+ * @param {unknown} value
37
+ * @param {{
38
+ * singleLine?: boolean, // fold newlines/tabs to spaces (one-line fields)
39
+ * maxWidth?: number, // truncate each line to N display columns
40
+ * maxChars?: number, // compatibility alias for maxWidth
41
+ * expandTabs?: boolean, // replace tabs with spaces (use before rendering)
42
+ * tabSize?: number,
43
+ * ellipsis?: string
44
+ * }} [options]
45
+ * @returns {string}
46
+ */
47
+ export function sanitizeDisplay(value, { singleLine = false, maxWidth, maxChars, expandTabs: shouldExpandTabs = false, tabSize = 4, ellipsis = '\u2026' } = {}) {
48
+ if (value === null || value === undefined) return ''
49
+ let text = typeof value === 'string' ? value : String(value)
50
+ text = stripBom(text)
51
+ text = text.replace(/\r\n?/g, '\n')
52
+ text = stripTerminalSequences(text)
53
+ text = text.replace(BIDI_DISPLAY, '')
54
+ text = text.replace(C0_NO_LINE, '')
55
+ text = text.replace(C1_ALL, '')
56
+ if (shouldExpandTabs) text = expandTabs(text, tabSize)
57
+ const limit = maxWidth === undefined ? maxChars : maxWidth
58
+ const hasLimit = typeof limit === 'number' && Number.isFinite(limit)
59
+ const widthLimit = hasLimit ? Math.max(0, Math.floor(limit)) : 0
60
+ if (singleLine) {
61
+ text = text.replace(/\t/g, ' ').replace(/\n+/g, ' ').replace(/ {2,}/g, ' ').trim()
62
+ return hasLimit ? truncateToWidth(text, widthLimit, { ellipsis }) : text
63
+ }
64
+ if (!hasLimit) return text
65
+ return text
66
+ .split('\n')
67
+ .map((line) => truncateToWidth(line, widthLimit, { ellipsis }))
68
+ .join('\n')
69
+ }
70
+
71
+ /**
72
+ * True when the string still contains characters that can forge terminal state
73
+ * (ESC/C0/C1/bidi/zero-width). Used by tests and the --plain output gate.
74
+ *
75
+ * @param {unknown} value
76
+ * @returns {boolean}
77
+ */
78
+ export function hasUnsafeDisplayChars(value) {
79
+ if (typeof value !== 'string') return false
80
+ return UNSAFE_DISPLAY.test(value)
81
+ }
82
+
83
+ /**
84
+ * Inverse of hasUnsafeDisplayChars().
85
+ *
86
+ * @param {unknown} value
87
+ * @returns {boolean}
88
+ */
89
+ export function isDisplaySafe(value) {
90
+ return !hasUnsafeDisplayChars(value)
91
+ }
92
+
93
+ /**
94
+ * Deep-copy a JSON value with display-unsafe characters removed from strings and keys.
95
+ *
96
+ * Use it for human-facing JSON fields (error message/hint, remote subject lines). It is
97
+ * intentionally not the default for data fields: --json data keeps its value, and
98
+ * assertJsonPure() is the gate that catches control bytes in the emitted stream.
99
+ *
100
+ * @template T
101
+ * @param {T} value
102
+ * @returns {T}
103
+ */
104
+ export function jsonSafe(value) {
105
+ return sanitizeJsonValue(value, new WeakSet())
106
+ }
107
+
108
+ function sanitizeJsonValue(value, seen) {
109
+ if (typeof value === 'string') return sanitizeJsonString(value)
110
+ if (value === null || typeof value !== 'object') return value
111
+ if (seen.has(value)) throw new TypeError('jsonSafe: cyclic structure')
112
+ seen.add(value)
113
+ let out
114
+ if (Array.isArray(value)) {
115
+ out = value.map((item) => sanitizeJsonValue(item, seen))
116
+ } else {
117
+ out = {}
118
+ for (const [key, item] of Object.entries(value)) out[sanitizeJsonString(key)] = sanitizeJsonValue(item, seen)
119
+ }
120
+ seen.delete(value)
121
+ return out
122
+ }
123
+
124
+ /**
125
+ * Sanitise one JSON string field: strip escape sequences, bidi/zero-width marks and
126
+ * C0/C1 controls, normalise CRLF to LF. Newlines and tabs are kept as data (JSON
127
+ * serialisers escape them); normal CJK punctuation and emoji are preserved.
128
+ *
129
+ * @param {unknown} value
130
+ * @returns {string}
131
+ */
132
+ export function sanitizeJsonString(value) {
133
+ if (value === null || value === undefined) return ''
134
+ let text = typeof value === 'string' ? value : String(value)
135
+ text = stripBom(text)
136
+ text = stripTerminalSequences(text)
137
+ text = text.replace(BIDI_DISPLAY, '')
138
+ text = text.replace(/\r\n?/g, '\n')
139
+ text = text.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '')
140
+ return text
141
+ }
142
+
@@ -0,0 +1,116 @@
1
+ /**
2
+ * BOM-aware text/JSON file helpers (0.3.0 output kernel).
3
+ *
4
+ * Windows PowerShell 5.1 is a first-class environment for Advisers and it writes
5
+ * BOMs: `Out-File -Encoding utf8` emits EF BB BF, `>` / `>>` redirection emits a
6
+ * UTF-16LE BOM (FF FE). Node then reads the BOM as a character and JSON.parse fails.
7
+ * These helpers detect and remove the BOM at the read boundary (parsing only; the
8
+ * original bytes and their hashes are never rewritten), and write UTF-8 without a BOM
9
+ * atomically through lib/fs-safe.js.
10
+ *
11
+ * This module does not decide which inputs are user-editable; the Wave-2 CLI wiring
12
+ * routes import/template/state/office-edit reads through it.
13
+ */
14
+ import { readFileSync } from 'node:fs'
15
+ import { atomicWriteFileSync } from '../fs-safe.js'
16
+ import { stripBom } from '../text-safe.js'
17
+ import { stringifyJson } from './json.js'
18
+
19
+ const UTF8_BOM = [0xef, 0xbb, 0xbf]
20
+ const UTF16LE_BOM = [0xff, 0xfe]
21
+ const UTF16BE_BOM = [0xfe, 0xff]
22
+
23
+ /**
24
+ * Decode a buffer into text, removing a leading BOM and decoding UTF-16 when the BOM
25
+ * says so (PowerShell 5.1 redirection). Unknown input is decoded as UTF-8.
26
+ *
27
+ * @param {Buffer | Uint8Array | string} buffer
28
+ * @returns {string}
29
+ */
30
+ export function decodeTextBuffer(buffer) {
31
+ if (typeof buffer === 'string') return stripBom(buffer)
32
+ const bytes = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer ?? [])
33
+ if (bytes.length >= 3 && bytes[0] === UTF8_BOM[0] && bytes[1] === UTF8_BOM[1] && bytes[2] === UTF8_BOM[2]) {
34
+ return stripBom(bytes.subarray(3).toString('utf8'))
35
+ }
36
+ if (bytes.length >= 2 && bytes[0] === UTF16LE_BOM[0] && bytes[1] === UTF16LE_BOM[1]) {
37
+ return stripBom(bytes.subarray(2).toString('utf16le'))
38
+ }
39
+ if (bytes.length >= 2 && bytes[0] === UTF16BE_BOM[0] && bytes[1] === UTF16BE_BOM[1]) {
40
+ const body = Buffer.from(bytes.subarray(2))
41
+ if (body.length % 2 !== 0) body.writeUInt8(0, body.length - 1)
42
+ body.swap16()
43
+ return stripBom(body.toString('utf16le'))
44
+ }
45
+ return stripBom(bytes.toString('utf8'))
46
+ }
47
+
48
+ /**
49
+ * True when the leading bytes are a BOM this module understands.
50
+ *
51
+ * @param {Buffer | Uint8Array} buffer
52
+ * @returns {boolean}
53
+ */
54
+ export function hasTextBom(buffer) {
55
+ const bytes = Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer ?? [])
56
+ if (bytes.length >= 3 && bytes[0] === UTF8_BOM[0] && bytes[1] === UTF8_BOM[1] && bytes[2] === UTF8_BOM[2]) return true
57
+ if (bytes.length >= 2 && bytes[0] === UTF16LE_BOM[0] && bytes[1] === UTF16LE_BOM[1]) return true
58
+ if (bytes.length >= 2 && bytes[0] === UTF16BE_BOM[0] && bytes[1] === UTF16BE_BOM[1]) return true
59
+ return false
60
+ }
61
+
62
+ /**
63
+ * Read a text file as UTF-8, stripping a UTF-8/UTF-16 BOM if present.
64
+ *
65
+ * @param {string} file
66
+ * @returns {string}
67
+ */
68
+ export function readTextFile(file) {
69
+ return decodeTextBuffer(readFileSync(file))
70
+ }
71
+
72
+ /**
73
+ * Read and parse a JSON file, tolerating a Windows BOM.
74
+ *
75
+ * @param {string} file
76
+ * @returns {unknown}
77
+ */
78
+ export function readJsonFile(file) {
79
+ const text = readTextFile(file)
80
+ try {
81
+ return JSON.parse(text)
82
+ } catch (error) {
83
+ const wrapped = new SyntaxError(`invalid JSON in ${file}: ${error.message}`)
84
+ wrapped.name = 'JsonFileError'
85
+ wrapped.code = 'E_JSON_INVALID'
86
+ wrapped.cause = error
87
+ throw wrapped
88
+ }
89
+ }
90
+
91
+ /**
92
+ * Write UTF-8 text without a BOM, atomically and durably (0600 by default).
93
+ *
94
+ * @param {string} file
95
+ * @param {string} text
96
+ * @param {{ mode?: number, fsync?: boolean }} [options]
97
+ * @returns {number} bytes written
98
+ */
99
+ export function writeTextFile(file, text, { mode = 0o600, fsync = true } = {}) {
100
+ const data = Buffer.from(String(text), 'utf8')
101
+ atomicWriteFileSync(file, data, { mode, fsync })
102
+ return data.length
103
+ }
104
+
105
+ /**
106
+ * Serialise a value as JSON and write it as UTF-8 without a BOM (atomic, durable).
107
+ *
108
+ * @param {string} file
109
+ * @param {unknown} value
110
+ * @param {{ space?: number, sanitize?: boolean, mode?: number, fsync?: boolean }} [options]
111
+ * @returns {number} bytes written
112
+ */
113
+ export function writeJsonFile(file, value, { space = 0, sanitize = false, mode = 0o600, fsync = true } = {}) {
114
+ return writeTextFile(file, stringifyJson(value, { space, sanitize }), { mode, fsync })
115
+ }
116
+