dsh-ssh-hub 0.0.0-stage → 0.2.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 (133) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +271 -2
  3. package/cordis.patch.yml +16 -0
  4. package/icon.svg +3 -0
  5. package/lib/client.js +13975 -0
  6. package/lib/index.js +6908 -0
  7. package/lib/types/activity/history.d.ts +50 -0
  8. package/lib/types/alerting/notify.d.ts +89 -0
  9. package/lib/types/alerting/prompt-summary.d.ts +28 -0
  10. package/lib/types/alerting/rules.d.ts +135 -0
  11. package/lib/types/alerting/tools.d.ts +30 -0
  12. package/lib/types/audit/audit-log.d.ts +84 -0
  13. package/lib/types/audit/recorder.d.ts +50 -0
  14. package/lib/types/client/api.d.ts +222 -0
  15. package/lib/types/client/index.d.ts +45 -0
  16. package/lib/types/client/locales.d.ts +319 -0
  17. package/lib/types/client/native-panel.d.ts +70 -0
  18. package/lib/types/client/panel/ClusterTab.d.ts +7 -0
  19. package/lib/types/client/panel/DeployTab.d.ts +10 -0
  20. package/lib/types/client/panel/FleetTab.d.ts +10 -0
  21. package/lib/types/client/panel/HostFormDialog.d.ts +12 -0
  22. package/lib/types/client/panel/HostsTab.d.ts +25 -0
  23. package/lib/types/client/panel/LogsTab.d.ts +10 -0
  24. package/lib/types/client/panel/SshPanel.d.ts +14 -0
  25. package/lib/types/client/panel/TerminalTab.d.ts +27 -0
  26. package/lib/types/client/panel/TransferTab.d.ts +7 -0
  27. package/lib/types/client/panel/TunnelEditDialog.d.ts +15 -0
  28. package/lib/types/client/panel/TunnelsTab.d.ts +27 -0
  29. package/lib/types/client/panel/controller.d.ts +253 -0
  30. package/lib/types/client/panel/helpers.d.ts +45 -0
  31. package/lib/types/client/panel/tabs.d.ts +62 -0
  32. package/lib/types/client/panel/xterm.css.d.ts +2 -0
  33. package/lib/types/client/settings-binding.d.ts +71 -0
  34. package/lib/types/deploy/orchestrator.d.ts +158 -0
  35. package/lib/types/deploy/tools.d.ts +14 -0
  36. package/lib/types/dsh-home.d.ts +16 -0
  37. package/lib/types/engine/cluster.d.ts +19 -0
  38. package/lib/types/engine/connection-pool.d.ts +183 -0
  39. package/lib/types/engine/proxy-command.d.ts +36 -0
  40. package/lib/types/engine/pty.d.ts +32 -0
  41. package/lib/types/engine/sftp.d.ts +20 -0
  42. package/lib/types/engine/terminal-sessions.d.ts +67 -0
  43. package/lib/types/engine/tunnel-discovery.d.ts +89 -0
  44. package/lib/types/engine/tunnel-remarks.d.ts +49 -0
  45. package/lib/types/engine/tunnel.d.ts +76 -0
  46. package/lib/types/engine.d.ts +103 -0
  47. package/lib/types/http.d.ts +59 -0
  48. package/lib/types/index.d.ts +128 -0
  49. package/lib/types/inspect/checks.d.ts +118 -0
  50. package/lib/types/inspect/inspection.d.ts +111 -0
  51. package/lib/types/inspect/tools.d.ts +50 -0
  52. package/lib/types/logs/search.d.ts +131 -0
  53. package/lib/types/logs/tools.d.ts +6 -0
  54. package/lib/types/loopback.d.ts +64 -0
  55. package/lib/types/monitor/loop.d.ts +133 -0
  56. package/lib/types/monitor/metrics.d.ts +151 -0
  57. package/lib/types/mount-once.d.ts +55 -0
  58. package/lib/types/protocol.d.ts +524 -0
  59. package/lib/types/routes.d.ts +82 -0
  60. package/lib/types/security/known-hosts.d.ts +153 -0
  61. package/lib/types/security/master-secret.d.ts +157 -0
  62. package/lib/types/security/redact.d.ts +44 -0
  63. package/lib/types/security/secrets.d.ts +70 -0
  64. package/lib/types/ssh-config.d.ts +42 -0
  65. package/lib/types/store.d.ts +183 -0
  66. package/lib/types/tool-surface.d.ts +72 -0
  67. package/lib/types/tools.d.ts +56 -0
  68. package/locale/en.json +6 -0
  69. package/locale/zh.json +6 -0
  70. package/package.json +126 -6
  71. package/src/activity/history.ts +117 -0
  72. package/src/alerting/notify.ts +212 -0
  73. package/src/alerting/prompt-summary.ts +71 -0
  74. package/src/alerting/rules.ts +281 -0
  75. package/src/alerting/tools.ts +263 -0
  76. package/src/audit/audit-log.ts +199 -0
  77. package/src/audit/recorder.ts +73 -0
  78. package/src/client/api.ts +782 -0
  79. package/src/client/css-modules.d.ts +5 -0
  80. package/src/client/index.ts +150 -0
  81. package/src/client/locales.ts +654 -0
  82. package/src/client/native-panel.tsx +141 -0
  83. package/src/client/panel/ClusterTab.tsx +141 -0
  84. package/src/client/panel/DeployTab.tsx +314 -0
  85. package/src/client/panel/FleetTab.tsx +494 -0
  86. package/src/client/panel/HostFormDialog.tsx +289 -0
  87. package/src/client/panel/HostsTab.tsx +395 -0
  88. package/src/client/panel/LogsTab.tsx +208 -0
  89. package/src/client/panel/SshPanel.tsx +105 -0
  90. package/src/client/panel/TerminalTab.tsx +550 -0
  91. package/src/client/panel/TransferTab.tsx +238 -0
  92. package/src/client/panel/TunnelEditDialog.tsx +174 -0
  93. package/src/client/panel/TunnelsTab.tsx +328 -0
  94. package/src/client/panel/controller.ts +507 -0
  95. package/src/client/panel/helpers.ts +84 -0
  96. package/src/client/panel/panel.module.css +1734 -0
  97. package/src/client/panel/tabs.ts +52 -0
  98. package/src/client/panel/xterm.css.ts +2 -0
  99. package/src/client/settings-binding.ts +184 -0
  100. package/src/deploy/orchestrator.ts +326 -0
  101. package/src/deploy/tools.ts +225 -0
  102. package/src/dsh-home.ts +42 -0
  103. package/src/engine/cluster.ts +60 -0
  104. package/src/engine/connection-pool.ts +721 -0
  105. package/src/engine/proxy-command.ts +248 -0
  106. package/src/engine/pty.ts +78 -0
  107. package/src/engine/sftp.ts +229 -0
  108. package/src/engine/terminal-sessions.ts +280 -0
  109. package/src/engine/tunnel-discovery.ts +353 -0
  110. package/src/engine/tunnel-remarks.ts +120 -0
  111. package/src/engine/tunnel.ts +300 -0
  112. package/src/engine.ts +195 -0
  113. package/src/http.ts +127 -0
  114. package/src/index.ts +690 -0
  115. package/src/inspect/checks.ts +251 -0
  116. package/src/inspect/inspection.ts +321 -0
  117. package/src/inspect/tools.ts +366 -0
  118. package/src/logs/search.ts +251 -0
  119. package/src/logs/tools.ts +160 -0
  120. package/src/loopback.ts +119 -0
  121. package/src/monitor/loop.ts +265 -0
  122. package/src/monitor/metrics.ts +333 -0
  123. package/src/mount-once.ts +142 -0
  124. package/src/protocol.ts +534 -0
  125. package/src/routes.ts +998 -0
  126. package/src/security/known-hosts.ts +342 -0
  127. package/src/security/master-secret.ts +334 -0
  128. package/src/security/redact.ts +119 -0
  129. package/src/security/secrets.ts +152 -0
  130. package/src/ssh-config.ts +182 -0
  131. package/src/store.ts +757 -0
  132. package/src/tool-surface.ts +96 -0
  133. package/src/tools.ts +550 -0
@@ -0,0 +1,366 @@
1
+ /**
2
+ * Agent tools for the inspection layer.
3
+ *
4
+ * Two tools, deliberately split by intent:
5
+ * - `hub_inspect` runs a round of checks and returns the results
6
+ * - `hub_inspect_diff` returns what changed since the previous round
7
+ *
8
+ * The split matters: "check the fleet" and "what changed since I last
9
+ * looked" are different questions, and an agent that has to re-run the
10
+ * whole fleet to answer the second one pays for it in round trips.
11
+ */
12
+
13
+ import { defineTool } from '@deepseek-ai/dsh-tools'
14
+ import type { ContentBlock } from '@deepseek-ai/dsh-llm'
15
+ import type { SshEngine } from '../engine.ts'
16
+ import { BUILTIN_CHECKS, type Check, formatValue, type CheckResult } from './checks.ts'
17
+ import type { HostChange, Inspector } from './inspection.ts'
18
+
19
+ /** One text content block (the only render shape these tools emit). */
20
+ function text(value: string): ContentBlock[] {
21
+ return [{ type: 'text', text: value }]
22
+ }
23
+
24
+ /**
25
+ * Resolve the target hosts for an inspection.
26
+ *
27
+ * At least one selector is required, for the same reason `ssh_cluster`
28
+ * requires one: a fleet tool that silently inspects EVERY host when the
29
+ * selector is empty is a foot-gun, and an inspection is cheap but not free
30
+ * on 50 machines.
31
+ *
32
+ * @param engine - the SSH engine (the host list).
33
+ * @param aliases - explicit aliases.
34
+ * @param environment - an environment label (exact match).
35
+ * @param tags - tags that must ALL be present.
36
+ * @returns the selected aliases.
37
+ */
38
+ export function resolveTargets(
39
+ engine: SshEngine,
40
+ aliases?: string[],
41
+ environment?: string,
42
+ tags?: string[],
43
+ ): string[] {
44
+ const hasAlias = aliases !== undefined && aliases.length > 0
45
+ const hasEnvironment = environment !== undefined && environment !== ''
46
+ const hasTags = tags !== undefined && tags.length > 0
47
+ if (!hasAlias && !hasEnvironment && !hasTags) {
48
+ throw new Error('hub_inspect requires aliases, environment, or tags to limit the target set')
49
+ }
50
+ let hosts = engine.store.list()
51
+ if (hasAlias) {
52
+ const wanted = new Set(aliases as string[])
53
+ hosts = hosts.filter(host => wanted.has(host.alias))
54
+ }
55
+ if (hasEnvironment) {
56
+ hosts = hosts.filter(host => host.environment === environment)
57
+ }
58
+ if (hasTags) {
59
+ const wanted = tags as string[]
60
+ // ALL semantics, same as ssh_cluster: every listed tag must be present.
61
+ hosts = hosts.filter(host => wanted.every(tag => host.tags.includes(tag)))
62
+ }
63
+ return hosts.map(host => host.alias)
64
+ }
65
+
66
+ /** The check catalogue as the agent sees it. */
67
+ function renderCatalogue(): string {
68
+ const rows = BUILTIN_CHECKS.map(check => {
69
+ const threshold = check.threshold === undefined ? '-' : `${check.direction} ${check.threshold}${check.unit ?? ''}`
70
+ return `${check.id} | ${check.title} | ${threshold}`
71
+ })
72
+ return ['check | title | 触发条件', '--- | --- | ---', ...rows].join('\n')
73
+ }
74
+
75
+ /** One result line. */
76
+ function renderResult(check: Check, result: CheckResult): string {
77
+ const state = result.error !== undefined ? `失败(${result.error})` : result.breached ? '超限' : '正常'
78
+ return `${result.alias} | ${check.title} | ${formatValue(check, result.value)} | ${state}`
79
+ }
80
+
81
+ /** One change line. */
82
+ function renderChange(change: HostChange): string {
83
+ const transition = change.stateChange === 'new-breach'
84
+ ? ' → 新增超限'
85
+ : change.stateChange === 'recovered'
86
+ ? ' → 已恢复'
87
+ : ''
88
+ const before = change.before === undefined ? '(新增)' : change.before
89
+ return `${change.alias} | ${change.title} | ${before} → ${change.after}${transition}`
90
+ }
91
+
92
+ /** The inspection tool: run a round of checks. */
93
+ export function hubInspectTool(engine: SshEngine, inspector: Inspector) {
94
+ return defineTool({
95
+ name: 'hub_inspect',
96
+ description: 'Run the built-in fleet inspection checks (disk usage, load, memory, inodes, uptime, sshd, failed systemd units, kernel) across selected SSH hosts. Returns each host\'s value and whether it breaches its threshold, and retains the round so the next call can show what changed. Use ssh_exec for a one-off command; use hub_inspect for a repeatable fleet health check.',
97
+ parameters: {
98
+ aliases: { type: 'array', items: { type: 'string' }, description: 'Host aliases to inspect. Optional when environment or tags is given.' },
99
+ environment: { type: 'string', description: 'Inspect only hosts with this environment label (exact match).' },
100
+ tags: { type: 'array', items: { type: 'string' }, description: 'Inspect only hosts carrying ALL of these tags.' },
101
+ checks: { type: 'array', items: { type: 'string' }, description: 'Which checks to run (default: all). Call hub_inspect_catalog for the list.' },
102
+ timeoutMs: { type: 'integer', description: 'Per-command timeout in milliseconds (default 30000).' },
103
+ },
104
+ output: {
105
+ schema: {
106
+ type: 'object',
107
+ additionalProperties: false,
108
+ properties: {
109
+ ok: { type: 'boolean', required: true },
110
+ targets: { type: 'array', items: { type: 'string' } },
111
+ results: {
112
+ type: 'array',
113
+ items: {
114
+ type: 'object',
115
+ additionalProperties: false,
116
+ properties: {
117
+ alias: { type: 'string', required: true },
118
+ checkId: { type: 'string', required: true },
119
+ title: { type: 'string', required: true },
120
+ value: { type: 'string', required: true },
121
+ breached: { type: 'boolean', required: true },
122
+ error: { type: 'string' },
123
+ },
124
+ },
125
+ },
126
+ breaches: { type: 'integer' },
127
+ durationMs: { type: 'integer' },
128
+ error: { type: 'string' },
129
+ },
130
+ },
131
+ render: (_args, value: {
132
+ ok: boolean
133
+ targets?: string[]
134
+ results?: Array<{ alias: string; checkId: string; title: string; value: string; breached: boolean; error?: string }>
135
+ breaches?: number
136
+ durationMs?: number
137
+ error?: string
138
+ }) => {
139
+ if (value.error !== undefined) return text(`inspection failed: ${value.error}`)
140
+ if (value.results === undefined) return text('no results')
141
+ const breached = value.results.filter(result => result.breached)
142
+ const lines = [
143
+ `巡检 ${value.targets?.length ?? 0} 台主机,${value.results.length} 项检查,耗时 ${value.durationMs ?? 0}ms`,
144
+ `超限 ${value.breaches ?? breached.length} 项`,
145
+ '',
146
+ ...breached.map(result => `${result.alias} | ${result.title} | ${result.value} | 超限`),
147
+ ]
148
+ return text(lines.join('\n'))
149
+ },
150
+ },
151
+ async execute(args) {
152
+ const aliases = toStringArray(args.aliases)
153
+ const tags = toStringArray(args.tags)
154
+ const checks = toStringArray(args.checks)
155
+ const targets = resolveTargets(engine, aliases, args.environment, tags)
156
+ if (targets.length === 0) {
157
+ return { ok: true, targets: [], results: [], breaches: 0, durationMs: 0 }
158
+ }
159
+ const round = await inspector.run(engine, targets, checks, args.timeoutMs ?? 30_000)
160
+ const results = round.results.map(result => {
161
+ const check = BUILTIN_CHECKS.find(candidate => candidate.id === result.checkId)
162
+ return {
163
+ alias: result.alias,
164
+ checkId: result.checkId,
165
+ title: check?.title ?? result.checkId,
166
+ value: formatValue(check ?? fallbackCheck(result.checkId), result.value),
167
+ breached: result.breached,
168
+ ...(result.error !== undefined ? { error: result.error } : {}),
169
+ }
170
+ })
171
+ return {
172
+ ok: true,
173
+ targets: round.targets,
174
+ results,
175
+ breaches: results.filter(result => result.breached).length,
176
+ durationMs: round.durationMs,
177
+ }
178
+ },
179
+ })
180
+ }
181
+
182
+ /** The catalogue tool: list the available checks. */
183
+ export function hubInspectCatalogTool() {
184
+ return defineTool({
185
+ name: 'hub_inspect_catalog',
186
+ description: 'List the built-in fleet inspection checks with their ids, titles and breach thresholds. Use the ids with hub_inspect to run a subset.',
187
+ parameters: {},
188
+ output: {
189
+ schema: {
190
+ type: 'object',
191
+ additionalProperties: false,
192
+ properties: {
193
+ checks: {
194
+ type: 'array',
195
+ items: {
196
+ type: 'object',
197
+ additionalProperties: false,
198
+ properties: {
199
+ id: { type: 'string', required: true },
200
+ title: { type: 'string', required: true },
201
+ threshold: { type: 'string', required: true },
202
+ },
203
+ },
204
+ required: true,
205
+ },
206
+ },
207
+ },
208
+ render: (_args, value: { checks: Array<{ id: string; title: string; threshold: string }> }) => text(renderCatalogue()),
209
+ },
210
+ async execute() {
211
+ return {
212
+ checks: BUILTIN_CHECKS.map(check => ({
213
+ id: check.id,
214
+ title: check.title,
215
+ threshold: check.threshold === undefined
216
+ ? '-'
217
+ : `${check.direction} ${check.threshold}${check.unit ?? ''}`,
218
+ })),
219
+ }
220
+ },
221
+ })
222
+ }
223
+
224
+ /** The diff tool: what changed since the previous round. */
225
+ export function hubInspectDiffTool(inspector: Inspector) {
226
+ return defineTool({
227
+ name: 'hub_inspect_diff',
228
+ description: 'Show what changed in the fleet inspection results between the two most recent rounds (values that moved, new breaches, recoveries). Does not run any command on the hosts — it reads the retained history. Use hub_inspect first if no round has been run yet.',
229
+ parameters: {},
230
+ output: {
231
+ schema: {
232
+ type: 'object',
233
+ additionalProperties: false,
234
+ properties: {
235
+ ok: { type: 'boolean', required: true },
236
+ changes: {
237
+ type: 'array',
238
+ items: {
239
+ type: 'object',
240
+ additionalProperties: false,
241
+ properties: {
242
+ alias: { type: 'string', required: true },
243
+ checkId: { type: 'string', required: true },
244
+ title: { type: 'string', required: true },
245
+ before: { type: 'string' },
246
+ after: { type: 'string', required: true },
247
+ stateChange: { type: 'string', enum: ['new-breach', 'recovered'] },
248
+ },
249
+ },
250
+ required: true,
251
+ },
252
+ rounds: { type: 'integer' },
253
+ },
254
+ },
255
+ render: (_args, value: { ok: boolean; changes: HostChange[]; rounds?: number }) => {
256
+ if (value.changes.length === 0) return text('与上一轮相比没有变化')
257
+ const lines = [`与上一轮相比有 ${value.changes.length} 处变化:`, '', ...value.changes.map(renderChange)]
258
+ return text(lines.join('\n'))
259
+ },
260
+ },
261
+ async execute() {
262
+ const rounds = inspector.read(2)
263
+ return { ok: true, changes: inspector.diff(), rounds: rounds.length }
264
+ },
265
+ })
266
+ }
267
+
268
+ /**
269
+ * The monitoring-loop tool: is the fleet being watched, and what did the
270
+ * last round see?
271
+ *
272
+ * This is separate from `hub_inspect` on purpose. `hub_inspect` *runs* a
273
+ * round; this reports on the loop that runs rounds on its own. An agent
274
+ * asked "is the fleet being monitored?" must not have to run a round to
275
+ * answer, because running a round changes the thing being asked about.
276
+ *
277
+ * @param monitor - the loop (absent when the plugin mounted without one).
278
+ * @param store - the host store, for the configured target count.
279
+ * @returns the tool definition.
280
+ */
281
+ export function hubMonitorTool(monitor: { status(): Record<string, unknown> } | undefined) {
282
+ return defineTool({
283
+ name: 'hub_monitor',
284
+ description: 'Report whether the fleet monitoring loop is armed: its interval, how many hosts it watches, when the last round ran and when the next one will. An unarmed monitor means an empty alert list means nothing - use this before concluding the fleet is healthy. Pressing Check now in the panel runs the same round this loop runs.',
285
+ parameters: {},
286
+ output: {
287
+ schema: {
288
+ type: 'object',
289
+ properties: {
290
+ mounted: { type: 'boolean', required: true },
291
+ running: { type: 'boolean', required: true },
292
+ summary: { type: 'string', required: true },
293
+ },
294
+ additionalProperties: false,
295
+ },
296
+ render: (_args, value: { mounted: boolean; running: boolean; summary: string }) =>
297
+ text(value.summary),
298
+ },
299
+ async execute() {
300
+ if (monitor === undefined) {
301
+ return {
302
+ mounted: false,
303
+ running: false,
304
+ summary: '监控循环未挂载(插件可能以只读方式运行)。',
305
+ }
306
+ }
307
+ const status = monitor.status()
308
+ const running = status['running'] === true
309
+ const lines: string[] = [running ? '监控已启动' : '监控未启动']
310
+ if (running) {
311
+ const intervalMs = typeof status['intervalMs'] === 'number' ? status['intervalMs'] : 0
312
+ const hosts = typeof status['hosts'] === 'number' ? status['hosts'] : 0
313
+ lines.push(` 间隔 ${Math.round(intervalMs / 1000)}s,覆盖 ${hosts} 台主机`)
314
+ const last = status['lastTick']
315
+ if (typeof last === 'object' && last !== null) {
316
+ const tick = last as Record<string, unknown>
317
+ if (tick['ran'] === true) {
318
+ const at = typeof tick['at'] === 'number' ? new Date(tick['at']).toISOString() : '—'
319
+ lines.push(` 上一轮:${at},超限 ${String(tick['breaches'] ?? 0)} 项,探针失联 ${String(tick['blind'] ?? 0)} 项`)
320
+ } else {
321
+ lines.push(` 上一轮跳过:${String(tick['skippedBecause'] ?? '原因未知')}`)
322
+ }
323
+ }
324
+ const next = status['nextTickAt']
325
+ if (typeof next === 'number') {
326
+ lines.push(` 下一轮:${new Date(next).toISOString()}`)
327
+ }
328
+ } else {
329
+ // The distinction matters: a stopped loop and a healthy fleet both
330
+ // produce an empty alert list, and only one of them is good news.
331
+ lines.push(' 告警列表为空不能说明机群健康——没有任何东西在检查它们。')
332
+ lines.push(' 在设置里打开 monitorEnabled,或调用 hub_inspect 手动跑一轮。')
333
+ }
334
+ return { mounted: true, running, summary: lines.join('\n') }
335
+ },
336
+ })
337
+ }
338
+
339
+ /** A stand-in check for a stored result whose check no longer exists. */
340
+ function fallbackCheck(checkId: string): Check {
341
+ return {
342
+ id: checkId,
343
+ title: checkId,
344
+ kind: 'text',
345
+ direction: 'above',
346
+ command: '',
347
+ parse: () => null,
348
+ }
349
+ }
350
+
351
+ /**
352
+ * Narrow a tool argument to a string array.
353
+ *
354
+ * The tool parameter schema types arrays as JSON values, so the value
355
+ * arrives as `JsonValue | undefined`. A malformed value is dropped rather
356
+ * than passed on as-is: a selector that is not a list of strings must not
357
+ * silently select the whole fleet.
358
+ *
359
+ * @param value - the raw argument.
360
+ * @returns the strings, or undefined when the value is absent or unusable.
361
+ */
362
+ function toStringArray(value: unknown): string[] | undefined {
363
+ if (!Array.isArray(value)) return undefined
364
+ const strings = value.filter((item): item is string => typeof item === 'string' && item.trim() !== '')
365
+ return strings.length === 0 ? undefined : strings
366
+ }
@@ -0,0 +1,251 @@
1
+ /**
2
+ * Cross-host log search.
3
+ *
4
+ * The agentless way to search logs on 50 Linux machines: run a read-only
5
+ * grep over the log files on each host and aggregate the matches. No agent
6
+ * is installed on the remote side, nothing is written, and the whole thing
7
+ * is one SSH round trip per host.
8
+ *
9
+ * Two sources are supported, because a Linux fleet has both:
10
+ * - `journalctl` for the systemd journal
11
+ * - plain files under a log directory (grep over a file set)
12
+ *
13
+ * The search is BOUNDED on purpose: a grep across a fleet can return
14
+ * megabytes, which would flood the model's context. Per-host match counts
15
+ * and a global match cap keep the result readable, and the truncation is
16
+ * reported rather than hidden.
17
+ */
18
+
19
+ import type { SshEngine } from '../engine.ts'
20
+
21
+ /** Where to search. */
22
+ export type LogSource =
23
+ /** The systemd journal. */
24
+ | 'journal'
25
+ /** A set of log files under a directory. */
26
+ | 'files'
27
+
28
+ /** A log search request. */
29
+ export interface LogSearchRequest {
30
+ /** The search source. */
31
+ source: LogSource
32
+ /** The pattern to search for (a grep pattern or a journalctl match). */
33
+ pattern: string
34
+ /** The log directory, when the source is 'files'. */
35
+ directory?: string
36
+ /** How many lines to keep per host. */
37
+ maxLinesPerHost?: number
38
+ /** The systemd unit to filter on, when the source is 'journal'. */
39
+ unit?: string
40
+ /** The time window start (epoch seconds), when the source is 'journal'. */
41
+ since?: number
42
+ /** How long the command may take per host. */
43
+ timeoutMs?: number
44
+ /** How many hosts to search at once. */
45
+ maxWorkers?: number
46
+ }
47
+
48
+ /** One host's search outcome. */
49
+ export interface LogHostResult {
50
+ alias: string
51
+ ok: boolean
52
+ /** The matching lines (bounded). */
53
+ lines: string[]
54
+ /** How many matches the host reported in total. */
55
+ totalMatches?: number
56
+ /** Whether the output was truncated. */
57
+ truncated?: boolean
58
+ /** The error, when the search failed. */
59
+ error?: string
60
+ /** How long the search took on this host. */
61
+ durationMs?: number
62
+ }
63
+
64
+ /** The outcome of a fleet-wide search. */
65
+ export interface LogSearchResult {
66
+ ok: boolean
67
+ /** The hosts that were searched. */
68
+ targets: string[]
69
+ /** The per-host outcomes. */
70
+ results: LogHostResult[]
71
+ /** The total number of matching lines returned. */
72
+ totalLines: number
73
+ /** Whether any host's output was truncated. */
74
+ truncated: boolean
75
+ /** How long the whole search took. */
76
+ durationMs: number
77
+ /** The error, when the search could not run at all. */
78
+ error?: string
79
+ }
80
+
81
+ /**
82
+ * Build the remote command for one search.
83
+ *
84
+ * The pattern is passed as a shell argument, quoted so a pattern with
85
+ * spaces or quotes does not break the command. The pattern itself is a
86
+ * grep pattern — that is the operator's choice, and it runs on their own
87
+ * hosts.
88
+ *
89
+ * @param request - the search request.
90
+ * @returns the command to run on the remote host.
91
+ */
92
+ export function buildSearchCommand(request: LogSearchRequest): string {
93
+ const pattern = shellQuote(request.pattern)
94
+ const maxLines = request.maxLinesPerHost ?? 50
95
+ if (request.source === 'journal') {
96
+ const filters: string[] = []
97
+ if (request.unit !== undefined && request.unit !== '') {
98
+ filters.push(`--unit ${shellQuote(request.unit)}`)
99
+ }
100
+ if (request.since !== undefined) {
101
+ filters.push(`--since ${shellQuote(formatSince(request.since))}`)
102
+ }
103
+ const filterText = filters.length > 0 ? ` ${filters.join(' ')}` : ''
104
+ // The total count comes from a separate wc pass so the caller can tell
105
+ // "50 matches, all shown" from "5000 matches, 50 shown".
106
+ return `journalctl ${filterText} --no-pager --no-hostname 2>/dev/null | grep -F -- ${pattern} | head -n ${maxLines}; ` +
107
+ `journalctl ${filterText} --no-pager --no-hostname 2>/dev/null | grep -c -F -- ${pattern}`
108
+ }
109
+ const directory = shellQuote(request.directory ?? '/var/log')
110
+ return `grep -R -F --include='*.log' ${pattern} ${directory} 2>/dev/null | head -n ${maxLines}; ` +
111
+ `grep -R -F --include='*.log' -c ${pattern} ${directory} 2>/dev/null | awk -F: '{s+=$NF} END {print s+0}'`
112
+ }
113
+
114
+ /**
115
+ * Quote a value for a POSIX shell.
116
+ *
117
+ * @param value - the value to quote.
118
+ * @returns the quoted value.
119
+ */
120
+ export function shellQuote(value: string): string {
121
+ return `'${value.replaceAll("'", `'\\''`)}'`
122
+ }
123
+
124
+ /**
125
+ * Format a "since" timestamp for journalctl.
126
+ *
127
+ * @param epochSeconds - the timestamp in seconds.
128
+ * @returns the journalctl argument.
129
+ */
130
+ export function formatSince(epochSeconds: number): string {
131
+ // journalctl accepts an absolute ISO timestamp or a relative one. The
132
+ // absolute form is unambiguous across timezones.
133
+ return new Date(epochSeconds * 1000).toISOString()
134
+ }
135
+
136
+ /**
137
+ * Search the logs on many hosts.
138
+ *
139
+ * @param engine - the SSH engine.
140
+ * @param request - the search request.
141
+ * @param targets - the host aliases.
142
+ * @returns the fleet-wide outcome.
143
+ */
144
+ export async function searchLogs(
145
+ engine: SshEngine,
146
+ request: LogSearchRequest,
147
+ targets: string[],
148
+ ): Promise<LogSearchResult> {
149
+ const startedAt = Date.now()
150
+ const command = buildSearchCommand(request)
151
+ const timeoutMs = request.timeoutMs ?? 30_000
152
+ const maxWorkers = Math.max(1, request.maxWorkers ?? 8)
153
+
154
+ const results: LogHostResult[] = []
155
+ // A bounded worker pool: the engine's pool caps the connections, but the
156
+ // fan-out itself is limited so 50 hosts do not all connect at once.
157
+ let cursor = 0
158
+ const workers = Array.from({ length: Math.min(maxWorkers, targets.length) }, async () => {
159
+ while (cursor < targets.length) {
160
+ const index = cursor
161
+ cursor += 1
162
+ const alias = targets[index] as string
163
+ const hostStarted = Date.now()
164
+ try {
165
+ const execResult = await engine.exec(alias, command, timeoutMs)
166
+ const parsed = parseSearchOutput(execResult.stdout, request.maxLinesPerHost ?? 50)
167
+ results.push({
168
+ alias,
169
+ ok: execResult.success,
170
+ lines: parsed.lines,
171
+ totalMatches: parsed.total,
172
+ ...(parsed.truncated ? { truncated: true } : {}),
173
+ ...(execResult.error !== undefined ? { error: execResult.error } : {}),
174
+ durationMs: Date.now() - hostStarted,
175
+ })
176
+ } catch (error) {
177
+ results.push({
178
+ alias,
179
+ ok: false,
180
+ lines: [],
181
+ error: error instanceof Error ? error.message : String(error),
182
+ durationMs: Date.now() - hostStarted,
183
+ })
184
+ }
185
+ }
186
+ })
187
+ await Promise.all(workers)
188
+
189
+ // Keep the results in the caller's target order, not in completion order.
190
+ const order = new Map(targets.map((alias, index) => [alias, index]))
191
+ results.sort((left, right) => (order.get(left.alias) ?? 0) - (order.get(right.alias) ?? 0))
192
+
193
+ return {
194
+ ok: true,
195
+ targets: [...targets],
196
+ results,
197
+ totalLines: results.reduce((sum, result) => sum + result.lines.length, 0),
198
+ truncated: results.some(result => result.truncated === true),
199
+ durationMs: Date.now() - startedAt,
200
+ }
201
+ }
202
+
203
+ /**
204
+ * Parse the combined output of a search command.
205
+ *
206
+ * The command prints the matched lines, then the total count on the last
207
+ * line. The count line is numeric only, so it is unambiguous.
208
+ *
209
+ * @param stdout - the command output.
210
+ * @param maxLines - the per-host cap.
211
+ * @returns the lines and the total count.
212
+ */
213
+ export function parseSearchOutput(stdout: string, maxLines: number): { lines: string[]; total: number; truncated: boolean } {
214
+ const all = stdout.split('\n').filter(line => line.trim() !== '')
215
+ if (all.length === 0) return { lines: [], total: 0, truncated: false }
216
+ const last = all[all.length - 1] as string
217
+ const hasCount = /^\d+$/.test(last.trim())
218
+ const count = hasCount ? Number.parseInt(last.trim(), 10) : 0
219
+ const body = hasCount ? all.slice(0, -1) : all
220
+ return {
221
+ lines: body,
222
+ total: count,
223
+ truncated: count > body.length || body.length >= maxLines,
224
+ }
225
+ }
226
+
227
+ /**
228
+ * A human-readable rendering of a search outcome.
229
+ *
230
+ * @param result - the search outcome.
231
+ * @returns the report text.
232
+ */
233
+ export function renderLogSearch(result: LogSearchResult): string {
234
+ if (result.error !== undefined) return `日志检索失败:${result.error}`
235
+ const withMatches = result.results.filter(host => host.lines.length > 0)
236
+ const lines: string[] = [
237
+ `跨机日志检索:${result.targets.length} 台主机,命中 ${result.totalLines} 行,耗时 ${result.durationMs}ms`,
238
+ ]
239
+ if (result.truncated) {
240
+ lines.push('(部分主机的输出被截断,命中数可能高于显示行数)')
241
+ }
242
+ for (const host of withMatches) {
243
+ lines.push('', `── ${host.alias}(共 ${host.totalMatches ?? host.lines.length} 条命中)`)
244
+ for (const line of host.lines) lines.push(line)
245
+ }
246
+ const failed = result.results.filter(host => !host.ok)
247
+ if (failed.length > 0) {
248
+ lines.push('', `检索失败:${failed.map(host => `${host.alias}(${host.error ?? '未知错误'})`).join('、')}`)
249
+ }
250
+ return lines.join('\n')
251
+ }