@huaqiu/dsh-plugin-log 0.6.22 → 0.6.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/index.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * `@huaqiu/dsh-plugin-log` — one server-side log for every Huaqiu DSH plugin.
2
+ * `@huaqiu/dsh-plugin-log` — one shared, per-DSH-process log for every Huaqiu
3
+ * DSH plugin.
3
4
  *
4
5
  * ## Why this exists
5
6
  *
@@ -7,75 +8,85 @@
7
8
  * browser half logged to `console.*`, and the node half — the half that
8
9
  * actually owns credentials, HTTP routes and agent tools — logged nothing at
9
10
  * all outside the DSH process's stdout, which HQ Edge only captures as an
10
- * opaque text blob. When a `deepseek-harness` upgrade broke credential
11
- * propagation, the only way to see what the node half resolved was to add
12
- * temporary prints and re-run.
11
+ * opaque text blob.
13
12
  *
14
- * This package gives every plugin one shared, file-backed, cross-platform log
15
- * inside the current HQ Edge log tree:
13
+ * ## What changed (docs/tasks/dsh-plugin-log-isolation.md)
16
14
  *
17
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log (current)
18
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log (previous, after rotation)
15
+ * The package is shared by every plugin, but the logging RESOURCE belongs to
16
+ * the DSH process that loads them. So:
19
17
  *
20
- * ## HQ Edge home resolution
18
+ * - one DSH process = one log directory = one active file;
19
+ * - the directory is `<dsh-root>/<dsh_instance_id>/`, where `dsh-root` is the
20
+ * parent HQ Edge instance's `dsh/` directory;
21
+ * - `dsh_instance_id` is generated per DSH LAUNCH — a restart produces a new
22
+ * directory, a plugin reload does not;
23
+ * - plugins never configure a destination or a rotation; they only name
24
+ * themselves (`pluginId`) and get a namespaced logger;
25
+ * - the DSH process owns rotation, compression, retention and shutdown.
21
26
  *
22
- * The directory comes from the inlined `@hqedge/paths` resolution
23
- * (`src/paths.ts`): the same root every HQ Edge runtime uses, so plugin logs
24
- * land inside the current HQ Edge log tree:
27
+ * Layout:
25
28
  *
26
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log (current)
27
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log (previous, after rotation)
29
+ * <HQ_EDGE_HOME>/logs/instances/<edge-instance-id>/dsh/
30
+ * <dsh-instance-id>/
31
+ * instance.json ← identity of this DSH process
32
+ * owner.lock ← diagnostic only; existence ≠ ownership
33
+ * dsh.2026-11-11.log ← active log (owned by this process)
34
+ * dsh.2026-11-11.log.gz ← published archive
28
35
  *
29
- * Resolution honours the same overrides as the rest of HQ Edge:
36
+ * ## Guarantees
30
37
  *
31
- * explicit `configure({ dir })` > $DSH_PLUGIN_LOG_DIR > $HQ_EDGE_LOG_DIR / $HQ_EDGE_HOME
32
- *
33
- * HQ Edge runs DSH with `HQ_EDGE_HOME` set to its own per-user data directory,
34
- * so plugin logs live next to the rest of that installation's state and never
35
- * in the user's default home.
36
- *
37
- * ## Cross-platform notes
38
- *
39
- * - Pure `node:fs` / `node:os` / `node:path` — no native modules, no shelling
40
- * out, nothing that differs between macOS, Linux and Windows but the path
41
- * separators (handled by `node:path`).
42
- * - Rotation uses unlink-then-rename, because Windows cannot rename over an
43
- * existing file.
44
- * - File names never embed `:` or other Windows-illegal characters.
45
- * - If the log directory cannot be created (read-only install, locked-down
46
- * profile) we fall back to the OS temp dir, and if that also fails we keep
47
- * logging to the console. A logging failure must never take a plugin down.
48
- *
49
- * ## Safety
50
- *
51
- * - Every field passes through `redact()`: credential-shaped keys and values
52
- * are replaced with `[redacted]`, so the log is safe to share.
53
- * - `getLogger()` never throws. Neither does any log call.
38
+ * - `getLogger()` and every log call are synchronous, never throw, and never
39
+ * fail plugin business logic because a destination failed;
40
+ * - initialization is idempotent across duplicated package copies (the state
41
+ * lives in a process-wide `globalThis` registry);
42
+ * - a plugin's `fields` can never override identity or level fields;
43
+ * - plugin unload/reload never creates a second transport and never closes
44
+ * the shared one — only DSH shutdown flushes and closes.
54
45
  */
55
46
 
56
- import {
57
- mkdirSync,
58
- renameSync,
59
- rmSync,
60
- statSync,
61
- } from 'node:fs'
62
- import { appendFile } from 'node:fs/promises'
63
- import { tmpdir } from 'node:os'
64
- import { join } from 'node:path'
65
- import { getHqEdgeHome, getLogDir } from './paths.js'
47
+ import { existsSync, mkdirSync } from 'node:fs'
66
48
 
67
49
  import { isEnabled, parseLevel, type LogLevel } from './levels.js'
68
50
  import { redact } from './redact.js'
51
+ import { getDshLogRoot, getLogBaseDir, getHqEdgeHome } from './paths.js'
52
+ import { RESERVED_FIELDS } from './fields.js'
53
+ import {
54
+ awaitRuntimeReady,
55
+ enqueueRecord,
56
+ flushRuntime,
57
+ getDshIdentity,
58
+ getRuntimeSnapshot,
59
+ initializeDshRuntime,
60
+ resetRuntime,
61
+ runRuntimeMaintenance,
62
+ shutdownRuntime,
63
+ type DshLogRuntimeConfig,
64
+ type DshRuntimeSnapshot,
65
+ } from './runtime.js'
66
+ import type { DshRotationFaults, LoggingHealth, LoggingHealthState } from './rotation.js'
69
67
 
70
68
  export type { LogLevel } from './levels.js'
71
69
  export { LOG_LEVELS, levelRank, parseLevel } from './levels.js'
72
70
  export { redact, REDACTED } from './redact.js'
71
+ export type { DshRotationConfig, DshRotationFaults, LoggingHealth, LoggingHealthState } from './rotation.js'
72
+ export { DSH_ROTATION, parseSize, todayString } from './rotation.js'
73
+ export type { DshInstanceMetadata, DshLogContext } from './identity.js'
74
+ export { INSTANCE_METADATA_FILENAME, OWNER_LOCK_FILENAME, RESERVED_FIELDS } from './identity.js'
75
+ export type { DshOwnershipHandle } from './ownership.js'
76
+ export { acquireDshOwnership, probeDshOwnership } from './ownership.js'
77
+ export type { DshMaintenanceOptions, DshMaintenanceReport, LegacyPluginLogReport } from './recovery.js'
78
+ export { cleanupExpiredDshInstances, recoverDshInstances, reportLegacyPluginLogs } from './recovery.js'
79
+ export type { HostLogSink } from './runtime.js'
80
+ export { installHostLogSink } from './runtime.js'
73
81
 
74
82
  /** Arbitrary structured context attached to a log record. */
75
83
  export type LogFields = Record<string, unknown>
76
84
 
77
85
  /** The logger surface every plugin codes against. */
78
86
  export interface PluginLogger {
87
+ /** Plugin that owns these records (`pluginId`, e.g. `dsh-auth`). */
88
+ readonly pluginId: string
89
+ /** @deprecated Legacy alias for `pluginId`; kept for existing call sites. */
79
90
  readonly component: string
80
91
  debug(message: string, fields?: LogFields): void
81
92
  info(message: string, fields?: LogFields): void
@@ -86,94 +97,81 @@ export interface PluginLogger {
86
97
  }
87
98
 
88
99
  export interface LoggingOptions {
89
- /** Override the log directory (highest precedence, beats every env var). */
100
+ /**
101
+ * DSH log ROOT. The per-process instance directory is always appended, so a
102
+ * shared directory can never be written directly. Highest precedence, beats
103
+ * `$DSH_LOG_ROOT` and `$HQ_EDGE_INSTANCE_ID`.
104
+ */
90
105
  dir?: string
91
- /** Base file name inside the directory. Default `dsh-plugins.log`. */
92
- fileName?: string
106
+ /** Alias for {@link dir}, with a name that says what it is. */
107
+ dshLogRoot?: string
108
+ /** Test/host injection of `dsh_instance_id`. Production generates one. */
109
+ dshInstanceId?: string
93
110
  /** Minimum file level. Default from `$DSH_PLUGIN_LOG_LEVEL`, else `info`. */
94
111
  level?: LogLevel
95
112
  /**
96
- * Minimum level mirrored to the console. HQ Edge captures DSH's stdout, so
113
+ * Minimum level mirrored to DSH's stdout. HQ Edge captures that stream, so
97
114
  * this is how a plugin surfaces a problem without anyone opening a file.
98
115
  * Default from `$DSH_PLUGIN_LOG_CONSOLE`, else `warn`.
99
116
  */
100
117
  consoleLevel?: LogLevel | 'off'
101
- /** Rotate once the current file exceeds this many bytes. Default 5 MiB. */
118
+ /** Rotate once the active file exceeds this size. Default 10 MiB. */
119
+ maxSize?: string
120
+ /** @deprecated Use {@link maxSize}. Converted to a byte count. */
102
121
  maxBytes?: number
103
- /** Number of files kept (current + rotated). Default 4. */
122
+ /** @deprecated Retained for source compatibility; superseded by date+size rotation. */
104
123
  maxFiles?: number
124
+ /** Days of compressed history to keep. Default 14. */
125
+ retentionDays?: number
126
+ /** Total bytes this instance directory may consume. Default 256 MiB. */
127
+ maxStorageBytes?: number
128
+ /** Gzip rotated files. Default true. */
129
+ compress?: boolean
130
+ /** Test-only fault injection for rotation. */
131
+ faults?: DshRotationFaults
132
+ /** Test-only: bypass the OS ownership lock. */
133
+ skipOwnership?: boolean
134
+ /** Clock override (tests). */
135
+ now?: () => Date
136
+ /** Internal diagnostic sink (tests). */
137
+ onDiagnostic?: (record: Record<string, unknown>) => void
105
138
  }
106
139
 
107
- const DEFAULT_FILE_NAME = 'dsh-plugins.log'
108
- const DEFAULT_MAX_BYTES = 5 * 1024 * 1024
109
- const DEFAULT_MAX_FILES = 4
110
140
  const DEFAULT_LEVEL: LogLevel = 'info'
111
141
  const DEFAULT_CONSOLE_LEVEL: LogLevel = 'warn'
112
142
 
113
143
  // ── configuration ───────────────────────────────────────────────────────────
114
144
 
115
145
  interface ResolvedConfig {
116
- dir: string
117
- fileName: string
146
+ dshLogRoot: string | undefined
147
+ dshInstanceId: string | undefined
118
148
  level: LogLevel
119
149
  consoleLevel: LogLevel | 'off'
120
- maxBytes: number
121
- maxFiles: number
122
- }
123
-
124
- /**
125
- * Process-wide logger state, held on `globalThis`.
126
- *
127
- * Plugins are built independently, so each one gets its OWN bundled copy of
128
- * this module. Without a shared home, "one unified log" would degrade into one
129
- * sink (and one rotation counter) per plugin. Keying the state off a
130
- * `Symbol.for` on `globalThis` makes every copy — bundled, external, or
131
- * duplicated across installs — cooperate inside the same DSH process.
132
- */
133
- const STATE_KEY = Symbol.for('@huaqiu/dsh-plugin-log/state')
134
-
135
- interface LogState {
136
- override: Partial<LoggingOptions> | null
137
- resolved: ResolvedConfig | null
138
- sink: FileSink | null
139
- bootstrapped: boolean
140
- }
141
-
142
- function state(): LogState {
143
- const g = globalThis as Record<symbol, unknown>
144
- const existing = g[STATE_KEY] as LogState | undefined
145
- if (existing) return existing
146
- const fresh: LogState = { override: null, resolved: null, sink: null, bootstrapped: false }
147
- g[STATE_KEY] = fresh
148
- return fresh
150
+ maxSize: string
151
+ retentionDays: number
152
+ maxStorageBytes: number
153
+ compress: boolean
154
+ faults: DshRotationFaults | undefined
155
+ skipOwnership: boolean
156
+ now: (() => Date) | undefined
157
+ onDiagnostic: ((record: Record<string, unknown>) => void) | undefined
149
158
  }
150
159
 
151
- const getOverride = (): Partial<LoggingOptions> | null => state().override
152
- const setOverride = (value: Partial<LoggingOptions> | null): void => { state().override = value }
153
- const getSink = (): FileSink | null => state().sink
154
- const setSink = (value: FileSink | null): void => { state().sink = value }
155
-
160
+ let override: LoggingOptions | null = null
161
+ let resolved: ResolvedConfig | null = null
162
+ let bootstrapped = false
156
163
  /**
157
- * Programmatically configure logging. Call before the first `getLogger()`;
158
- * later calls take effect on the next `resetLogging()` (tests, host re-init).
164
+ * Pending boot-banner emission. `flushLogs()` must await it: the banner is
165
+ * written once the destination is decided, so without this barrier a flush
166
+ * could return before the banner (and any rotation it triggers) had landed.
159
167
  */
160
- export function configureLogging(options: LoggingOptions): void {
161
- setOverride({ ...(getOverride() ?? {}), ...options })
162
- state().resolved = null
163
- }
164
-
165
- /** Forget all configuration and cached loggers. Test/teardown helper. */
166
- export function resetLogging(): void {
167
- const s = state()
168
- s.override = null
169
- s.resolved = null
170
- s.sink = null
171
- s.bootstrapped = false
172
- }
168
+ let bootPromise: Promise<void> | null = null
173
169
 
174
170
  function env(name: string): string | undefined {
175
171
  const value = process.env[name]
176
- return value !== undefined && value.trim().length > 0 ? value.trim() : undefined
172
+ if (value === undefined) return undefined
173
+ const trimmed = value.trim()
174
+ return trimmed.length > 0 ? trimmed : undefined
177
175
  }
178
176
 
179
177
  function readInt(value: string | undefined, fallback: number): number {
@@ -182,176 +180,132 @@ function readInt(value: string | undefined, fallback: number): number {
182
180
  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
183
181
  }
184
182
 
185
- /**
186
- * Pick the log directory, honouring every override in precedence order.
187
- * Falls back to the OS temp directory when the DSH home is not writable — a
188
- * plugin that cannot log to its preferred location still logs somewhere.
189
- */
190
- function resolveLogDir(explicit?: string): { dir: string; fallback: boolean } {
191
- const candidates: string[] = []
192
- if (explicit !== undefined && explicit.length > 0) candidates.push(explicit)
193
- const fromEnv = env('DSH_PLUGIN_LOG_DIR')
194
- if (fromEnv) candidates.push(fromEnv)
195
- // Inside the current HQ Edge log tree (honours $HQ_EDGE_HOME / $HQ_EDGE_LOG_DIR
196
- // through the inlined paths resolver), so plugin logs follow the host install.
197
- candidates.push(getLogDir('dsh-plugins'))
198
- candidates.push(join(tmpdir(), 'hq-dsh-plugins', 'logs'))
199
-
200
- for (let i = 0; i < candidates.length; i += 1) {
201
- const dir = candidates[i]
202
- if (!dir) continue
203
- try {
204
- mkdirSync(dir, { recursive: true })
205
- return { dir, fallback: i > 0 }
206
- } catch {
207
- /* read-only or locked-down — try the next candidate */
208
- }
209
- }
183
+ function readBool(value: string | undefined, fallback: boolean): boolean {
184
+ if (value === undefined) return fallback
185
+ const normalized = value.trim().toLowerCase()
186
+ if (['1', 'true', 'yes', 'on'].includes(normalized)) return true
187
+ if (['0', 'false', 'no', 'off'].includes(normalized)) return false
188
+ return fallback
189
+ }
210
190
 
211
- // Nothing is writable. Report the last candidate; the sink degrades to
212
- // console output rather than failing.
213
- const last = candidates[candidates.length - 1]
214
- return { dir: last ?? '.', fallback: true }
191
+ function consoleLevelFrom(raw: string | undefined, explicit?: LogLevel | 'off'): LogLevel | 'off' {
192
+ if (explicit === 'off') return 'off'
193
+ if (explicit !== undefined) return explicit
194
+ if (raw === 'off' || raw === 'none' || raw === '0') return 'off'
195
+ if (raw === 'all' || raw === '1' || raw === 'true') return 'debug'
196
+ return parseLevel(raw, DEFAULT_CONSOLE_LEVEL)
215
197
  }
216
198
 
217
199
  function currentConfig(): ResolvedConfig {
218
- const s = state()
219
- if (s.resolved) return s.resolved
220
- const o = s.override
221
- const { dir } = resolveLogDir(o?.dir)
222
- const consoleRaw = o?.consoleLevel ?? env('DSH_PLUGIN_LOG_CONSOLE')
223
- s.resolved = {
224
- dir,
225
- fileName: o?.fileName ?? env('DSH_PLUGIN_LOG_FILE') ?? DEFAULT_FILE_NAME,
226
- level: o?.level ?? parseLevel(env('DSH_PLUGIN_LOG_LEVEL'), DEFAULT_LEVEL),
227
- consoleLevel:
228
- o?.consoleLevel === 'off'
229
- ? 'off'
230
- : consoleRaw === 'off' || consoleRaw === 'none' || consoleRaw === '0'
231
- ? 'off'
232
- : consoleRaw === 'all' || consoleRaw === '1' || consoleRaw === 'true'
233
- ? 'debug'
234
- : parseLevel(consoleRaw, DEFAULT_CONSOLE_LEVEL),
235
- maxBytes: o?.maxBytes ?? readInt(env('DSH_PLUGIN_LOG_MAX_BYTES'), DEFAULT_MAX_BYTES),
236
- maxFiles: o?.maxFiles ?? readInt(env('DSH_PLUGIN_LOG_MAX_FILES'), DEFAULT_MAX_FILES),
200
+ if (resolved) return resolved
201
+ const o: LoggingOptions = override ?? {}
202
+ const rootFromOption = o.dshLogRoot ?? o.dir
203
+ const rootFromEnv = env('DSH_LOG_ROOT') ?? env('DSH_PLUGIN_LOG_DIR')
204
+ const maxSize =
205
+ o.maxSize ?? (o.maxBytes !== undefined ? `${Math.max(1, Math.floor(o.maxBytes / (1024 * 1024)))}m` : undefined)
206
+ resolved = {
207
+ dshLogRoot: rootFromOption ?? rootFromEnv,
208
+ dshInstanceId: o.dshInstanceId,
209
+ level: o.level ?? parseLevel(env('DSH_PLUGIN_LOG_LEVEL'), DEFAULT_LEVEL),
210
+ consoleLevel: consoleLevelFrom(env('DSH_PLUGIN_LOG_CONSOLE'), o.consoleLevel),
211
+ maxSize: maxSize ?? env('DSH_PLUGIN_LOG_MAX_BYTES_SIZE') ?? '10m',
212
+ retentionDays: o.retentionDays ?? readInt(env('DSH_PLUGIN_LOG_RETENTION_DAYS'), 14),
213
+ maxStorageBytes: o.maxStorageBytes ?? readInt(env('DSH_PLUGIN_LOG_MAX_STORAGE_BYTES'), 256 * 1024 * 1024),
214
+ compress: o.compress ?? readBool(env('DSH_PLUGIN_LOG_COMPRESS'), true),
215
+ faults: o.faults,
216
+ skipOwnership: o.skipOwnership === true,
217
+ now: o.now,
218
+ onDiagnostic: o.onDiagnostic,
237
219
  }
238
- return s.resolved
220
+ return resolved
239
221
  }
240
222
 
241
- /** Absolute path of the current log file, or `null` before first use. */
242
- export function logFilePath(): string | null {
243
- const s = getSink()
244
- return s ? s.path : null
245
- }
246
-
247
- /** Absolute directory plugin logs are written to. */
248
- export function logDir(): string {
249
- return currentConfig().dir
223
+ function runtimeConfig(cfg: ResolvedConfig): DshLogRuntimeConfig {
224
+ return {
225
+ dshLogRoot: cfg.dshLogRoot,
226
+ dshInstanceId: cfg.dshInstanceId,
227
+ rotation: {
228
+ frequency: 'daily',
229
+ maxSize: cfg.maxSize,
230
+ retentionDays: cfg.retentionDays,
231
+ maxStorageBytes: cfg.maxStorageBytes,
232
+ compress: cfg.compress,
233
+ },
234
+ faults: cfg.faults,
235
+ skipOwnership: cfg.skipOwnership,
236
+ now: cfg.now,
237
+ onDiagnostic: cfg.onDiagnostic,
238
+ }
250
239
  }
251
240
 
252
- // ── file sink ───────────────────────────────────────────────────────────────
253
-
254
241
  /**
255
- * Serialized appender with size-based rotation.
256
- *
257
- * Writes are chained on a single promise so concurrent log calls from different
258
- * plugins in the same process can never interleave or race the rotation.
242
+ * Programmatically configure logging. Call before the first `getLogger()`;
243
+ * once the destination is established a later call only takes effect after
244
+ * {@link shutdownLogging} + {@link resetLogging} (tests, host re-init).
259
245
  */
260
- class FileSink {
261
- readonly path: string
262
- private queue: Promise<void> = Promise.resolve()
263
- private bytes: number
264
-
265
- constructor(
266
- private readonly dir: string,
267
- private readonly fileName: string,
268
- private readonly maxBytes: number,
269
- private readonly maxFiles: number,
270
- ) {
271
- this.path = join(dir, fileName)
272
- this.bytes = this.currentSize()
273
- }
274
-
275
- private currentSize(): number {
276
- try {
277
- return statSync(this.path).size
278
- } catch {
279
- return 0
280
- }
281
- }
282
-
283
- /** Rotate when appending `next` bytes would exceed the cap. */
284
- private rotateIfNeeded(next: number): void {
285
- if (this.maxBytes <= 0) return
286
- if (this.bytes + next <= this.maxBytes) return
287
- try {
288
- // Shift: .2 -> .3, .1 -> .2, current -> .1 (oldest is dropped).
289
- for (let i = this.maxFiles - 1; i >= 1; i -= 1) {
290
- const from = i === 1 ? join(this.dir, this.fileName) : this.rotated(i - 1)
291
- const to = this.rotated(i)
292
- if (!exists(from)) continue
293
- // Windows cannot rename over an existing file — remove the target first.
294
- if (exists(to)) rmSync(to, { force: true })
295
- renameSync(from, to)
296
- }
297
- this.bytes = this.currentSize()
298
- } catch {
299
- // Rotation is best-effort: never lose the write because of it.
300
- }
246
+ export function configureLogging(options: LoggingOptions): void {
247
+ override = { ...(override ?? {}), ...options }
248
+ resolved = null
249
+ if (getDshIdentity() !== null) {
250
+ // The destination is already established. Say so in the current log
251
+ // instead of silently pretending the new configuration applies.
252
+ enqueueRecord(
253
+ serialize({
254
+ time: Date.now(),
255
+ ts: new Date().toISOString(),
256
+ level: 'warn',
257
+ msg: 'configureLogging called after logging started; restart required for it to take effect',
258
+ pluginId: 'dsh-plugin-log',
259
+ component: 'dsh-plugin-log',
260
+ pid: process.pid,
261
+ }),
262
+ )
301
263
  }
264
+ }
302
265
 
303
- private rotated(index: number): string {
304
- const dot = this.fileName.lastIndexOf('.')
305
- const stem = dot > 0 ? this.fileName.slice(0, dot) : this.fileName
306
- const ext = dot > 0 ? this.fileName.slice(dot) : ''
307
- return join(this.dir, `${stem}.${index}${ext}`)
308
- }
266
+ /** Forgets all configuration and cached state. Test/teardown helper. */
267
+ export async function resetLogging(): Promise<void> {
268
+ if (bootPromise) await bootPromise
269
+ await resetRuntime()
270
+ override = null
271
+ resolved = null
272
+ bootstrapped = false
273
+ bootPromise = null
274
+ }
309
275
 
310
- /** Enqueue one already-serialized line. Never rejects. */
311
- write(line: string): void {
312
- const size = Buffer.byteLength(line, 'utf8')
313
- this.bytes += size
314
- this.queue = this.queue
315
- .then(async () => {
316
- this.rotateIfNeeded(size)
317
- await appendFile(this.path, line, 'utf8')
318
- })
319
- .catch(() => {
320
- /* a full or locked disk must never surface as a plugin failure */
321
- })
322
- }
276
+ // ── record building ─────────────────────────────────────────────────────────
323
277
 
324
- /** Wait for everything enqueued so far to reach the file. */
325
- flush(): Promise<void> {
326
- return this.queue
278
+ /** Drops reserved keys so a plugin cannot spoof identity or level. */
279
+ function sanitize(fields: LogFields | undefined): LogFields {
280
+ if (!fields) return {}
281
+ const out: LogFields = {}
282
+ for (const [key, value] of Object.entries(fields)) {
283
+ if (RESERVED_FIELDS.has(key)) continue
284
+ out[key] = value
327
285
  }
286
+ return out
328
287
  }
329
288
 
330
- function exists(path: string): boolean {
289
+ /** JSON.stringify that can never throw (BigInt, cycles in exotic values). */
290
+ function serialize(record: Record<string, unknown>): string {
331
291
  try {
332
- statSync(path)
333
- return true
292
+ return JSON.stringify(record)
334
293
  } catch {
335
- return false
294
+ try {
295
+ return JSON.stringify({
296
+ time: Date.now(),
297
+ ts: new Date().toISOString(),
298
+ level: 'error',
299
+ msg: '[unserializable log record]',
300
+ pluginId: typeof record.pluginId === 'string' ? record.pluginId : 'unknown',
301
+ pid: process.pid,
302
+ })
303
+ } catch {
304
+ return '{"level":"error","msg":"[unserializable log record]"}'
305
+ }
336
306
  }
337
307
  }
338
308
 
339
- function currentSink(): FileSink {
340
- const existing = getSink()
341
- if (existing) return existing
342
- const cfg = currentConfig()
343
- const created = new FileSink(cfg.dir, cfg.fileName, cfg.maxBytes, cfg.maxFiles)
344
- setSink(created)
345
- return created
346
- }
347
-
348
- /** Wait for all pending writes to land (shutdown hooks, tests). */
349
- export async function flushLogs(): Promise<void> {
350
- await getSink()?.flush()
351
- }
352
-
353
- // ── logger ──────────────────────────────────────────────────────────────────
354
-
355
309
  function consoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error' {
356
310
  if (level === 'error') return 'error'
357
311
  if (level === 'warn') return 'warn'
@@ -359,92 +313,232 @@ function consoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error' {
359
313
  return 'log'
360
314
  }
361
315
 
362
- function createLogger(component: string, defaults: LogFields): PluginLogger {
363
- const emit = (level: LogLevel, message: string, fields?: LogFields): void => {
364
- try {
365
- const cfg = currentConfig()
366
- if (!isEnabled(level, cfg.level) && !(cfg.consoleLevel !== 'off' && isEnabled(level, cfg.consoleLevel))) {
367
- return
368
- }
316
+ function emit(pluginId: string, defaults: LogFields, level: LogLevel, message: string, fields?: LogFields): void {
317
+ try {
318
+ const cfg = currentConfig()
319
+ const fileEnabled = isEnabled(level, cfg.level)
320
+ const consoleEnabled = cfg.consoleLevel !== 'off' && isEnabled(level, cfg.consoleLevel)
321
+ if (!fileEnabled && !consoleEnabled) return
322
+
323
+ ensureInitialized()
324
+
325
+ const identity = getDshIdentity()
326
+ const record: LogFields = {
327
+ time: Date.now(),
328
+ // Legacy ISO timestamp; `time` is the canonical field.
329
+ ts: new Date().toISOString(),
330
+ level,
331
+ msg: message,
332
+ pluginId,
333
+ // Legacy alias, still emitted so existing `grep '"component"'` recipes
334
+ // keep working. Never settable by the caller (see RESERVED_FIELDS).
335
+ component: pluginId,
336
+ installationId: identity?.installationId ?? null,
337
+ hostType: identity?.hostType ?? null,
338
+ hostInstanceId: identity?.hostInstanceId ?? null,
339
+ edgeInstanceId: identity?.edgeInstanceId ?? null,
340
+ dshInstanceId: identity?.dshInstanceId ?? null,
341
+ pid: identity?.pid ?? process.pid,
342
+ }
343
+ Object.assign(record, sanitize(defaults))
344
+ Object.assign(record, sanitize(fields))
369
345
 
370
- const record: LogFields = {
371
- ts: new Date().toISOString(),
372
- level,
373
- component,
374
- pid: process.pid,
375
- msg: message,
376
- }
377
- if (Object.keys(defaults).length > 0) Object.assign(record, defaults)
378
- if (fields && Object.keys(fields).length > 0) Object.assign(record, fields)
379
-
380
- const safe = redact(record) as LogFields
381
-
382
- if (isEnabled(level, cfg.level)) {
383
- currentSink().write(`${JSON.stringify(safe)}\n`)
384
- }
385
- if (cfg.consoleLevel !== 'off' && isEnabled(level, cfg.consoleLevel)) {
386
- const { msg, ...rest } = safe
387
- // eslint-disable-next-line no-console
388
- console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest)
389
- }
390
- } catch {
391
- /* logging must never throw */
346
+ const safe = redact(record) as LogFields
347
+
348
+ if (fileEnabled) {
349
+ enqueueRecord(`${serialize(safe)}\n`)
350
+ }
351
+ if (consoleEnabled) {
352
+ const { msg, ...rest } = safe
353
+ // eslint-disable-next-line no-console
354
+ console[consoleMethod(level)](`[${pluginId}] ${String(msg)}`, rest)
392
355
  }
356
+ } catch {
357
+ /* logging must never throw into plugin business logic */
393
358
  }
359
+ }
394
360
 
361
+ function createLoggerFor(pluginId: string, defaults: LogFields): PluginLogger {
395
362
  return {
396
- component,
397
- debug: (message, fields) => emit('debug', message, fields),
398
- info: (message, fields) => emit('info', message, fields),
399
- warn: (message, fields) => emit('warn', message, fields),
400
- error: (message, fields) => emit('error', message, fields),
401
- child: (fields) => createLogger(component, { ...defaults, ...fields }),
363
+ pluginId,
364
+ component: pluginId,
365
+ debug: (message, fields) => emit(pluginId, defaults, 'debug', message, fields),
366
+ info: (message, fields) => emit(pluginId, defaults, 'info', message, fields),
367
+ warn: (message, fields) => emit(pluginId, defaults, 'warn', message, fields),
368
+ error: (message, fields) => emit(pluginId, defaults, 'error', message, fields),
369
+ child: (fields) => createLoggerFor(pluginId, { ...defaults, ...fields }),
402
370
  }
403
371
  }
404
372
 
405
373
  /**
406
- * Get (or create) the logger for `component`.
374
+ * Gets (or creates) the logger for `pluginId`.
407
375
  *
408
- * `component` should be the short plugin name used everywhere else in its
409
- * output — `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen` — so the unified
410
- * file can be filtered with a single grep.
376
+ * `pluginId` should be the value used everywhere else in that plugin's output —
377
+ * `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen`, or the full package name
378
+ * (`@huaqiu/dsh-plugin-eda`) when that is less ambiguous. It is attached to
379
+ * every record, which is what makes per-plugin filtering possible without a
380
+ * file per plugin.
411
381
  */
412
- export function getLogger(component: string, defaults: LogFields = {}): PluginLogger {
382
+ export function getLogger(pluginId: string, defaults: LogFields = {}): PluginLogger {
383
+ ensureInitialized()
413
384
  bootstrap()
414
- return createLogger(component, defaults)
385
+ return createLoggerFor(pluginId, defaults)
386
+ }
387
+
388
+ /** Spec-shaped factory: `createLogger({ pluginId })`. Equivalent to `getLogger`. */
389
+ export function createLogger(options: { pluginId: string }): PluginLogger {
390
+ return getLogger(options.pluginId)
415
391
  }
416
392
 
417
- // ── boot banner ─────────────────────────────────────────────────────────────
393
+ // ── initialization / boot banner ────────────────────────────────────────────
394
+
395
+ function ensureInitialized(): void {
396
+ if (getDshIdentity() !== null) return
397
+ initializeDshRuntime(runtimeConfig(currentConfig()))
398
+ }
418
399
 
419
400
  /**
420
- * Write one record describing where this process is logging.
401
+ * One record describing where this process logs and which identities it
402
+ * carries. This is the line that makes the next "one editor logged, the other
403
+ * did not" investigation cheap.
421
404
  *
422
- * This is the line that makes the next "we upgraded deepseek-harness and
423
- * something stopped syncing" investigation cheap: it pins the DSH home, the
424
- * resolved log file, the platform and the DSH/plugin versions in use at the
425
- * moment the first plugin touched the log.
405
+ * Emitted AFTER the destination is decided, so `ownership` and `logFile` in the
406
+ * banner describe reality instead of the transient "pending" state. Records
407
+ * logged before then are buffered and appear before it in the file.
426
408
  */
427
409
  function bootstrap(): void {
428
- const s = state()
429
- if (s.bootstrapped) return
430
- s.bootstrapped = true
431
- const cfg = currentConfig()
432
- const logger = createLogger('dsh-plugin-log', {})
410
+ if (bootstrapped) return
411
+ bootstrapped = true
412
+ bootPromise = awaitRuntimeReady().then(() => emitBootRecord())
413
+ }
414
+
415
+ function emitBootRecord(): void {
416
+ const snapshot = getRuntimeSnapshot()
417
+ const identity = getDshIdentity()
433
418
  let hqEdgeHome: string | null = null
434
419
  try {
435
420
  hqEdgeHome = getHqEdgeHome()
436
421
  } catch {
437
422
  hqEdgeHome = null
438
423
  }
439
- logger.info('plugin log ready', {
440
- logFile: join(cfg.dir, cfg.fileName),
441
- logDir: cfg.dir,
424
+ emit('dsh-plugin-log', {}, 'info', 'dsh plugin log ready', {
425
+ logRoot: snapshot.logRoot,
426
+ instanceDir: snapshot.instanceDir,
427
+ logFile: snapshot.logFile,
428
+ ownership: snapshot.ownership,
429
+ degradedReason: snapshot.degradedReason,
430
+ version: identity?.version ?? null,
431
+ targetHost: identity?.targetHost ?? null,
432
+ dshHome: identity?.dshHome ?? null,
442
433
  hqEdgeHome,
443
- level: cfg.level,
444
- consoleLevel: cfg.consoleLevel,
445
- pid: process.pid,
434
+ level: currentConfig().level,
435
+ consoleLevel: currentConfig().consoleLevel,
446
436
  node: process.version,
447
437
  platform: process.platform,
448
438
  arch: process.arch,
449
439
  })
450
440
  }
441
+
442
+ // ── introspection ───────────────────────────────────────────────────────────
443
+
444
+ /** Absolute directory this DSH process exclusively owns, or null before init. */
445
+ export function logDir(): string | null {
446
+ ensureInitialized()
447
+ return getRuntimeSnapshot().instanceDir
448
+ }
449
+
450
+ /** Absolute path of the active log file, or null before it is open. */
451
+ export function logFilePath(): string | null {
452
+ return getRuntimeSnapshot().logFile
453
+ }
454
+
455
+ /** Root that contains one directory per DSH instance. */
456
+ export function logRoot(): string | null {
457
+ ensureInitialized()
458
+ return getRuntimeSnapshot().logRoot
459
+ }
460
+
461
+ /** Identity of this DSH process (null before initialization). */
462
+ export function dshInstanceInfo(): DshRuntimeSnapshot {
463
+ return getRuntimeSnapshot()
464
+ }
465
+
466
+ export interface LoggingHealthReport extends LoggingHealth {
467
+ instanceDir: string | null
468
+ logFile: string | null
469
+ ownership: DshRuntimeSnapshot['ownership']
470
+ degradedReason: string | null
471
+ }
472
+
473
+ /** Destination health, for a diagnostics/health endpoint or a support bundle. */
474
+ export function getLoggingHealth(): LoggingHealthReport {
475
+ const snapshot = getRuntimeSnapshot()
476
+ const health = snapshot.health
477
+ const state: LoggingHealthState = health
478
+ ? health.state
479
+ : snapshot.degradedReason !== null
480
+ ? 'unavailable'
481
+ : snapshot.ready
482
+ ? 'healthy'
483
+ : 'initializing'
484
+ return {
485
+ state,
486
+ reason: health?.reason ?? snapshot.degradedReason ?? (snapshot.ready ? 'destination open' : 'not initialized'),
487
+ droppedRecords: (health?.droppedRecords ?? 0) + snapshot.droppedBeforeReady,
488
+ rotationCount: health?.rotationCount ?? 0,
489
+ lastError: health?.lastError ?? null,
490
+ instanceDir: snapshot.instanceDir,
491
+ logFile: snapshot.logFile,
492
+ ownership: snapshot.ownership,
493
+ degradedReason: snapshot.degradedReason,
494
+ }
495
+ }
496
+
497
+ // ── lifecycle ───────────────────────────────────────────────────────────────
498
+
499
+ /** Waits until the destination is decided. For tests and startup diagnostics. */
500
+ export function ready(): Promise<boolean> {
501
+ ensureInitialized()
502
+ return awaitRuntimeReady()
503
+ }
504
+
505
+ /** Waits for all pending records (and any rotation they triggered) to land. */
506
+ export async function flushLogs(): Promise<void> {
507
+ if (bootPromise) await bootPromise
508
+ await flushRuntime()
509
+ }
510
+
511
+ /**
512
+ * Final flush + close + ownership release.
513
+ *
514
+ * Owned by the DSH host. A plugin must NEVER call this: it would close the
515
+ * shared destination for every other plugin in the process.
516
+ */
517
+ export async function shutdownLogging(): Promise<void> {
518
+ if (bootPromise) await bootPromise
519
+ await shutdownRuntime()
520
+ }
521
+
522
+ /** Runs historical recovery/retention now (tests, or a DSH maintenance hook). */
523
+ export async function runMaintenance(
524
+ options: { timeBudgetMs?: number; retentionDays?: number; minAgeMs?: number } = {},
525
+ ): Promise<void> {
526
+ ensureInitialized()
527
+ await awaitRuntimeReady()
528
+ await runRuntimeMaintenance(options)
529
+ }
530
+
531
+ /**
532
+ * Creates the log root if it does not exist. Exposed for the DSH host's
533
+ * startup path, which may want to validate the destination before plugins load.
534
+ */
535
+ export function ensureLogRoot(): string {
536
+ const cfg = currentConfig()
537
+ const root = cfg.dshLogRoot ?? getDshLogRoot(getDshIdentity()?.edgeInstanceId ?? null)
538
+ try {
539
+ if (!existsSync(root)) mkdirSync(root, { recursive: true })
540
+ } catch {
541
+ /* the runtime reports the failure with full context */
542
+ }
543
+ return root
544
+ }