@huaqiu/dsh-plugin-log 0.6.23 → 0.6.25

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/lib/index.mjs CHANGED
@@ -1,83 +1,12 @@
1
- import { mkdirSync, renameSync, rmSync, statSync } from "node:fs";
2
- import { appendFile } from "node:fs/promises";
3
- import { homedir, tmpdir } from "node:os";
4
- import { join } from "node:path";
5
- //#region src/paths.ts
6
- /**
7
- * Inlined from `@hqedge/paths` (hq-edge/packages/paths/src/index.ts) so this
8
- * plugin stays fully self-contained — no runtime dependency on the published
9
- * package. Keep in sync when `@hqedge/paths` changes its path conventions.
10
- *
11
- * ────────────────────────────────────────────────────────────────────────────
12
- * Shared path resolution for HQ Edge runtimes.
13
- *
14
- * The single source of truth for where HQ Edge places per-user directories.
15
- * `getHqEdgeHome()` is the root: every other path getter (`getLogBaseDir`,
16
- * `getLogDir`) is derived from it, so all HQ Edge user directories live under
17
- * one self-contained tree and every consumer resolves the same location.
18
- *
19
- * The home is **the same on every platform** — `~/.hq-edge/` — because HQ Edge
20
- * is a developer/EDA runtime environment rather than a conventional desktop
21
- * app: a single dotfile under `$HOME` keeps logging, diagnostics, DSH
22
- * integration, CLI behavior and documentation identical on macOS / Linux /
23
- * Windows, instead of introducing a second filesystem convention
24
- * (`%LOCALAPPDATA%\hq-edge` or `~/.local/share/hq-edge`) per platform.
25
- * `HQ_EDGE_HOME` is the universal escape hatch (tests, bundling, portable
26
- * installs, CI).
27
- *
28
- * Note: the immutable HQ Edge runtime (`<installRoot>/dsh`,
29
- * `<installRoot>/dsh-plugins`) and `<KiCad installation>/` (application
30
- * install) are deliberately NOT this home — user data, managed runtime and
31
- * installation stay distinct. Mutable per-version DSH state lives UNDER this
32
- * home at `<home>/<version>/dsh-home` (see dshHome.ts). The
33
- * `~/.hq/hq-edge/<version>/` path from an earlier design draft never landed.
34
- */
35
- /**
36
- * Resolves the per-user data home directory for HQ Edge — the single root from
37
- * which every other HQ Edge path getter is derived.
38
- *
39
- * macOS / Linux / Windows: ~/.hq-edge/
40
- *
41
- * Unconditional across platforms (see the file header for the rationale). The
42
- * path may be overridden explicitly via `override` or the `HQ_EDGE_HOME`
43
- * environment variable (useful for tests / bundling / portable installs).
44
- */
45
- function getHqEdgeHome(override) {
46
- if (override) return override;
47
- if (process.env.HQ_EDGE_HOME) return process.env.HQ_EDGE_HOME;
48
- return join(homedir(), ".hq-edge");
49
- }
50
- /**
51
- * Resolves the base log directory for HQ Edge.
52
- *
53
- * Built on top of `getHqEdgeHome()` as `<home>/logs` on every platform, so
54
- * logs live inside the HQ Edge home tree:
55
- *
56
- * macOS / Linux / Windows: ~/.hq-edge/logs/
57
- *
58
- * The path may be overridden explicitly via `override` or the
59
- * `HQ_EDGE_LOG_DIR` environment variable.
60
- */
61
- function getLogBaseDir(override) {
62
- if (override) return override;
63
- if (process.env.HQ_EDGE_LOG_DIR) return process.env.HQ_EDGE_LOG_DIR;
64
- return join(getHqEdgeHome(), "logs");
65
- }
66
- /**
67
- * Resolves the per-component log directory, e.g. `<base>/dsh-plugins/`.
68
- *
69
- * The directory is created on demand by the rotating file stream.
70
- *
71
- * Note: the directory name is the component verbatim — there is no implicit
72
- * version scoping. Callers that need version isolation (e.g. the DSH home,
73
- * which keeps one tree per HQ Edge release) must layer it on top of
74
- * `getHqEdgeHome()` themselves. Cross-version logs (server, plugin diagnostics)
75
- * intentionally share a tree so a single `tail -F` follows them across upgrades.
76
- */
77
- function getLogDir(component, baseDirOverride) {
78
- return join(getLogBaseDir(baseDirOverride), component);
79
- }
80
- //#endregion
1
+ import { closeSync, createReadStream, createWriteStream, existsSync, fsyncSync, linkSync, mkdirSync, openSync, promises, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
2
+ import { homedir } from "node:os";
3
+ import { basename, dirname, isAbsolute, join, resolve } from "node:path";
4
+ import { createHash, randomUUID } from "node:crypto";
5
+ import { fileURLToPath } from "node:url";
6
+ import { createConnection, createServer } from "node:net";
7
+ import { createGunzip, createGzip } from "node:zlib";
8
+ import { pipeline } from "node:stream/promises";
9
+ import { Writable } from "node:stream";
81
10
  //#region src/levels.ts
82
11
  /** Levels ordered from most to least verbose. */
83
12
  const LOG_LEVELS = [
@@ -141,6 +70,13 @@ const SENSITIVE_KEY = /(token|secret|password|passwd|pwd|authorization|cookie|ap
141
70
  const BEARER_IN_STRING = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/i;
142
71
  /** Strings at least this long that look like a single opaque credential blob. */
143
72
  const OPAQUE_SECRET = /^[A-Za-z0-9_-]{32,}$/;
73
+ /**
74
+ * UUIDs are identifiers, not secrets. Every record carries at least
75
+ * `installationId` / `edgeInstanceId` / `dshInstanceId`, all UUID-shaped, so
76
+ * without this exemption the shape-based rule would blank out exactly the
77
+ * fields that make a multi-process log attributable.
78
+ */
79
+ const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
144
80
  const REDACTED = "[redacted]";
145
81
  /** Maximum object depth walked before the value is collapsed. Cycle-safe. */
146
82
  const MAX_DEPTH = 6;
@@ -189,348 +125,2438 @@ function redactInner(value, depth, seen) {
189
125
  /** Redact credentials embedded in an otherwise ordinary string. */
190
126
  function redactString(value) {
191
127
  if (BEARER_IN_STRING.test(value)) return value.replace(BEARER_IN_STRING, "$1 " + REDACTED);
128
+ if (UUID_SHAPE.test(value)) return value;
192
129
  if (OPAQUE_SECRET.test(value)) return REDACTED;
193
130
  return value;
194
131
  }
195
132
  //#endregion
196
- //#region src/index.ts
133
+ //#region src/paths.ts
197
134
  /**
198
- * `@huaqiu/dsh-plugin-log` — one server-side log for every Huaqiu DSH plugin.
135
+ * Inlined from `@hqedge/paths` (hq-edge/packages/paths/src/index.ts) so this
136
+ * package stays fully self-contained — no runtime dependency on the published
137
+ * package. Keep in sync when `@hqedge/paths` changes its path conventions.
199
138
  *
200
- * ## Why this exists
139
+ * ────────────────────────────────────────────────────────────────────────────
140
+ * Shared path resolution for HQ Edge runtimes.
201
141
  *
202
- * Plugin diagnostics used to live only in the browser console: each plugin's
203
- * browser half logged to `console.*`, and the node half — the half that
204
- * actually owns credentials, HTTP routes and agent tools — logged nothing at
205
- * all outside the DSH process's stdout, which HQ Edge only captures as an
206
- * opaque text blob. When a `deepseek-harness` upgrade broke credential
207
- * propagation, the only way to see what the node half resolved was to add
208
- * temporary prints and re-run.
142
+ * The home is **the same on every platform** — `~/.hq-edge/` — because HQ Edge
143
+ * is a developer/EDA runtime environment rather than a conventional desktop
144
+ * app: a single dotfile under `$HOME` keeps logging, diagnostics, DSH
145
+ * integration, CLI behavior and documentation identical on macOS / Linux /
146
+ * Windows.
209
147
  *
210
- * This package gives every plugin one shared, file-backed, cross-platform log
211
- * inside the current HQ Edge log tree:
148
+ * ## Log tree layout (docs/tasks/dsh-plugin-log-isolation.md §3)
212
149
  *
213
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log (current)
214
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log (previous, after rotation)
150
+ * <home>/logs/instances/<edge-instance-id>/
151
+ * server.<date>.log ← owned by the HQ Edge process
152
+ * dsh/
153
+ * <dsh-instance-id>/
154
+ * instance.json ← this package writes it
155
+ * owner.lock ← diagnostic only
156
+ * dsh.<date>.log ← owned by THIS DSH process
157
+ * dsh.<date>.log.gz ← published archive
215
158
  *
216
- * ## HQ Edge home resolution
159
+ * A DSH process never writes into another DSH process's directory, and never
160
+ * into its parent Edge instance directory: it only appends the
161
+ * `<dsh-instance-id>` level below the `dsh/` root it is handed.
217
162
  *
218
- * The directory comes from the inlined `@hqedge/paths` resolution
219
- * (`src/paths.ts`): the same root every HQ Edge runtime uses, so plugin logs
220
- * land inside the current HQ Edge log tree:
163
+ * `HQ_EDGE_HOME` / `HQ_EDGE_LOG_DIR` / `DSH_LOG_ROOT` are the escape hatches
164
+ * (tests, portable installs, CI). Per repository convention a relative
165
+ * `HQ_EDGE_HOME` is ignored rather than resolved against the CWD.
166
+ */
167
+ /** True for a non-empty absolute path — the only accepted override shape. */
168
+ function absoluteOverride(value) {
169
+ if (value === void 0) return void 0;
170
+ const trimmed = value.trim();
171
+ if (trimmed.length === 0) return void 0;
172
+ return isAbsolute(trimmed) ? trimmed : void 0;
173
+ }
174
+ /**
175
+ * Resolves the per-user data home directory for HQ Edge — the single root from
176
+ * which every other HQ Edge path getter is derived.
221
177
  *
222
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log (current)
223
- * <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log (previous, after rotation)
178
+ * macOS / Linux / Windows: ~/.hq-edge/
224
179
  *
225
- * Resolution honours the same overrides as the rest of HQ Edge:
180
+ * The path may be overridden explicitly via `override` or the `HQ_EDGE_HOME`
181
+ * environment variable (tests / bundling / portable installs).
182
+ */
183
+ function getHqEdgeHome(override) {
184
+ return getHqEdgeHomeFrom(process.env, override);
185
+ }
186
+ /**
187
+ * Environment-parameterized form of {@link getHqEdgeHome}. Identity resolution
188
+ * uses this so the result depends on the environment it was HANDED, never on
189
+ * whatever `process.env` happens to contain at that moment.
190
+ */
191
+ function getHqEdgeHomeFrom(env, override) {
192
+ const explicit = absoluteOverride(override);
193
+ if (explicit) return explicit;
194
+ const fromEnv = absoluteOverride(env.HQ_EDGE_HOME);
195
+ if (fromEnv) return fromEnv;
196
+ return join(homedir(), ".hq-edge");
197
+ }
198
+ /**
199
+ * Resolves the base log directory for HQ Edge: `<home>/logs` on every
200
+ * platform. Overridable via `override` or `HQ_EDGE_LOG_DIR`.
201
+ */
202
+ function getLogBaseDir(override) {
203
+ return getLogBaseDirFrom(process.env, override);
204
+ }
205
+ /** Environment-parameterized form of {@link getLogBaseDir}. */
206
+ function getLogBaseDirFrom(env, override) {
207
+ const explicit = absoluteOverride(override);
208
+ if (explicit) return explicit;
209
+ const fromEnv = absoluteOverride(env.HQ_EDGE_LOG_DIR);
210
+ if (fromEnv) return fromEnv;
211
+ return join(getHqEdgeHomeFrom(env), "logs");
212
+ }
213
+ /**
214
+ * `<base>/instances/<edge-instance-id>/dsh` — the DSH log root owned by one HQ
215
+ * Edge process. Every DSH launch under that process creates its own child
216
+ * directory here.
226
217
  *
227
- * explicit `configure({ dir })` > $DSH_PLUGIN_LOG_DIR > $HQ_EDGE_LOG_DIR / $HQ_EDGE_HOME
218
+ * When `edgeInstanceId` is unknown (a standalone `dsh` used in development or a
219
+ * test), the root degrades to `<base>/dsh`, deliberately WITHOUT an
220
+ * `instances/<id>` level: inventing an Edge identity would attribute DSH logs
221
+ * to an HQ Edge process that does not exist.
222
+ */
223
+ function getDshLogRoot(edgeInstanceId, baseDirOverride) {
224
+ return getDshLogRootFrom(process.env, edgeInstanceId, baseDirOverride);
225
+ }
226
+ /** Environment-parameterized form of {@link getDshLogRoot}. */
227
+ function getDshLogRootFrom(env, edgeInstanceId, baseDirOverride) {
228
+ const base = getLogBaseDirFrom(env, baseDirOverride);
229
+ return edgeInstanceId ? join(base, "instances", edgeInstanceId, "dsh") : join(base, "dsh");
230
+ }
231
+ //#endregion
232
+ //#region src/fields.ts
233
+ /**
234
+ * Record fields owned by `@huaqiu/dsh-plugin-log`.
228
235
  *
229
- * HQ Edge runs DSH with `HQ_EDGE_HOME` set to its own per-user data directory,
230
- * so plugin logs live next to the rest of that installation's state and never
231
- * in the user's default home.
236
+ * Kept in a leaf module with NO runtime imports so the browser half can share
237
+ * the exact same reserved-field rule without pulling `node:fs` / `node:os`
238
+ * into a browser bundle.
239
+ */
240
+ /**
241
+ * A plugin's `fields` object may not override any of these. Without the rule a
242
+ * plugin could rewrite its own `pluginId` (mis-attributing records to another
243
+ * plugin) or promote a `debug` line to `error` — and the log would stop being
244
+ * evidence.
245
+ */
246
+ const RESERVED_FIELDS = /* @__PURE__ */ new Set([
247
+ "time",
248
+ "ts",
249
+ "level",
250
+ "msg",
251
+ "pid",
252
+ "schemaVersion",
253
+ "installationId",
254
+ "hostType",
255
+ "hostInstanceId",
256
+ "edgeInstanceId",
257
+ "dshInstanceId",
258
+ "pluginId",
259
+ "component"
260
+ ]);
261
+ //#endregion
262
+ //#region src/fs-utils.ts
263
+ /**
264
+ * Small, dependency-free filesystem primitives shared by identity, ownership,
265
+ * rotation and historical recovery.
232
266
  *
233
- * ## Cross-platform notes
267
+ * The DSH log tree is written by several DSH processes that may share one HQ
268
+ * Edge installation, so every mutation here follows the same rules as the HQ
269
+ * Edge logging subsystem (docs/tasks/dsh-plugin-log-isolation.md §5):
234
270
  *
235
- * - Pure `node:fs` / `node:os` / `node:path` — no native modules, no shelling
236
- * out, nothing that differs between macOS, Linux and Windows but the path
237
- * separators (handled by `node:path`).
238
- * - Rotation uses unlink-then-rename, because Windows cannot rename over an
239
- * existing file.
240
- * - File names never embed `:` or other Windows-illegal characters.
241
- * - If the log directory cannot be created (read-only install, locked-down
242
- * profile) we fall back to the OS temp dir, and if that also fails we keep
243
- * logging to the console. A logging failure must never take a plugin down.
271
+ * - publication is ATOMIC and NEVER overwrites an existing destination;
272
+ * - temporary files are unique and live on the same filesystem as the
273
+ * destination, so a rename can never cross volumes;
274
+ * - Windows sharing violations get bounded, classified retries;
275
+ * - every helper is safe to call from an error path: it never throws past a
276
+ * guarded boundary and never buffers without a bound.
277
+ */
278
+ /** RFC 4122 / RFC 9562 UUID (versions 1–5) — used to validate identity values. */
279
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
280
+ function isUuid(value) {
281
+ return typeof value === "string" && UUID_RE.test(value);
282
+ }
283
+ /** Filesystem errors that a Windows file lock / transient sharing violation can produce. */
284
+ const TRANSIENT_FS_CODES = /* @__PURE__ */ new Set([
285
+ "EPERM",
286
+ "EBUSY",
287
+ "EACCES",
288
+ "EAGAIN",
289
+ "UNKNOWN",
290
+ "ESTALE",
291
+ "ETIMEDOUT",
292
+ "ELOCKED"
293
+ ]);
294
+ /** Errors that must NOT be retried (permanent permission / invalid path / disk full). */
295
+ const PERMANENT_FS_CODES = /* @__PURE__ */ new Set([
296
+ "ENOENT",
297
+ "ENOSPC",
298
+ "EISDIR",
299
+ "ENOTDIR",
300
+ "EINVAL",
301
+ "ENAMETOOLONG",
302
+ "EROFS",
303
+ "EMFILE",
304
+ "ENFILE"
305
+ ]);
306
+ function isTransientFsError(err) {
307
+ const code = err?.code ?? "";
308
+ if (PERMANENT_FS_CODES.has(code)) return false;
309
+ return TRANSIENT_FS_CODES.has(code);
310
+ }
311
+ function errorCode(err) {
312
+ return err?.code ?? "UNKNOWN";
313
+ }
314
+ function errorMessage(err) {
315
+ return err instanceof Error ? err.message : String(err);
316
+ }
317
+ /** Bounded async delay used by filesystem retry backoff. */
318
+ function delay$1(ms) {
319
+ return new Promise((resolve) => setTimeout(resolve, ms));
320
+ }
321
+ /**
322
+ * Runs `operation` with a bounded exponential backoff for transient Windows
323
+ * file-lock failures. Permanent failures are rethrown immediately. A total
324
+ * time budget keeps a rotation from stalling plugin shutdown indefinitely.
325
+ */
326
+ async function withFsRetries(operation, options = {}) {
327
+ const attempts = options.attempts ?? 5;
328
+ const baseDelayMs = options.baseDelayMs ?? 25;
329
+ const maxDelayMs = options.maxDelayMs ?? 400;
330
+ const totalTimeoutMs = options.totalTimeoutMs ?? 5e3;
331
+ const isRetryable = options.isRetryable ?? isTransientFsError;
332
+ const deadline = Date.now() + totalTimeoutMs;
333
+ let lastError;
334
+ for (let attempt = 0; attempt < attempts; attempt += 1) try {
335
+ return await operation();
336
+ } catch (err) {
337
+ lastError = err;
338
+ if (!isRetryable(err) || attempt === attempts - 1 || Date.now() >= deadline) throw err;
339
+ const wait = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs, Math.max(0, deadline - Date.now()));
340
+ if (wait > 0) await delay$1(wait);
341
+ }
342
+ throw lastError;
343
+ }
344
+ /**
345
+ * Publishes `src` as `dst` without ever overwriting an existing file.
244
346
  *
245
- * ## Safety
347
+ * Hard-link creation is the primary mechanism: it is atomic on NTFS and POSIX
348
+ * and fails with EEXIST when the destination already exists. Where hard links
349
+ * are unavailable (some network/virtual filesystems), a guarded rename is used
350
+ * inside the caller's exclusively-owned directory.
246
351
  *
247
- * - Every field passes through `redact()`: credential-shaped keys and values
248
- * are replaced with `[redacted]`, so the log is safe to share.
249
- * - `getLogger()` never throws. Neither does any log call.
352
+ * Returns true when this call created `dst`, false when `dst` already existed.
250
353
  */
251
- const DEFAULT_FILE_NAME = "dsh-plugins.log";
252
- const DEFAULT_MAX_BYTES = 5242880;
253
- const DEFAULT_MAX_FILES = 4;
254
- const DEFAULT_LEVEL = "info";
255
- const DEFAULT_CONSOLE_LEVEL = "warn";
354
+ function atomicPublish(src, dst) {
355
+ if (existsSync(dst)) return false;
356
+ try {
357
+ linkSync(src, dst);
358
+ try {
359
+ unlinkSync(src);
360
+ } catch {}
361
+ return true;
362
+ } catch (err) {
363
+ if (errorCode(err) === "EEXIST") return false;
364
+ if (!isLinkUnsupported(err)) throw err;
365
+ if (existsSync(dst)) return false;
366
+ renameSync(src, dst);
367
+ return true;
368
+ }
369
+ }
370
+ function isLinkUnsupported(err) {
371
+ const code = errorCode(err);
372
+ return code === "EPERM" || code === "EOPNOTSUPP" || code === "ENOSYS" || code === "EXDEV" || code === "ENOTSUP";
373
+ }
256
374
  /**
257
- * Process-wide logger state, held on `globalThis`.
258
- *
259
- * Plugins are built independently, so each one gets its OWN bundled copy of
260
- * this module. Without a shared home, "one unified log" would degrade into one
261
- * sink (and one rotation counter) per plugin. Keying the state off a
262
- * `Symbol.for` on `globalThis` makes every copy — bundled, external, or
263
- * duplicated across installs — cooperate inside the same DSH process.
375
+ * Atomically writes `data` to `path` ONLY if that path does not exist, so a
376
+ * partially-written temp file can never be observed at the destination.
264
377
  */
265
- const STATE_KEY = Symbol.for("@huaqiu/dsh-plugin-log/state");
266
- function state() {
267
- const g = globalThis;
268
- const existing = g[STATE_KEY];
269
- if (existing) return existing;
270
- const fresh = {
271
- override: null,
272
- resolved: null,
273
- sink: null,
274
- bootstrapped: false
275
- };
276
- g[STATE_KEY] = fresh;
277
- return fresh;
378
+ function atomicCreateNewFile(path, data, tmpPrefix = ".tmp-") {
379
+ mkdirSync(dirname(path), { recursive: true });
380
+ const tmp = join(dirname(path), `${tmpPrefix}${randomUUID()}`);
381
+ let fd = null;
382
+ try {
383
+ fd = openSync(tmp, "wx", 384);
384
+ const buf = typeof data === "string" ? Buffer.from(data, "utf-8") : data;
385
+ writeSync(fd, buf, 0, buf.length, 0);
386
+ fsyncSync(fd);
387
+ closeSync(fd);
388
+ fd = null;
389
+ return atomicPublish(tmp, path);
390
+ } finally {
391
+ if (fd !== null) try {
392
+ closeSync(fd);
393
+ } catch {}
394
+ try {
395
+ if (existsSync(tmp)) unlinkSync(tmp);
396
+ } catch {}
397
+ }
278
398
  }
279
- const getOverride = () => state().override;
280
- const setOverride = (value) => {
281
- state().override = value;
282
- };
283
- const getSink = () => state().sink;
284
- const setSink = (value) => {
285
- state().sink = value;
286
- };
287
399
  /**
288
- * Programmatically configure logging. Call before the first `getLogger()`;
289
- * later calls take effect on the next `resetLogging()` (tests, host re-init).
400
+ * Reads a JSON file. Returns `null` on any error (missing, unreadable, NUL
401
+ * corruption, invalid JSON). Callers MUST treat `null` as "preserve, never
402
+ * delete" — a corrupt `instance.json` is evidence, not garbage.
290
403
  */
291
- function configureLogging(options) {
292
- setOverride({
293
- ...getOverride() ?? {},
294
- ...options
295
- });
296
- state().resolved = null;
404
+ function readJsonSafe(path) {
405
+ try {
406
+ const raw = readFileSync(path, "utf-8");
407
+ if (raw.includes("\0")) return null;
408
+ const value = JSON.parse(raw);
409
+ return value && typeof value === "object" ? value : null;
410
+ } catch {
411
+ return null;
412
+ }
297
413
  }
298
- /** Forget all configuration and cached loggers. Test/teardown helper. */
299
- function resetLogging() {
300
- const s = state();
301
- s.override = null;
302
- s.resolved = null;
303
- s.sink = null;
304
- s.bootstrapped = false;
414
+ /** Best-effort synchronous append that can never throw. Used by error paths. */
415
+ function appendDiagnostic(path, record) {
416
+ try {
417
+ mkdirSync(dirname(path), { recursive: true });
418
+ const line = typeof record === "string" ? record : JSON.stringify({
419
+ time: (/* @__PURE__ */ new Date()).toISOString(),
420
+ ...record !== null && typeof record === "object" ? record : { value: String(record) }
421
+ });
422
+ const fd = openSync(path, "a", 384);
423
+ try {
424
+ writeSync(fd, Buffer.from(`${line}\n`, "utf-8"));
425
+ } finally {
426
+ closeSync(fd);
427
+ }
428
+ } catch {}
305
429
  }
306
- function env(name) {
307
- const value = process.env[name];
308
- return value !== void 0 && value.trim().length > 0 ? value.trim() : void 0;
430
+ /** Size of a file, or 0 when it cannot be stat'ed. */
431
+ function sizeOrZero(path) {
432
+ try {
433
+ return statSync(path).size;
434
+ } catch {
435
+ return 0;
436
+ }
309
437
  }
310
- function readInt(value, fallback) {
311
- if (value === void 0) return fallback;
312
- const parsed = Number.parseInt(value, 10);
313
- return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
438
+ //#endregion
439
+ //#region src/identity.ts
440
+ /**
441
+ * Identity for ONE DSH process, and the log root it is allowed to write into.
442
+ *
443
+ * This is the fourth level of the ownership hierarchy
444
+ * (docs/tasks/dsh-plugin-log-isolation.md §1):
445
+ *
446
+ * installation_id HQ Edge installation (installation lifetime)
447
+ * host_instance_id EDA Host (host process lifetime)
448
+ * edge_instance_id HQ Edge (Edge process lifetime)
449
+ * dsh_instance_id DSH runtime (DSH process lifetime) ← here
450
+ *
451
+ * Plugins have no process identity of their own. They are attributed to a DSH
452
+ * process through `plugin_id` (see `index.ts`), which is why nothing in this
453
+ * module knows about plugins.
454
+ *
455
+ * Rules encoded here:
456
+ * - `dsh_instance_id` is generated per DSH LAUNCH. A DSH restart produces a
457
+ * new id and therefore a new directory; a plugin reload does not.
458
+ * - HQ Edge passes the parent identities in the environment. It must never
459
+ * generate a `dsh_instance_id` itself and reuse it across restarts.
460
+ * - An absent or malformed parent identity is recorded as `null`, never
461
+ * fabricated: attributing logs to the wrong Edge process is worse than
462
+ * attributing them to none.
463
+ */
464
+ /** Written once per DSH process, atomically, never overwritten. */
465
+ const INSTANCE_METADATA_FILENAME = "instance.json";
466
+ /** Diagnostic JSONL. Its EXISTENCE never implies ownership. */
467
+ const OWNER_LOCK_FILENAME = "owner.lock";
468
+ /** Appended by historical recovery in the recovering process's own directory. */
469
+ const RECOVERY_LOG_FILENAME = "recovery.log";
470
+ /** Written when the destination cannot be established at all. */
471
+ const FATAL_LOG_FILENAME = "fatal.log";
472
+ function envValue(env, name) {
473
+ const value = env[name];
474
+ if (value === void 0) return void 0;
475
+ const trimmed = value.trim();
476
+ return trimmed.length > 0 ? trimmed : void 0;
477
+ }
478
+ function uuidOrNull(env, name, warnings) {
479
+ const value = envValue(env, name);
480
+ if (value === void 0) return null;
481
+ if (isUuid(value)) return value;
482
+ warnings.push(`${name} is not a valid UUID and was ignored`);
483
+ return null;
484
+ }
485
+ function hostTypeOrNull(env, warnings) {
486
+ const value = envValue(env, "HQ_HOST_TYPE");
487
+ if (value === void 0) return null;
488
+ const normalized = value.toLowerCase();
489
+ if (!/^[a-z][a-z0-9_-]{0,31}$/.test(normalized)) {
490
+ warnings.push("HQ_HOST_TYPE has an unexpected shape and was ignored");
491
+ return null;
492
+ }
493
+ return normalized;
314
494
  }
315
495
  /**
316
- * Pick the log directory, honouring every override in precedence order.
317
- * Falls back to the OS temp directory when the DSH home is not writable — a
318
- * plugin that cannot log to its preferred location still logs somewhere.
319
- */
320
- function resolveLogDir(explicit) {
321
- const candidates = [];
322
- if (explicit !== void 0 && explicit.length > 0) candidates.push(explicit);
323
- const fromEnv = env("DSH_PLUGIN_LOG_DIR");
324
- if (fromEnv) candidates.push(fromEnv);
325
- candidates.push(getLogDir("dsh-plugins"));
326
- candidates.push(join(tmpdir(), "hq-dsh-plugins", "logs"));
327
- for (let i = 0; i < candidates.length; i += 1) {
328
- const dir = candidates[i];
329
- if (!dir) continue;
330
- try {
331
- mkdirSync(dir, { recursive: true });
332
- return {
333
- dir,
334
- fallback: i > 0
335
- };
336
- } catch {}
496
+ * Resolves the DSH log root and the parent identities from the environment.
497
+ *
498
+ * Root precedence (§3 / §4):
499
+ * 1. explicit option (`configureLogging({ dir })`)
500
+ * 2. `$DSH_LOG_ROOT` (set by HQ Edge when it launches DSH)
501
+ * 3. `$HQ_EDGE_INSTANCE_ID` → `<logs>/instances/<edge>/dsh`
502
+ * 4. otherwise → `<logs>/dsh` (standalone DSH)
503
+ */
504
+ function readDshLogContext(env = process.env, overrides = {}) {
505
+ const warnings = [];
506
+ const installationId = uuidOrNull(env, "HQ_EDGE_INSTALLATION_ID", warnings);
507
+ const edgeInstanceId = uuidOrNull(env, "HQ_EDGE_INSTANCE_ID", warnings);
508
+ const hostInstanceId = uuidOrNull(env, "HQ_HOST_INSTANCE_ID", warnings);
509
+ const hostType = hostTypeOrNull(env, warnings);
510
+ let dshLogRoot;
511
+ let dshLogRootSource;
512
+ if (overrides.dshLogRoot && overrides.dshLogRoot.length > 0) {
513
+ dshLogRoot = overrides.dshLogRoot;
514
+ dshLogRootSource = "override";
515
+ } else {
516
+ const fromEnv = envValue(env, "DSH_LOG_ROOT");
517
+ if (fromEnv) {
518
+ dshLogRoot = fromEnv;
519
+ dshLogRootSource = "env:DSH_LOG_ROOT";
520
+ } else {
521
+ dshLogRoot = getDshLogRootFrom(env, edgeInstanceId, overrides.baseDir);
522
+ dshLogRootSource = edgeInstanceId ? "edge-instance" : "unscoped";
523
+ }
337
524
  }
338
525
  return {
339
- dir: candidates[candidates.length - 1] ?? ".",
340
- fallback: true
526
+ dshLogRoot,
527
+ dshLogRootSource,
528
+ installationId,
529
+ edgeInstanceId,
530
+ hostType,
531
+ hostInstanceId,
532
+ targetHost: envValue(env, "HQ_TARGET_HOST") ?? null,
533
+ dshHome: envValue(env, "DSH_HOME") ?? null,
534
+ hqEdgeHome: getHqEdgeHomeFrom(env),
535
+ warnings
341
536
  };
342
537
  }
343
- function currentConfig() {
344
- const s = state();
345
- if (s.resolved) return s.resolved;
346
- const o = s.override;
347
- const { dir } = resolveLogDir(o?.dir);
348
- const consoleRaw = o?.consoleLevel ?? env("DSH_PLUGIN_LOG_CONSOLE");
349
- s.resolved = {
350
- dir,
351
- fileName: o?.fileName ?? env("DSH_PLUGIN_LOG_FILE") ?? DEFAULT_FILE_NAME,
352
- level: o?.level ?? parseLevel(env("DSH_PLUGIN_LOG_LEVEL"), DEFAULT_LEVEL),
353
- consoleLevel: o?.consoleLevel === "off" ? "off" : consoleRaw === "off" || consoleRaw === "none" || consoleRaw === "0" ? "off" : consoleRaw === "all" || consoleRaw === "1" || consoleRaw === "true" ? "debug" : parseLevel(consoleRaw, DEFAULT_CONSOLE_LEVEL),
354
- maxBytes: o?.maxBytes ?? readInt(env("DSH_PLUGIN_LOG_MAX_BYTES"), DEFAULT_MAX_BYTES),
355
- maxFiles: o?.maxFiles ?? readInt(env("DSH_PLUGIN_LOG_MAX_FILES"), DEFAULT_MAX_FILES)
538
+ let cachedVersion = null;
539
+ /**
540
+ * Version of this package, used to attribute a log directory to the build that
541
+ * created it. Resolved lazily and cached: `import.meta.url` may point outside
542
+ * the package when a plugin bundle inlines this module, in which case the env
543
+ * override or `unknown` is used instead of failing.
544
+ */
545
+ function pluginLogVersion() {
546
+ if (cachedVersion !== null) return cachedVersion;
547
+ const fromEnv = process.env.DSH_PLUGIN_LOG_VERSION?.trim();
548
+ if (fromEnv) {
549
+ cachedVersion = fromEnv;
550
+ return cachedVersion;
551
+ }
552
+ try {
553
+ const here = fileURLToPath(new URL(".", import.meta.url));
554
+ const raw = readFileSync(join(here, "..", "package.json"), "utf-8");
555
+ const parsed = JSON.parse(raw);
556
+ cachedVersion = typeof parsed.version === "string" ? parsed.version : "unknown";
557
+ } catch {
558
+ cachedVersion = "unknown";
559
+ }
560
+ return cachedVersion;
561
+ }
562
+ /**
563
+ * Creates the immutable identity of THIS DSH process.
564
+ *
565
+ * `dsh_instance_id` is taken from an explicit override (tests / host
566
+ * injection), else `$DSH_INSTANCE_ID`, else freshly generated. HQ Edge must
567
+ * not set either variable: a restart has to produce a new directory.
568
+ */
569
+ function createDshIdentity(context, options = {}) {
570
+ const injected = options.dshInstanceId ?? envValue(process.env, "DSH_INSTANCE_ID");
571
+ return {
572
+ schemaVersion: 1,
573
+ dshInstanceId: isUuid(injected) ? injected : randomUUID(),
574
+ installationId: context.installationId,
575
+ edgeInstanceId: context.edgeInstanceId,
576
+ hostType: context.hostType,
577
+ hostInstanceId: context.hostInstanceId,
578
+ targetHost: context.targetHost,
579
+ pid: options.pid ?? process.pid,
580
+ startedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
581
+ version: options.version ?? pluginLogVersion(),
582
+ dshHome: context.dshHome,
583
+ logRoot: context.dshLogRoot
356
584
  };
357
- return s.resolved;
358
585
  }
359
- /** Absolute path of the current log file, or `null` before first use. */
360
- function logFilePath() {
361
- const s = getSink();
362
- return s ? s.path : null;
586
+ /** Absolute directory this DSH process exclusively owns. */
587
+ function instanceDirFor(identity) {
588
+ return join(identity.logRoot, identity.dshInstanceId);
363
589
  }
364
- /** Absolute directory plugin logs are written to. */
365
- function logDir() {
366
- return currentConfig().dir;
590
+ /** Reads and validates `instance.json` from an (historical) directory. */
591
+ function readDshInstanceMetadata(dir) {
592
+ const value = readJsonSafe(join(dir, INSTANCE_METADATA_FILENAME));
593
+ if (!value) return null;
594
+ if (!isUuid(value.dshInstanceId)) return null;
595
+ if (basename(dir).toLowerCase() !== value.dshInstanceId.toLowerCase()) return null;
596
+ return {
597
+ schemaVersion: typeof value.schemaVersion === "number" ? value.schemaVersion : 0,
598
+ dshInstanceId: value.dshInstanceId,
599
+ installationId: isUuid(value.installationId) ? value.installationId : null,
600
+ edgeInstanceId: isUuid(value.edgeInstanceId) ? value.edgeInstanceId : null,
601
+ hostType: typeof value.hostType === "string" ? value.hostType : null,
602
+ hostInstanceId: isUuid(value.hostInstanceId) ? value.hostInstanceId : null,
603
+ targetHost: typeof value.targetHost === "string" ? value.targetHost : null,
604
+ pid: typeof value.pid === "number" ? value.pid : 0,
605
+ startedAt: typeof value.startedAt === "string" ? value.startedAt : "",
606
+ version: typeof value.version === "string" ? value.version : "unknown",
607
+ dshHome: typeof value.dshHome === "string" ? value.dshHome : null,
608
+ logRoot: typeof value.logRoot === "string" ? value.logRoot : dir
609
+ };
367
610
  }
611
+ //#endregion
612
+ //#region src/ownership.ts
368
613
  /**
369
- * Serialized appender with size-based rotation.
614
+ * Exclusive, OS-backed ownership of ONE DSH instance log directory.
615
+ *
616
+ * The lock is a **bound IPC endpoint held open by the owning DSH process**:
617
+ *
618
+ * Windows : named pipe \\.\pipe\hq-edge-dsh-instance-<sha256(dir)>
619
+ * POSIX : unix socket <dir>/.owner.sock
620
+ *
621
+ * Creating a second server on the same endpoint fails with EADDRINUSE while
622
+ * the owner is alive, and the OS closes the handle — releasing the lock — the
623
+ * instant the owner terminates, including abnormal termination. There is no
624
+ * PID check, no heartbeat and no stale-timestamp heuristic: a DSH process that
625
+ * crashes must not leave a lock that a later process has to guess about.
370
626
  *
371
- * Writes are chained on a single promise so concurrent log calls from different
372
- * plugins in the same process can never interleave or race the rotation.
627
+ * The endpoint is keyed by the INSTANCE DIRECTORY, so two DSH processes under
628
+ * the same HQ Edge process, two DSH processes under different Edge processes,
629
+ * and a DSH process plus the Edge maintenance job never contend for the same
630
+ * lock unless they genuinely target the same directory.
631
+ *
632
+ * `owner.lock` is a diagnostic JSONL file only. Its existence NEVER implies
633
+ * ownership, and it is intentionally left behind after exit: it is the record
634
+ * of which process last owned the directory and when.
373
635
  */
374
- var FileSink = class {
375
- dir;
376
- fileName;
377
- maxBytes;
378
- maxFiles;
379
- path;
380
- queue = Promise.resolve();
381
- bytes;
382
- constructor(dir, fileName, maxBytes, maxFiles) {
383
- this.dir = dir;
384
- this.fileName = fileName;
385
- this.maxBytes = maxBytes;
386
- this.maxFiles = maxFiles;
387
- this.path = join(dir, fileName);
388
- this.bytes = this.currentSize();
389
- }
390
- currentSize() {
391
- try {
392
- return statSync(this.path).size;
393
- } catch {
394
- return 0;
395
- }
636
+ const PIPE_PREFIX = "\\\\.\\pipe\\hq-edge-dsh-instance-";
637
+ const SOCKET_FILENAME = ".owner.sock";
638
+ function normalizedDir(dir) {
639
+ const absolute = resolve(dir);
640
+ return process.platform === "win32" ? absolute.toLowerCase() : absolute;
641
+ }
642
+ /** Deterministic, filesystem-safe lock key. Not an identity — a lookup key. */
643
+ function ownershipKey(dir) {
644
+ return createHash("sha256").update(normalizedDir(dir)).digest("hex").slice(0, 32);
645
+ }
646
+ function endpointFor(dir) {
647
+ return process.platform === "win32" ? `${PIPE_PREFIX}${ownershipKey(dir)}` : join(resolve(dir), SOCKET_FILENAME);
648
+ }
649
+ function recordOwnerClaim(dir, dshInstanceId) {
650
+ appendDiagnostic(join(dir, OWNER_LOCK_FILENAME), {
651
+ event: "ownership-claimed",
652
+ pid: process.pid,
653
+ dshInstanceId,
654
+ acquiredAt: (/* @__PURE__ */ new Date()).toISOString()
655
+ });
656
+ }
657
+ var DshOwnershipHandleImpl = class {
658
+ instanceDir;
659
+ dshInstanceId;
660
+ server;
661
+ socketFile;
662
+ diagnostics;
663
+ _released = false;
664
+ constructor(instanceDir, dshInstanceId, server, socketFile, diagnostics) {
665
+ this.instanceDir = instanceDir;
666
+ this.dshInstanceId = dshInstanceId;
667
+ this.server = server;
668
+ this.socketFile = socketFile;
669
+ this.diagnostics = diagnostics;
670
+ }
671
+ get released() {
672
+ return this._released;
396
673
  }
397
- /** Rotate when appending `next` bytes would exceed the cap. */
398
- rotateIfNeeded(next) {
399
- if (this.maxBytes <= 0) return;
400
- if (this.bytes + next <= this.maxBytes) return;
674
+ release() {
675
+ if (this._released) return;
676
+ this._released = true;
401
677
  try {
402
- for (let i = this.maxFiles - 1; i >= 1; i -= 1) {
403
- const from = i === 1 ? join(this.dir, this.fileName) : this.rotated(i - 1);
404
- const to = this.rotated(i);
405
- if (!exists(from)) continue;
406
- if (exists(to)) rmSync(to, { force: true });
407
- renameSync(from, to);
408
- }
409
- this.bytes = this.currentSize();
678
+ this.server.close();
410
679
  } catch {}
411
- }
412
- rotated(index) {
413
- const dot = this.fileName.lastIndexOf(".");
414
- const stem = dot > 0 ? this.fileName.slice(0, dot) : this.fileName;
415
- const ext = dot > 0 ? this.fileName.slice(dot) : "";
416
- return join(this.dir, `${stem}.${index}${ext}`);
417
- }
418
- /** Enqueue one already-serialized line. Never rejects. */
419
- write(line) {
420
- const size = Buffer.byteLength(line, "utf8");
421
- this.bytes += size;
422
- this.queue = this.queue.then(async () => {
423
- this.rotateIfNeeded(size);
424
- await appendFile(this.path, line, "utf8");
425
- }).catch(() => {});
426
- }
427
- /** Wait for everything enqueued so far to reach the file. */
428
- flush() {
429
- return this.queue;
680
+ if (this.socketFile) try {
681
+ unlinkSync(this.socketFile);
682
+ } catch {}
683
+ if (this.diagnostics) appendDiagnostic(join(this.instanceDir, OWNER_LOCK_FILENAME), {
684
+ event: "ownership-released",
685
+ pid: process.pid,
686
+ dshInstanceId: this.dshInstanceId,
687
+ releasedAt: (/* @__PURE__ */ new Date()).toISOString()
688
+ });
430
689
  }
431
690
  };
432
- function exists(path) {
691
+ function bindServer(endpoint) {
692
+ return new Promise((resolvePromise) => {
693
+ const server = createServer();
694
+ let settled = false;
695
+ const finish = (ok, code) => {
696
+ if (settled) return;
697
+ settled = true;
698
+ resolvePromise({
699
+ server,
700
+ ok,
701
+ code
702
+ });
703
+ };
704
+ server.once("error", (err) => finish(false, err.code ?? "UNKNOWN"));
705
+ server.once("listening", () => finish(true));
706
+ try {
707
+ server.listen(endpoint);
708
+ } catch (err) {
709
+ finish(false, errorCode(err));
710
+ }
711
+ });
712
+ }
713
+ function delay(ms) {
714
+ return new Promise((resolve) => {
715
+ setTimeout(resolve, ms).unref();
716
+ });
717
+ }
718
+ /**
719
+ * Binds the endpoint, retrying briefly while it reports EADDRINUSE.
720
+ *
721
+ * A process that has JUST released the endpoint can take a few milliseconds to
722
+ * disappear (Windows closes the named-pipe instance asynchronously). Without
723
+ * the retry, a recovery pass that runs immediately after a release mistakes a
724
+ * dying owner for a live one and skips the directory. A genuinely live owner
725
+ * keeps failing every attempt, so this only removes the race — it never steals
726
+ * a held lock.
727
+ */
728
+ async function bindWithRetry(endpoint) {
729
+ let bound = await bindServer(endpoint);
730
+ for (let attempt = 0; attempt < 4 && !bound.ok && bound.code === "EADDRINUSE"; attempt += 1) {
731
+ try {
732
+ bound.server.close();
733
+ } catch {}
734
+ await delay(15 * (attempt + 1));
735
+ bound = await bindServer(endpoint);
736
+ }
737
+ return bound;
738
+ }
739
+ /** POSIX only: is the socket file a live owner or a stale crash leftover? */
740
+ function socketIsLive(socketFile) {
741
+ return new Promise((resolvePromise) => {
742
+ const socket = createConnection(socketFile);
743
+ const done = (live) => {
744
+ socket.destroy();
745
+ resolvePromise(live);
746
+ };
747
+ socket.once("connect", () => done(true));
748
+ socket.once("error", () => done(false));
749
+ socket.setTimeout(250, () => done(false));
750
+ });
751
+ }
752
+ /**
753
+ * Attempts exclusive ownership. Returns `null` when another live process owns
754
+ * the directory — callers MUST then leave the directory completely alone.
755
+ *
756
+ * Asynchronous because a socket bind resolves on the event loop. The runtime
757
+ * gates opening the active log file on this promise, so no active file is ever
758
+ * written before ownership is established.
759
+ */
760
+ async function acquireDshOwnership(instanceDir, dshInstanceId, options = {}) {
761
+ const diagnostics = options.diagnostics !== false;
433
762
  try {
434
- statSync(path);
435
- return true;
763
+ mkdirSync(instanceDir, { recursive: true });
436
764
  } catch {
437
- return false;
765
+ return null;
438
766
  }
767
+ const endpoint = endpointFor(instanceDir);
768
+ let bound = await bindWithRetry(endpoint);
769
+ if (!bound.ok && process.platform !== "win32" && bound.code === "EADDRINUSE") {
770
+ if (existsSync(endpoint) && !await socketIsLive(endpoint)) {
771
+ try {
772
+ unlinkSync(endpoint);
773
+ } catch {}
774
+ bound = await bindWithRetry(endpoint);
775
+ }
776
+ }
777
+ if (!bound.ok) {
778
+ try {
779
+ bound.server.close();
780
+ } catch {}
781
+ return null;
782
+ }
783
+ if (diagnostics) recordOwnerClaim(instanceDir, dshInstanceId);
784
+ bound.server.unref();
785
+ return new DshOwnershipHandleImpl(instanceDir, dshInstanceId, bound.server, process.platform === "win32" ? null : endpoint, diagnostics);
439
786
  }
440
- function currentSink() {
441
- const existing = getSink();
442
- if (existing) return existing;
443
- const cfg = currentConfig();
444
- const created = new FileSink(cfg.dir, cfg.fileName, cfg.maxBytes, cfg.maxFiles);
445
- setSink(created);
446
- return created;
447
- }
448
- /** Wait for all pending writes to land (shutdown hooks, tests). */
449
- async function flushLogs() {
450
- await getSink()?.flush();
787
+ /**
788
+ * Historical recovery / cleanup entry point. Stricter than
789
+ * {@link acquireDshOwnership}: it refuses to create the directory (a deleted
790
+ * directory must stay deleted) and writes no diagnostics into it.
791
+ */
792
+ async function acquireHistoricalDshOwnership(instanceDir, dshInstanceId) {
793
+ if (!existsSync(instanceDir)) return null;
794
+ return acquireDshOwnership(instanceDir, dshInstanceId, { diagnostics: false });
451
795
  }
452
- function consoleMethod(level) {
453
- if (level === "error") return "error";
454
- if (level === "warn") return "warn";
455
- if (level === "info") return "info";
456
- return "log";
796
+ /** Non-destructive probe: true when nobody currently owns the directory. */
797
+ async function probeDshOwnership(instanceDir) {
798
+ if (!existsSync(instanceDir)) return false;
799
+ const handle = await acquireDshOwnership(instanceDir, "ownership-probe", { diagnostics: false });
800
+ if (!handle) return false;
801
+ handle.release();
802
+ return true;
457
803
  }
458
- function createLogger(component, defaults) {
459
- const emit = (level, message, fields) => {
804
+ /** Writes a recovery diagnostic without touching a live owner's data. */
805
+ function recordRecoveryDiagnostic(instanceDir, record) {
806
+ try {
807
+ const fd = openSync(join(instanceDir, RECOVERY_LOG_FILENAME), "a", 384);
460
808
  try {
461
- const cfg = currentConfig();
462
- if (!isEnabled(level, cfg.level) && !(cfg.consoleLevel !== "off" && isEnabled(level, cfg.consoleLevel))) return;
463
- const record = {
464
- ts: (/* @__PURE__ */ new Date()).toISOString(),
465
- level,
466
- component,
467
- pid: process.pid,
468
- msg: message
469
- };
470
- if (Object.keys(defaults).length > 0) Object.assign(record, defaults);
471
- if (fields && Object.keys(fields).length > 0) Object.assign(record, fields);
472
- const safe = redact(record);
473
- if (isEnabled(level, cfg.level)) currentSink().write(`${JSON.stringify(safe)}\n`);
474
- if (cfg.consoleLevel !== "off" && isEnabled(level, cfg.consoleLevel)) {
475
- const { msg, ...rest } = safe;
476
- console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest);
477
- }
478
- } catch {}
479
- };
480
- return {
481
- component,
482
- debug: (message, fields) => emit("debug", message, fields),
483
- info: (message, fields) => emit("info", message, fields),
484
- warn: (message, fields) => emit("warn", message, fields),
485
- error: (message, fields) => emit("error", message, fields),
486
- child: (fields) => createLogger(component, {
487
- ...defaults,
488
- ...fields
489
- })
490
- };
809
+ writeSync(fd, Buffer.from(`${JSON.stringify({
810
+ time: (/* @__PURE__ */ new Date()).toISOString(),
811
+ ...record
812
+ })}\n`));
813
+ } finally {
814
+ closeSync(fd);
815
+ }
816
+ } catch {}
491
817
  }
818
+ //#endregion
819
+ //#region src/rotation.ts
492
820
  /**
493
- * Get (or create) the logger for `component`.
821
+ * Asynchronous, fault-tolerant rotation + retention for ONE DSH process's log
822
+ * file inside the directory that process exclusively owns.
823
+ *
824
+ * The previous `@huaqiu/dsh-plugin-log` rotation was a synchronous
825
+ * `rename`-shift chain that (a) assumed the process could rename files another
826
+ * DSH process might hold open and (b) produced `.1 .2 .3` siblings with no
827
+ * ownership metadata. Both are wrong once several DSH processes share an
828
+ * installation, so this implementation follows the same rules as the HQ Edge
829
+ * logging subsystem (docs/tasks/dsh-plugin-log-isolation.md §5):
494
830
  *
495
- * `component` should be the short plugin name used everywhere else in its
496
- * output — `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen` — so the unified
497
- * file can be filtered with a single grep.
831
+ * - compression is streamed and asynchronous: no whole-file sync gzip;
832
+ * - the closing file is SEALED under a unique name first, so a crash leaves
833
+ * a recoverable artifact rather than a half-renamed member of a chain;
834
+ * - the archive is VERIFIED (gzip trailer included) before publication;
835
+ * - publication is atomic and NEVER overwrites an existing archive;
836
+ * - the sealed source is deleted only after successful publication;
837
+ * - unresolved artifacts are capped, so a filesystem that keeps rejecting
838
+ * publication cannot accumulate temp files without bound.
839
+ *
840
+ * Lifecycle:
841
+ * ACTIVE → ROTATION_REQUESTED → SEALING → ARCHIVING → VERIFYING
842
+ * → PUBLISHING → COMPLETED
843
+ * Every failure state preserves the original data for historical recovery.
498
844
  */
499
- function getLogger(component, defaults = {}) {
500
- bootstrap();
501
- return createLogger(component, defaults);
845
+ /**
846
+ * Defaults for DSH plugin logs: plugin diagnostics are low volume, so 10 MiB
847
+ * per file with 14 days of history is plenty, and 256 MiB caps a pathological
848
+ * plugin without competing with the parent Edge instance's own budget.
849
+ */
850
+ const DSH_ROTATION = {
851
+ frequency: "daily",
852
+ maxSize: "10m",
853
+ retentionDays: 14,
854
+ maxStorageBytes: 268435456,
855
+ compress: true
856
+ };
857
+ /** Parses a human size string ("10m", "1g", "500k", or "1024") into bytes. */
858
+ function parseSize(input) {
859
+ const match = /^(\d+(?:\.\d+)?)\s*([kmg]?b?)?$/i.exec(input.trim());
860
+ if (!match) return 10485760;
861
+ const value = Number.parseFloat(match[1] ?? "");
862
+ if (!Number.isFinite(value)) return 10485760;
863
+ switch ((match[2] || "m").toLowerCase()[0]) {
864
+ case "k": return Math.floor(value * 1024);
865
+ case "g": return Math.floor(value * 1024 * 1024 * 1024);
866
+ default: return Math.floor(value * 1024 * 1024);
867
+ }
868
+ }
869
+ /** Current UTC date as `yyyy-MM-dd`. UTC keeps multi-timezone installs stable. */
870
+ function todayString(date = /* @__PURE__ */ new Date()) {
871
+ return date.toISOString().slice(0, 10);
872
+ }
873
+ const SEALED_MARKER = ".log.sealed-";
874
+ const TEMP_MARKER = ".gz.tmp-";
875
+ const QUARANTINE_MARKER = ".quarantine-";
876
+ const ARCHIVE_SUFFIX = ".log.gz";
877
+ /** Canonical name for an in-progress gzip archive, e.g. `dsh.<date>.log.gz.tmp-<uuid>`. */
878
+ function tempArchivePathFor(archivePath) {
879
+ return `${archivePath.slice(0, -3)}${TEMP_MARKER}${randomUUID()}`;
880
+ }
881
+ /** Inverse of {@link tempArchivePathFor}, for a TEMP_MARKER-bearing name. */
882
+ function archivePathFromTempName(dir, name) {
883
+ return join(dir, `${name.slice(0, name.indexOf(TEMP_MARKER))}.gz`);
884
+ }
885
+ /** True for names that are published or legacy archives. */
886
+ function isArchiveName(name) {
887
+ return name.endsWith(".gz") || /\.gz\.\d+$/.test(name);
888
+ }
889
+ /** True for names that are incomplete rotation artifacts. */
890
+ function isRecoveryArtifactName(name) {
891
+ return name.includes(".log.sealed-") || name.includes(".gz.tmp-");
892
+ }
893
+ const MAX_PENDING_BYTES$1 = 4194304;
894
+ const MAX_PENDING_RECORDS$1 = 2e4;
895
+ const MAX_DIAGNOSTICS = 40;
896
+ const MAX_DELETES_PER_SWEEP = 64;
897
+ const MAX_OPEN_ATTEMPTS = 3;
898
+ const MAX_UNRESOLVED_ARTIFACTS = 6;
899
+ const STREAM_CLOSE_TIMEOUT_MS = 2e3;
900
+ const DRAIN_TIMEOUT_MS = 2e3;
901
+ const TEMP_MAX_AGE_MS = 864e5;
902
+ /** Streams `src` into a gzip temp file. Never loads the whole log into memory. */
903
+ async function compressFileToArchive(src, tmp, faults) {
904
+ if (faults?.gzipDelayMs) await new Promise((resolve) => setTimeout(resolve, faults.gzipDelayMs));
905
+ if (faults?.gzip) throw new Error("injected gzip failure");
906
+ await pipeline(createReadStream(src), createGzip({ level: 6 }), createWriteStream(tmp, { flags: "wx" }));
907
+ }
908
+ /** Verifies a gzip archive is complete and readable (trailer included). */
909
+ async function verifyGzipArchive(path) {
910
+ let bytes = 0;
911
+ const counter = new Writable({ write(chunk, _encoding, callback) {
912
+ bytes += chunk.length;
913
+ callback();
914
+ } });
915
+ await pipeline(createReadStream(path), createGunzip(), counter);
916
+ return bytes;
502
917
  }
503
918
  /**
504
- * Write one record describing where this process is logging.
919
+ * Serialized writer for one DSH log stream.
505
920
  *
506
- * This is the line that makes the next "we upgraded deepseek-harness and
507
- * something stopped syncing" investigation cheap: it pins the DSH home, the
508
- * resolved log file, the platform and the DSH/plugin versions in use at the
509
- * moment the first plugin touched the log.
921
+ * Every mutation — append, seal, compress, publish, sweep — runs on ONE promise
922
+ * chain, so two plugins logging concurrently can never interleave a rotation
923
+ * with a write, and `flush()` has a single, exact meaning: "everything enqueued
924
+ * so far, including any rotation it triggered, has finished".
510
925
  */
511
- function bootstrap() {
926
+ var DshLogWriter = class {
927
+ dir;
928
+ baseName;
929
+ cfg;
930
+ maxSizeBytes;
931
+ now;
932
+ faults;
933
+ onDiagnostic;
934
+ stream = null;
935
+ currentDate;
936
+ currentPath;
937
+ bytesWritten = 0;
938
+ queue = Promise.resolve();
939
+ pendingBytes = 0;
940
+ pendingRecords = 0;
941
+ droppedRecords = 0;
942
+ openAttempts = 0;
943
+ rotationCount = 0;
944
+ deletions = 0;
945
+ protectedFiles = /* @__PURE__ */ new Set();
946
+ diagnosticsEmitted = 0;
947
+ closing = false;
948
+ opened = false;
949
+ health = "initializing";
950
+ healthReason = "awaiting instance ownership";
951
+ lastError = null;
952
+ constructor(options) {
953
+ this.dir = options.dir;
954
+ this.baseName = options.baseName ?? "dsh";
955
+ this.cfg = options.cfg ?? DSH_ROTATION;
956
+ this.maxSizeBytes = parseSize(this.cfg.maxSize);
957
+ this.now = options.now ?? (() => /* @__PURE__ */ new Date());
958
+ this.faults = options.faults ?? {};
959
+ this.onDiagnostic = options.onDiagnostic;
960
+ this.currentDate = todayString(this.now());
961
+ this.currentPath = this.pathForDate(this.currentDate);
962
+ }
963
+ /** Absolute path of the active file (whether or not it is open yet). */
964
+ get path() {
965
+ return this.currentPath;
966
+ }
967
+ getHealth() {
968
+ return {
969
+ state: this.health,
970
+ reason: this.healthReason,
971
+ droppedRecords: this.droppedRecords,
972
+ rotationCount: this.rotationCount,
973
+ lastError: this.lastError
974
+ };
975
+ }
976
+ /** Opens the active file. Called only after the directory is owned. */
977
+ open() {
978
+ if (this.closing || this.opened) return;
979
+ this.opened = true;
980
+ this.openStream();
981
+ this.queue = this.queue.then(() => this.runSweepSafely());
982
+ }
983
+ pathForDate(date) {
984
+ return join(this.dir, `${this.baseName}.${date}.log`);
985
+ }
986
+ diagnose(event, err, extra = {}) {
987
+ if (this.diagnosticsEmitted >= MAX_DIAGNOSTICS) return;
988
+ this.diagnosticsEmitted += 1;
989
+ const record = {
990
+ event: `dsh-logging-${event}`,
991
+ instanceDir: this.dir,
992
+ ...extra
993
+ };
994
+ if (err !== void 0) {
995
+ record.code = errorCode(err);
996
+ record.message = errorMessage(err).slice(0, 500);
997
+ this.lastError = errorMessage(err).slice(0, 500);
998
+ }
999
+ if (this.onDiagnostic) try {
1000
+ this.onDiagnostic(record);
1001
+ return;
1002
+ } catch {}
1003
+ appendDiagnostic(join(this.dir, "logging-health.log"), record);
1004
+ }
1005
+ setHealth(state, reason, err) {
1006
+ this.health = state;
1007
+ this.healthReason = reason;
1008
+ if (err !== void 0) this.lastError = errorMessage(err).slice(0, 500);
1009
+ }
1010
+ openStream() {
1011
+ if (this.closing) return;
1012
+ if (this.faults.streamOpen) {
1013
+ this.setHealth("unavailable", "injected stream-open failure");
1014
+ this.diagnose("open-failed", /* @__PURE__ */ new Error("injected stream-open failure"));
1015
+ return;
1016
+ }
1017
+ try {
1018
+ const stream = createWriteStream(this.currentPath, { flags: "a" });
1019
+ stream.on("error", (err) => {
1020
+ this.diagnose("write-stream-error", err);
1021
+ this.setHealth("degraded", "active write stream error", err);
1022
+ if (this.stream !== stream) return;
1023
+ this.stream = null;
1024
+ stream.destroy();
1025
+ });
1026
+ this.stream = stream;
1027
+ this.bytesWritten = sizeOrZero(this.currentPath);
1028
+ this.setHealth("healthy", "active log stream open");
1029
+ if (this.faults.diskFull) {
1030
+ const err = Object.assign(/* @__PURE__ */ new Error("ENOSPC: no space left on device"), { code: "ENOSPC" });
1031
+ setImmediate(() => stream.emit("error", err));
1032
+ }
1033
+ } catch (err) {
1034
+ this.setHealth("degraded", "cannot open active log file", err);
1035
+ this.diagnose("open-failed", err);
1036
+ }
1037
+ }
1038
+ /** Total in-memory queue pressure, used to reject unbounded buffering. */
1039
+ canEnqueue(bytes) {
1040
+ if (this.pendingBytes + bytes <= MAX_PENDING_BYTES$1 && this.pendingRecords < MAX_PENDING_RECORDS$1) return true;
1041
+ this.droppedRecords += 1;
1042
+ this.diagnose("pending-overflow", void 0, { droppedTotal: this.droppedRecords });
1043
+ return false;
1044
+ }
1045
+ /**
1046
+ * Enqueues one already-serialized JSONL record. Never throws and never
1047
+ * blocks the caller: a plugin's business call returns immediately.
1048
+ */
1049
+ write(line) {
1050
+ if (this.closing) {
1051
+ this.droppedRecords += 1;
1052
+ return;
1053
+ }
1054
+ const bytes = Buffer.byteLength(line, "utf8");
1055
+ if (!this.canEnqueue(bytes)) return;
1056
+ this.pendingBytes += bytes;
1057
+ this.pendingRecords += 1;
1058
+ this.queue = this.queue.then(async () => {
1059
+ this.pendingBytes -= bytes;
1060
+ this.pendingRecords -= 1;
1061
+ await this.append(line);
1062
+ }).catch((err) => {
1063
+ this.diagnose("append-failed", err);
1064
+ this.setHealth("degraded", "append failed", err);
1065
+ });
1066
+ }
1067
+ async append(line) {
1068
+ if (this.closing || this.health === "unavailable") {
1069
+ this.droppedRecords += 1;
1070
+ return;
1071
+ }
1072
+ if (todayString(this.now()) !== this.currentDate) await this.rotate("date");
1073
+ if (!this.stream) {
1074
+ if (this.openAttempts >= MAX_OPEN_ATTEMPTS) {
1075
+ this.droppedRecords += 1;
1076
+ return;
1077
+ }
1078
+ this.openAttempts += 1;
1079
+ this.openStream();
1080
+ if (!this.stream) {
1081
+ this.droppedRecords += 1;
1082
+ return;
1083
+ }
1084
+ }
1085
+ const stream = this.stream;
1086
+ try {
1087
+ await this.writeChunk(stream, line);
1088
+ this.bytesWritten += Buffer.byteLength(line, "utf8");
1089
+ this.openAttempts = 0;
1090
+ } catch (err) {
1091
+ this.diagnose("write-failed", err);
1092
+ this.setHealth("degraded", "write failed", err);
1093
+ this.droppedRecords += 1;
1094
+ return;
1095
+ }
1096
+ if (this.bytesWritten >= this.maxSizeBytes) await this.rotate("size");
1097
+ }
1098
+ /**
1099
+ * Writes one chunk and resolves only once the stream has flushed it, so
1100
+ * `flush()` is a real durability boundary (not just "handed to the stream").
1101
+ * A bounded timeout keeps a wedged stream from stalling shutdown forever.
1102
+ */
1103
+ writeChunk(stream, chunk) {
1104
+ return new Promise((resolve, reject) => {
1105
+ let settled = false;
1106
+ let timer = null;
1107
+ const cleanup = () => {
1108
+ if (timer) clearTimeout(timer);
1109
+ stream.removeListener("error", onError);
1110
+ };
1111
+ const finish = (err) => {
1112
+ if (settled) return;
1113
+ settled = true;
1114
+ cleanup();
1115
+ if (err) reject(err);
1116
+ else resolve();
1117
+ };
1118
+ const onError = (err) => finish(err);
1119
+ stream.once("error", onError);
1120
+ try {
1121
+ if (!stream.write(chunk, (err) => {
1122
+ if (err) finish(err);
1123
+ else finish();
1124
+ })) {
1125
+ timer = setTimeout(() => finish(), DRAIN_TIMEOUT_MS);
1126
+ timer.unref();
1127
+ }
1128
+ } catch (err) {
1129
+ finish(err instanceof Error ? err : new Error(String(err)));
1130
+ }
1131
+ });
1132
+ }
1133
+ sealedPathFor(date, reason, sequence) {
1134
+ const stem = reason === "date" ? `${this.baseName}.${date}` : `${this.baseName}.${date}.${sequence}`;
1135
+ return join(this.dir, `${stem}${SEALED_MARKER}${randomUUID()}`);
1136
+ }
1137
+ archivePathFor(sealedPath) {
1138
+ const name = basename(sealedPath);
1139
+ const marker = name.indexOf(SEALED_MARKER);
1140
+ const stem = marker > 0 ? name.slice(0, marker) : name;
1141
+ return join(this.dir, `${stem}${ARCHIVE_SUFFIX}`);
1142
+ }
1143
+ /** Never overwrite: pick the first free sequence, never append `.gz.N`. */
1144
+ chooseArchivePath(preferred, startSeq = 1) {
1145
+ if (startSeq === 1 && !existsSync(preferred)) return preferred;
1146
+ const stem = (preferred.endsWith(".log.gz") ? preferred.slice(0, -7) : preferred).replace(/\.\d+$/, "");
1147
+ for (let seq = startSeq; seq < 1e4; seq += 1) {
1148
+ const candidate = `${stem}.${seq}${ARCHIVE_SUFFIX}`;
1149
+ if (!existsSync(candidate)) return candidate;
1150
+ }
1151
+ return `${stem}.${randomUUID()}${ARCHIVE_SUFFIX}`;
1152
+ }
1153
+ unresolvedArtifactCount() {
1154
+ try {
1155
+ return readdirSync(this.dir).filter((name) => isRecoveryArtifactName(name)).length;
1156
+ } catch {
1157
+ return 0;
1158
+ }
1159
+ }
1160
+ closeStream() {
1161
+ const stream = this.stream;
1162
+ this.stream = null;
1163
+ if (!stream) return Promise.resolve();
1164
+ return new Promise((resolve) => {
1165
+ let settled = false;
1166
+ const done = () => {
1167
+ if (settled) return;
1168
+ settled = true;
1169
+ resolve();
1170
+ };
1171
+ stream.once("finish", done);
1172
+ stream.once("error", done);
1173
+ stream.once("close", done);
1174
+ try {
1175
+ stream.end();
1176
+ } catch {
1177
+ done();
1178
+ }
1179
+ setTimeout(done, STREAM_CLOSE_TIMEOUT_MS).unref();
1180
+ });
1181
+ }
1182
+ async rotate(reason) {
1183
+ if (this.closing || this.health === "unavailable") return;
1184
+ const unresolved = this.unresolvedArtifactCount();
1185
+ if (reason === "size" && unresolved >= MAX_UNRESOLVED_ARTIFACTS) {
1186
+ this.diagnose("rotation-deferred", void 0, {
1187
+ unresolved,
1188
+ cap: MAX_UNRESOLVED_ARTIFACTS
1189
+ });
1190
+ this.setHealth("degraded", "unresolved rotation artifacts at cap; continuing on active file");
1191
+ return;
1192
+ }
1193
+ this.rotationCount += 1;
1194
+ const closingDate = this.currentDate;
1195
+ const closingPath = this.currentPath;
1196
+ await this.closeStream();
1197
+ this.currentDate = todayString(this.now());
1198
+ this.currentPath = this.pathForDate(this.currentDate);
1199
+ if (!existsSync(closingPath) || sizeOrZero(closingPath) === 0) {
1200
+ try {
1201
+ if (existsSync(closingPath)) unlinkSync(closingPath);
1202
+ } catch {}
1203
+ this.openStream();
1204
+ return;
1205
+ }
1206
+ const sequence = reason === "size" ? this.rotationCount : 0;
1207
+ const sealedPath = this.sealedPathFor(closingDate, reason, sequence);
1208
+ try {
1209
+ if (this.faults.seal) throw new Error("injected seal failure");
1210
+ await withFsRetries(() => renameSync(closingPath, sealedPath), {
1211
+ attempts: 5,
1212
+ baseDelayMs: 25,
1213
+ totalTimeoutMs: 2e3
1214
+ });
1215
+ } catch (err) {
1216
+ this.diagnose("seal-failed", err, { closingPath });
1217
+ this.setHealth("degraded", "seal failed; continuing on active file", err);
1218
+ this.currentDate = closingDate;
1219
+ this.currentPath = closingPath;
1220
+ this.openStream();
1221
+ return;
1222
+ }
1223
+ this.protectedFiles.add(sealedPath);
1224
+ this.openStream();
1225
+ if (!this.cfg.compress) {
1226
+ this.protectedFiles.delete(sealedPath);
1227
+ return;
1228
+ }
1229
+ const preferredArchive = this.chooseArchivePath(this.archivePathFor(sealedPath));
1230
+ const tmpPath = tempArchivePathFor(preferredArchive);
1231
+ this.protectedFiles.add(tmpPath);
1232
+ let archiveVerified = false;
1233
+ try {
1234
+ await compressFileToArchive(sealedPath, tmpPath, this.faults);
1235
+ await verifyGzipArchive(tmpPath);
1236
+ archiveVerified = true;
1237
+ if (this.faults.publishDelayMs) await new Promise((resolve) => setTimeout(resolve, this.faults.publishDelayMs));
1238
+ if (this.faults.publish) throw new Error("injected publish failure");
1239
+ let published = false;
1240
+ let archivePath = preferredArchive;
1241
+ for (let attempt = 0; attempt < 32 && !published; attempt += 1) {
1242
+ try {
1243
+ published = await withFsRetries(() => atomicPublish(tmpPath, archivePath), {
1244
+ attempts: 4,
1245
+ baseDelayMs: 25,
1246
+ totalTimeoutMs: 2e3,
1247
+ isRetryable: (err) => errorCode(err) !== "EEXIST" && errorCode(err) !== "ENOENT"
1248
+ });
1249
+ } catch (err) {
1250
+ this.diagnose("publish-failed", err, { archivePath });
1251
+ break;
1252
+ }
1253
+ if (!published) archivePath = this.chooseArchivePath(preferredArchive, attempt + 2);
1254
+ }
1255
+ if (!published) {
1256
+ this.diagnose("publish-unresolved", void 0, {
1257
+ sealedPath,
1258
+ tmpPath,
1259
+ archivePath
1260
+ });
1261
+ this.setHealth("degraded", "archive publication deferred to recovery");
1262
+ return;
1263
+ }
1264
+ this.protectedFiles.delete(tmpPath);
1265
+ this.diagnose("archive-published", void 0, { archivePath });
1266
+ try {
1267
+ if (this.faults.unlink) throw new Error("injected unlink failure");
1268
+ await withFsRetries(() => unlinkSync(sealedPath), {
1269
+ attempts: 4,
1270
+ baseDelayMs: 25,
1271
+ totalTimeoutMs: 2e3
1272
+ });
1273
+ } catch (err) {
1274
+ this.diagnose("source-unlink-failed", err, { sealedPath });
1275
+ }
1276
+ this.setHealth("healthy", "rotation completed");
1277
+ } catch (err) {
1278
+ if (archiveVerified) {
1279
+ this.diagnose("publish-failed-after-verify", err, {
1280
+ sealedPath,
1281
+ tmpPath
1282
+ });
1283
+ this.setHealth("degraded", "archive publication deferred to recovery");
1284
+ } else {
1285
+ this.diagnose("compression-failed", err, {
1286
+ sealedPath,
1287
+ tmpPath
1288
+ });
1289
+ this.setHealth("degraded", "rotation failed; sealed source preserved", err);
1290
+ try {
1291
+ if (existsSync(tmpPath)) unlinkSync(tmpPath);
1292
+ } catch {}
1293
+ this.protectedFiles.delete(tmpPath);
1294
+ }
1295
+ } finally {
1296
+ this.protectedFiles.delete(sealedPath);
1297
+ await this.runSweepSafely();
1298
+ }
1299
+ }
1300
+ async runSweepSafely() {
1301
+ try {
1302
+ await this.runSweep();
1303
+ } catch (err) {
1304
+ this.diagnose("sweep-failed", err);
1305
+ }
1306
+ }
1307
+ /**
1308
+ * Capacity + retention. Counts ACTUAL disk consumption of the instance
1309
+ * directory. The active file and any file involved in the current rotation
1310
+ * are never deleted.
1311
+ */
1312
+ async runSweep() {
1313
+ this.deletions = 0;
1314
+ let entries;
1315
+ try {
1316
+ entries = await promises.readdir(this.dir);
1317
+ } catch {
1318
+ return;
1319
+ }
1320
+ const activeName = `${this.baseName}.${this.currentDate}.log`;
1321
+ const now = Date.now();
1322
+ const retentionMs = this.cfg.retentionDays * 24 * 60 * 60 * 1e3;
1323
+ const candidates = [];
1324
+ let totalSize = 0;
1325
+ for (const name of entries.slice(0, 2e4)) {
1326
+ const path = join(this.dir, name);
1327
+ try {
1328
+ const stat = await promises.stat(path);
1329
+ if (!stat.isFile()) continue;
1330
+ totalSize += stat.size;
1331
+ if (name === activeName || this.protectedFiles.has(path)) continue;
1332
+ if (isArchiveName(name)) candidates.push({
1333
+ name,
1334
+ path,
1335
+ size: stat.size,
1336
+ mtime: stat.mtimeMs
1337
+ });
1338
+ else if (name.includes(".gz.tmp-") && now - stat.mtimeMs > TEMP_MAX_AGE_MS) candidates.push({
1339
+ name,
1340
+ path,
1341
+ size: stat.size,
1342
+ mtime: stat.mtimeMs
1343
+ });
1344
+ } catch {}
1345
+ }
1346
+ for (const file of candidates) {
1347
+ const match = /\.(\d{4}-\d{2}-\d{2})\./.exec(file.name);
1348
+ const stamp = match?.[1] ? Date.parse(match[1]) : NaN;
1349
+ if ((Number.isNaN(stamp) ? now - file.mtime : now - stamp) <= retentionMs) continue;
1350
+ if (await this.deleteEligible(file)) totalSize -= file.size;
1351
+ }
1352
+ if (totalSize > this.cfg.maxStorageBytes) {
1353
+ const sorted = candidates.filter((file) => existsSync(file.path)).sort((a, b) => a.mtime - b.mtime);
1354
+ for (const file of sorted) {
1355
+ if (totalSize <= this.cfg.maxStorageBytes) break;
1356
+ if (await this.deleteEligible(file)) totalSize -= file.size;
1357
+ }
1358
+ }
1359
+ }
1360
+ async deleteEligible(file) {
1361
+ if (this.deletions >= MAX_DELETES_PER_SWEEP) return false;
1362
+ if (!existsSync(file.path)) return false;
1363
+ try {
1364
+ await withFsRetries(() => unlinkSync(file.path), {
1365
+ attempts: 3,
1366
+ baseDelayMs: 25,
1367
+ totalTimeoutMs: 1e3
1368
+ });
1369
+ this.deletions += 1;
1370
+ return true;
1371
+ } catch (err) {
1372
+ this.diagnose("cleanup-failed", err, { file: file.name });
1373
+ return false;
1374
+ }
1375
+ }
1376
+ /**
1377
+ * Waits until everything enqueued so far — including a rotation it
1378
+ * triggered — has completed. Never called from plugin code; only from DSH
1379
+ * shutdown and tests.
1380
+ */
1381
+ async flush() {
1382
+ await this.queue;
1383
+ }
1384
+ /** Bounded, final close. Deletes nothing and finishes the active file. */
1385
+ async close() {
1386
+ if (this.closing) {
1387
+ await this.queue;
1388
+ return;
1389
+ }
1390
+ this.closing = true;
1391
+ await this.queue;
1392
+ await this.closeStream();
1393
+ }
1394
+ };
1395
+ //#endregion
1396
+ //#region src/recovery.ts
1397
+ /**
1398
+ * Bounded historical recovery + retention for DSH log directories.
1399
+ *
1400
+ * A running DSH process owns ONLY `<dsh-root>/<its own dsh_instance_id>`. It may
1401
+ * inspect sibling (historical) directories — a previous DSH launch under the
1402
+ * same HQ Edge process leaves one behind every time DSH restarts — but every
1403
+ * modification MUST be preceded by successfully acquiring THAT directory's OS
1404
+ * ownership lock.
1405
+ *
1406
+ * That ordering is the whole safety argument (§5):
1407
+ * - the parent HQ Edge process never rotates DSH logs while DSH runs;
1408
+ * - one DSH process never rotates another LIVE DSH process's log;
1409
+ * - a directory whose owner is gone can be repaired by any later DSH process.
1410
+ *
1411
+ * Recovery is idempotent, bounded in time and file count, never rewrites
1412
+ * `instance.json`, never overwrites a published archive, and preserves
1413
+ * anything it cannot verify.
1414
+ */
1415
+ function emptyReport() {
1416
+ return {
1417
+ scanned: 0,
1418
+ skippedLive: 0,
1419
+ skippedInvalid: 0,
1420
+ skippedRecent: 0,
1421
+ recovered: 0,
1422
+ preserved: 0,
1423
+ quarantined: 0,
1424
+ deletedFiles: 0,
1425
+ deletedDirectories: 0,
1426
+ truncated: false,
1427
+ details: []
1428
+ };
1429
+ }
1430
+ function report(options, record) {
1431
+ appendDiagnostic(join(options.ownInstanceDir, RECOVERY_LOG_FILENAME), record);
1432
+ try {
1433
+ options.report?.(record);
1434
+ } catch {}
1435
+ }
1436
+ function archivePathForArtifact(dir, name) {
1437
+ if (name.includes(".gz.tmp-")) return archivePathFromTempName(dir, name);
1438
+ const stem = name.slice(0, name.indexOf(SEALED_MARKER));
1439
+ return join(dir, `${stem}${ARCHIVE_SUFFIX}`);
1440
+ }
1441
+ function uniqueArchivePath(preferred) {
1442
+ if (!existsSync(preferred)) return preferred;
1443
+ const stem = preferred.slice(0, -7);
1444
+ for (let seq = 1; seq < 1e3; seq += 1) {
1445
+ const candidate = `${stem}.${seq}${ARCHIVE_SUFFIX}`;
1446
+ if (!existsSync(candidate)) return candidate;
1447
+ }
1448
+ return `${stem}.${randomUUID()}${ARCHIVE_SUFFIX}`;
1449
+ }
1450
+ /**
1451
+ * Repairs incomplete rotation artifacts left by a previous DSH process.
1452
+ * Safe to run repeatedly and safe to run while other DSH processes are active
1453
+ * (their directories are skipped because their ownership lock is held).
1454
+ */
1455
+ async function recoverDshInstances(options) {
1456
+ const now = options.now ?? Date.now;
1457
+ const maxDirectories = options.maxDirectories ?? 64;
1458
+ const maxFiles = options.maxFilesPerDirectory ?? 256;
1459
+ const deadline = now() + (options.timeBudgetMs ?? 3e3);
1460
+ const minAgeMs = options.minAgeMs ?? 5e3;
1461
+ const result = emptyReport();
1462
+ const recentGuard = minAgeMs > 0;
1463
+ const note = (dir, action, detail) => {
1464
+ result.details.push({
1465
+ dir,
1466
+ action,
1467
+ detail
1468
+ });
1469
+ report(options, {
1470
+ event: "dsh-historical-recovery",
1471
+ dir,
1472
+ action,
1473
+ detail
1474
+ });
1475
+ };
1476
+ let names;
1477
+ try {
1478
+ names = await promises.readdir(options.instancesRoot);
1479
+ } catch {
1480
+ return result;
1481
+ }
1482
+ for (const name of names.slice(0, maxDirectories)) {
1483
+ if (now() > deadline) {
1484
+ result.truncated = true;
1485
+ break;
1486
+ }
1487
+ const dir = join(options.instancesRoot, name);
1488
+ if (dir === options.ownInstanceDir) continue;
1489
+ if (!isUuid(name)) {
1490
+ result.skippedInvalid += 1;
1491
+ note(dir, "preserved-invalid-name");
1492
+ continue;
1493
+ }
1494
+ let stat;
1495
+ try {
1496
+ stat = await promises.stat(dir);
1497
+ if (!stat.isDirectory()) continue;
1498
+ } catch {
1499
+ continue;
1500
+ }
1501
+ result.scanned += 1;
1502
+ const metadata = readDshInstanceMetadata(dir);
1503
+ if (!metadata) {
1504
+ result.skippedInvalid += 1;
1505
+ note(dir, "preserved-corrupt-metadata");
1506
+ continue;
1507
+ }
1508
+ if (recentGuard && Math.max(0, now() - stat.mtimeMs) < minAgeMs) {
1509
+ result.skippedRecent += 1;
1510
+ note(dir, "skipped-recent");
1511
+ continue;
1512
+ }
1513
+ const ownership = await acquireHistoricalDshOwnership(dir, metadata.dshInstanceId);
1514
+ if (!ownership) {
1515
+ result.skippedLive += 1;
1516
+ note(dir, "skipped-live-owner");
1517
+ continue;
1518
+ }
1519
+ try {
1520
+ let files;
1521
+ try {
1522
+ files = (await promises.readdir(dir)).slice(0, maxFiles);
1523
+ } catch {
1524
+ continue;
1525
+ }
1526
+ for (const file of files) {
1527
+ if (now() > deadline) {
1528
+ result.truncated = true;
1529
+ break;
1530
+ }
1531
+ if (file.includes(".quarantine-")) continue;
1532
+ if (!file.includes(".gz.tmp-") && !file.includes(".log.sealed-")) continue;
1533
+ const path = join(dir, file);
1534
+ const canonicalArchive = archivePathForArtifact(dir, file);
1535
+ const canonicalExists = existsSync(canonicalArchive);
1536
+ if (file.includes(".gz.tmp-")) {
1537
+ try {
1538
+ await verifyGzipArchive(path);
1539
+ } catch {
1540
+ try {
1541
+ renameSync(path, `${path}${QUARANTINE_MARKER}${randomUUID()}`);
1542
+ result.quarantined += 1;
1543
+ note(dir, "quarantined-invalid-temp", file);
1544
+ } catch {
1545
+ result.preserved += 1;
1546
+ note(dir, "preserved-invalid-temp", file);
1547
+ }
1548
+ continue;
1549
+ }
1550
+ if (canonicalExists) {
1551
+ try {
1552
+ unlinkSync(path);
1553
+ result.deletedFiles += 1;
1554
+ note(dir, "removed-redundant-temp", file);
1555
+ } catch {
1556
+ result.preserved += 1;
1557
+ }
1558
+ continue;
1559
+ }
1560
+ try {
1561
+ if (atomicPublish(path, canonicalArchive)) {
1562
+ result.recovered += 1;
1563
+ note(dir, "published-temp-archive", file);
1564
+ } else {
1565
+ result.preserved += 1;
1566
+ note(dir, "preserved-publish-conflict", file);
1567
+ }
1568
+ } catch {
1569
+ result.preserved += 1;
1570
+ note(dir, "preserved-publish-failure", file);
1571
+ }
1572
+ continue;
1573
+ }
1574
+ if (canonicalExists) {
1575
+ result.preserved += 1;
1576
+ note(dir, "preserved-redundant-sealed", file);
1577
+ continue;
1578
+ }
1579
+ const archivePath = uniqueArchivePath(canonicalArchive);
1580
+ const tmp = tempArchivePathFor(archivePath);
1581
+ try {
1582
+ await compressFileToArchive(path, tmp);
1583
+ await verifyGzipArchive(tmp);
1584
+ if (atomicPublish(tmp, archivePath)) {
1585
+ await withFsRetries(() => unlinkSync(path), {
1586
+ attempts: 3,
1587
+ baseDelayMs: 25,
1588
+ totalTimeoutMs: 800
1589
+ });
1590
+ result.recovered += 1;
1591
+ note(dir, "recovered-sealed-source", file);
1592
+ } else {
1593
+ result.preserved += 1;
1594
+ note(dir, "preserved-archive-conflict", file);
1595
+ }
1596
+ } catch (err) {
1597
+ result.preserved += 1;
1598
+ note(dir, "preserved-compression-failure", `${file}: ${errorMessage(err).slice(0, 160)}`);
1599
+ try {
1600
+ if (existsSync(tmp)) unlinkSync(tmp);
1601
+ } catch {}
1602
+ }
1603
+ }
1604
+ } finally {
1605
+ ownership.release();
1606
+ recordRecoveryDiagnostic(dir, {
1607
+ event: "recovery-lock-released",
1608
+ pid: process.pid
1609
+ });
1610
+ }
1611
+ }
1612
+ return result;
1613
+ }
1614
+ /** Files that may remain in an expired instance directory. */
1615
+ const METADATA_FILES = /* @__PURE__ */ new Set([
1616
+ "instance.json",
1617
+ "owner.lock",
1618
+ "recovery.log",
1619
+ "fatal.log",
1620
+ "logging-health.log"
1621
+ ]);
1622
+ /**
1623
+ * Per-instance retention. Never deletes an active directory: ownership
1624
+ * acquisition fails while the owner is alive. Never deletes a directory that
1625
+ * still has incomplete recovery artifacts.
1626
+ */
1627
+ async function cleanupExpiredDshInstances(options) {
1628
+ const now = options.now ?? Date.now;
1629
+ const retentionMs = (options.retentionDays ?? 30) * 24 * 60 * 60 * 1e3;
1630
+ const deadline = now() + (options.timeBudgetMs ?? 3e3);
1631
+ const result = emptyReport();
1632
+ const note = (dir, action, detail) => {
1633
+ result.details.push({
1634
+ dir,
1635
+ action,
1636
+ detail
1637
+ });
1638
+ report(options, {
1639
+ event: "dsh-historical-cleanup",
1640
+ dir,
1641
+ action,
1642
+ detail
1643
+ });
1644
+ };
1645
+ let names;
1646
+ try {
1647
+ names = await promises.readdir(options.instancesRoot);
1648
+ } catch {
1649
+ return result;
1650
+ }
1651
+ for (const name of names.slice(0, options.maxDirectories ?? 64)) {
1652
+ if (now() > deadline) {
1653
+ result.truncated = true;
1654
+ break;
1655
+ }
1656
+ const dir = join(options.instancesRoot, name);
1657
+ if (dir === options.ownInstanceDir || !isUuid(name)) continue;
1658
+ const metadata = readDshInstanceMetadata(dir);
1659
+ if (!metadata) {
1660
+ result.skippedInvalid += 1;
1661
+ note(dir, "preserved-corrupt-metadata");
1662
+ continue;
1663
+ }
1664
+ let stat;
1665
+ try {
1666
+ stat = await promises.stat(dir);
1667
+ } catch {
1668
+ continue;
1669
+ }
1670
+ if (Math.max(0, now() - stat.mtimeMs) < retentionMs) continue;
1671
+ result.scanned += 1;
1672
+ const ownership = await acquireHistoricalDshOwnership(dir, metadata.dshInstanceId);
1673
+ if (!ownership) {
1674
+ result.skippedLive += 1;
1675
+ note(dir, "skipped-live-owner");
1676
+ continue;
1677
+ }
1678
+ try {
1679
+ let files;
1680
+ try {
1681
+ files = await promises.readdir(dir);
1682
+ } catch {
1683
+ continue;
1684
+ }
1685
+ if (files.some((file) => file.includes(".gz.tmp-") || file.includes(".log.sealed-") || file.includes(".quarantine-"))) {
1686
+ result.preserved += 1;
1687
+ note(dir, "preserved-unrecovered-artifacts");
1688
+ continue;
1689
+ }
1690
+ for (const file of files) {
1691
+ if (METADATA_FILES.has(file)) continue;
1692
+ if (!isArchiveName(file) && !file.endsWith(".log")) {
1693
+ result.preserved += 1;
1694
+ note(dir, "preserved-unknown-file", file);
1695
+ continue;
1696
+ }
1697
+ try {
1698
+ await withFsRetries(() => unlinkSync(join(dir, file)), {
1699
+ attempts: 3,
1700
+ baseDelayMs: 25,
1701
+ totalTimeoutMs: 800
1702
+ });
1703
+ result.deletedFiles += 1;
1704
+ } catch {
1705
+ result.preserved += 1;
1706
+ note(dir, "preserved-delete-failure", file);
1707
+ }
1708
+ }
1709
+ if ((await promises.readdir(dir)).every((file) => METADATA_FILES.has(file))) try {
1710
+ await promises.rm(dir, {
1711
+ recursive: true,
1712
+ force: true
1713
+ });
1714
+ result.deletedDirectories += 1;
1715
+ note(dir, "deleted-expired-dsh-instance");
1716
+ } catch {
1717
+ note(dir, "preserved-delete-directory-failure");
1718
+ }
1719
+ } finally {
1720
+ ownership.release();
1721
+ }
1722
+ }
1723
+ return result;
1724
+ }
1725
+ /**
1726
+ * Conservative handling of the pre-isolation shared plugin log (§3).
1727
+ *
1728
+ * Old builds wrote `<HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log[.N]` from
1729
+ * every plugin in every DSH process. Those files have no ownership metadata
1730
+ * and may still be written by an older build during a rolling upgrade, so this
1731
+ * function only REPORTS them. Nothing is moved, compressed or deleted: a
1732
+ * one-time, operator-reviewed migration is the only safe way to retire them.
1733
+ */
1734
+ async function reportLegacyPluginLogs(logBaseDir) {
1735
+ const files = [];
1736
+ let totalBytes = 0;
1737
+ const legacyDir = join(logBaseDir, "dsh-plugins");
1738
+ let names;
1739
+ try {
1740
+ names = await promises.readdir(legacyDir);
1741
+ } catch {
1742
+ return {
1743
+ files,
1744
+ totalBytes: 0,
1745
+ note: "no legacy dsh-plugins directory"
1746
+ };
1747
+ }
1748
+ for (const name of names) {
1749
+ if (!name.endsWith(".log") && !isArchiveName(name)) continue;
1750
+ const path = join(legacyDir, name);
1751
+ try {
1752
+ const stat = await promises.stat(path);
1753
+ if (!stat.isFile()) continue;
1754
+ files.push({
1755
+ path,
1756
+ size: stat.size,
1757
+ action: "preserved"
1758
+ });
1759
+ totalBytes += stat.size;
1760
+ } catch {}
1761
+ }
1762
+ return {
1763
+ files,
1764
+ totalBytes,
1765
+ note: `Preserved ${files.length} legacy shared plugin log file(s) (${totalBytes} bytes). No file was moved or deleted: ownership cannot be established from the old naming scheme.`
1766
+ };
1767
+ }
1768
+ //#endregion
1769
+ //#region src/runtime.ts
1770
+ /**
1771
+ * Process-wide logging runtime for ONE DSH process.
1772
+ *
1773
+ * This module is the only place that decides WHERE records go. Plugins never
1774
+ * see it: they call `getLogger()` and get a namespaced logger.
1775
+ *
1776
+ * Startup order (docs/tasks/dsh-plugin-log-isolation.md §4):
1777
+ * 1. read the parent logging context from the environment
1778
+ * 2. generate `dsh_instance_id` (per LAUNCH, never per plugin)
1779
+ * 3. create `<dsh-root>/<dsh_instance_id>/` exclusively
1780
+ * 4. write `instance.json` atomically (never overwrite)
1781
+ * 5. acquire the OS ownership lock for that directory
1782
+ * 6. open `dsh.<date>.log` and replay records buffered during 1–5
1783
+ *
1784
+ * Steps 1–4 are synchronous so that `logDir()` / `logFilePath()` are correct
1785
+ * the instant DSH starts. Step 5 is asynchronous (a socket bind resolves on the
1786
+ * event loop), so records emitted in the meantime are buffered — bounded — and
1787
+ * replayed after ownership is confirmed. If ownership cannot be established the
1788
+ * destination is marked unavailable and the buffer is dropped: there is
1789
+ * deliberately no fallback to a shared writable file.
1790
+ *
1791
+ * ## Why `globalThis`
1792
+ *
1793
+ * A plugin bundle may inline its own copy of this package, so a module-level
1794
+ * singleton would give each copy its own sink, rotation counter and buffer.
1795
+ * The state lives on `globalThis` under a `Symbol.for` key, which is a genuine
1796
+ * process-wide registry: every copy — bundled, external or duplicated —
1797
+ * cooperates on one destination.
1798
+ */
1799
+ const STATE_KEY = Symbol.for("@huaqiu/dsh-plugin-log/runtime");
1800
+ const HOST_SINK_KEY = Symbol.for("@huaqiu/dsh-plugin-log/host-sink");
1801
+ const MAX_PENDING_RECORDS = 2e3;
1802
+ const MAX_PENDING_BYTES = 1048576;
1803
+ const DEFAULT_OWNERSHIP_TIMEOUT_MS = 5e3;
1804
+ const FLUSH_TIMEOUT_MS = 5e3;
1805
+ const MAINTENANCE_DELAY_MS = 1500;
1806
+ const MAINTENANCE_BUDGET_MS = 3e3;
1807
+ const RETENTION_DAYS = 30;
1808
+ function freshState() {
1809
+ return {
1810
+ schema: 2,
1811
+ config: null,
1812
+ context: null,
1813
+ identity: null,
1814
+ instanceDir: null,
1815
+ ownership: null,
1816
+ ownershipState: "pending",
1817
+ ownershipPromise: null,
1818
+ writer: null,
1819
+ ready: false,
1820
+ degradedReason: null,
1821
+ pending: [],
1822
+ pendingBytes: 0,
1823
+ droppedBeforeReady: 0,
1824
+ shutdown: false,
1825
+ shutdownPromise: null,
1826
+ maintenanceScheduled: false,
1827
+ generation: 0
1828
+ };
1829
+ }
1830
+ function state() {
1831
+ const registry = globalThis;
1832
+ const existing = registry[STATE_KEY];
1833
+ if (existing && existing.schema === 2) return existing;
1834
+ const created = freshState();
1835
+ registry[STATE_KEY] = created;
1836
+ return created;
1837
+ }
1838
+ function hostSink() {
1839
+ return globalThis[HOST_SINK_KEY] ?? null;
1840
+ }
1841
+ /**
1842
+ * Installs a DSH-host-provided sink. MUST be called before the first log
1843
+ * record: once the package has established its own destination (and taken the
1844
+ * ownership lock), silently switching transports would abandon a directory it
1845
+ * owns. A late call is ignored and diagnosed rather than throwing.
1846
+ */
1847
+ function installHostLogSink(sink) {
1848
+ const registry = globalThis;
1849
+ if (sink === null) {
1850
+ delete registry[HOST_SINK_KEY];
1851
+ return;
1852
+ }
512
1853
  const s = state();
513
- if (s.bootstrapped) return;
514
- s.bootstrapped = true;
515
- const cfg = currentConfig();
516
- const logger = createLogger("dsh-plugin-log", {});
1854
+ if (s.identity !== null) {
1855
+ appendDiagnostic(join(s.instanceDir ?? ".", FATAL_LOG_FILENAME), {
1856
+ event: "host-sink-installed-too-late",
1857
+ detail: "installHostLogSink() must be called before the first log record"
1858
+ });
1859
+ return;
1860
+ }
1861
+ registry[HOST_SINK_KEY] = sink;
1862
+ }
1863
+ function degraded(reason, detail) {
1864
+ const s = state();
1865
+ s.degradedReason = reason;
1866
+ s.ownershipState = "unavailable";
1867
+ if (s.instanceDir && detail) appendDiagnostic(join(s.instanceDir, FATAL_LOG_FILENAME), {
1868
+ event: "logging-degraded",
1869
+ reason,
1870
+ detail,
1871
+ dshInstanceId: s.identity?.dshInstanceId ?? null,
1872
+ pid: process.pid
1873
+ });
1874
+ }
1875
+ /**
1876
+ * Creates the instance directory and metadata, then starts ownership
1877
+ * acquisition in the background. Idempotent: later calls return immediately.
1878
+ */
1879
+ function initializeDshRuntime(config = {}) {
1880
+ const s = state();
1881
+ if (s.shutdown) return;
1882
+ if (s.identity !== null) return;
1883
+ s.config = config;
1884
+ s.generation += 1;
1885
+ const generation = s.generation;
1886
+ const context = readDshLogContext(process.env, {
1887
+ dshLogRoot: config.dshLogRoot,
1888
+ baseDir: config.baseDir
1889
+ });
1890
+ s.context = context;
1891
+ try {
1892
+ mkdirSync(context.dshLogRoot, { recursive: true });
1893
+ } catch (err) {
1894
+ degraded("dsh-log-root-unavailable", String(err));
1895
+ return;
1896
+ }
1897
+ let identity = null;
1898
+ let instanceDir = null;
1899
+ for (let attempt = 0; attempt < 3 && identity === null; attempt += 1) {
1900
+ const candidate = createDshIdentity(context, {
1901
+ dshInstanceId: config.dshInstanceId,
1902
+ now: config.now?.()
1903
+ });
1904
+ const candidateDir = instanceDirFor(candidate);
1905
+ let created = false;
1906
+ try {
1907
+ mkdirSync(candidateDir);
1908
+ created = true;
1909
+ } catch {
1910
+ created = false;
1911
+ }
1912
+ if (!created) {
1913
+ if (!existsSync(candidateDir)) {
1914
+ degraded("instance-directory-unavailable", candidateDir);
1915
+ return;
1916
+ }
1917
+ const existing = readDshInstanceMetadata(candidateDir);
1918
+ if (existing !== null && existing.dshInstanceId === candidate.dshInstanceId) {
1919
+ identity = candidate;
1920
+ instanceDir = candidateDir;
1921
+ break;
1922
+ }
1923
+ if (config.dshInstanceId !== void 0) {
1924
+ degraded("instance-directory-collision", candidateDir);
1925
+ return;
1926
+ }
1927
+ continue;
1928
+ }
1929
+ const metadataPath = join(candidateDir, INSTANCE_METADATA_FILENAME);
1930
+ const metadata = {
1931
+ ...candidate,
1932
+ schemaVersion: 1
1933
+ };
1934
+ if (!atomicCreateNewFile(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`)) {
1935
+ degraded("instance-metadata-collision", metadataPath);
1936
+ return;
1937
+ }
1938
+ identity = candidate;
1939
+ instanceDir = candidateDir;
1940
+ }
1941
+ if (identity === null || instanceDir === null) {
1942
+ degraded("instance-identity-unavailable");
1943
+ return;
1944
+ }
1945
+ s.identity = identity;
1946
+ s.instanceDir = instanceDir;
1947
+ if (hostSink() !== null) {
1948
+ s.ready = true;
1949
+ s.ownershipState = "skipped";
1950
+ s.writer = null;
1951
+ flushPendingIntoHost();
1952
+ return;
1953
+ }
1954
+ const rotation = config.rotation ?? DSH_ROTATION;
1955
+ const skipOwnership = config.skipOwnership === true;
1956
+ s.ownershipPromise = (async () => {
1957
+ let handle = null;
1958
+ try {
1959
+ handle = await acquireDshOwnership(instanceDir, identity.dshInstanceId, { diagnostics: true });
1960
+ } catch {
1961
+ handle = null;
1962
+ }
1963
+ if (s.generation !== generation) {
1964
+ handle?.release();
1965
+ return;
1966
+ }
1967
+ if (!handle && !skipOwnership) {
1968
+ degraded("ownership-unavailable", instanceDir ?? void 0);
1969
+ dropPending();
1970
+ return;
1971
+ }
1972
+ s.ownership = handle;
1973
+ s.ownershipState = skipOwnership ? "skipped" : "held";
1974
+ const writer = new DshLogWriter({
1975
+ dir: instanceDir,
1976
+ baseName: "dsh",
1977
+ cfg: rotation,
1978
+ faults: config.faults,
1979
+ now: config.now,
1980
+ onDiagnostic: config.onDiagnostic
1981
+ });
1982
+ writer.open();
1983
+ if (s.shutdown) {
1984
+ await writer.close();
1985
+ handle?.release();
1986
+ return;
1987
+ }
1988
+ s.writer = writer;
1989
+ s.ready = true;
1990
+ flushPendingIntoWriter(writer);
1991
+ scheduleMaintenance();
1992
+ })();
1993
+ }
1994
+ function dropPending() {
1995
+ const s = state();
1996
+ s.droppedBeforeReady += s.pending.length;
1997
+ s.pending = [];
1998
+ s.pendingBytes = 0;
1999
+ }
2000
+ function flushPendingIntoWriter(writer) {
2001
+ const s = state();
2002
+ const pending = s.pending;
2003
+ s.pending = [];
2004
+ s.pendingBytes = 0;
2005
+ for (const line of pending) writer.write(line);
2006
+ }
2007
+ function flushPendingIntoHost() {
2008
+ const sink = hostSink();
2009
+ if (!sink) return;
2010
+ const s = state();
2011
+ const pending = s.pending;
2012
+ s.pending = [];
2013
+ s.pendingBytes = 0;
2014
+ for (const line of pending) try {
2015
+ sink.write(line);
2016
+ } catch {
2017
+ s.droppedBeforeReady += 1;
2018
+ }
2019
+ }
2020
+ /**
2021
+ * Accepts one already-serialized JSONL record. Never throws, never blocks.
2022
+ * Before the destination is ready the record is buffered (bounded); if the
2023
+ * destination is unavailable it is dropped — logging must never fail plugin
2024
+ * business logic.
2025
+ */
2026
+ function enqueueRecord(line) {
2027
+ const s = state();
2028
+ if (s.shutdown) return;
2029
+ const sink = hostSink();
2030
+ if (sink !== null) {
2031
+ try {
2032
+ sink.write(line);
2033
+ } catch {
2034
+ s.droppedBeforeReady += 1;
2035
+ }
2036
+ return;
2037
+ }
2038
+ if (s.writer !== null && s.ready) {
2039
+ s.writer.write(line);
2040
+ return;
2041
+ }
2042
+ if (s.degradedReason !== null && s.ownershipState === "unavailable") {
2043
+ s.droppedBeforeReady += 1;
2044
+ return;
2045
+ }
2046
+ const bytes = Buffer.byteLength(line, "utf8");
2047
+ if (s.pending.length >= MAX_PENDING_RECORDS || s.pendingBytes + bytes > MAX_PENDING_BYTES) {
2048
+ s.droppedBeforeReady += 1;
2049
+ return;
2050
+ }
2051
+ s.pending.push(line);
2052
+ s.pendingBytes += bytes;
2053
+ }
2054
+ function withTimeout(promise, ms, fallback) {
2055
+ return Promise.race([promise, new Promise((resolve) => {
2056
+ setTimeout(() => resolve(fallback), ms).unref();
2057
+ })]);
2058
+ }
2059
+ /** Resolves when the destination is decided (held, skipped or unavailable). */
2060
+ async function awaitRuntimeReady(timeoutMs = DEFAULT_OWNERSHIP_TIMEOUT_MS) {
2061
+ const s = state();
2062
+ if (s.ready) return true;
2063
+ if (s.degradedReason !== null) return false;
2064
+ if (!s.ownershipPromise) return false;
2065
+ return await withTimeout(s.ownershipPromise.then(() => s.ready || s.degradedReason === null), timeoutMs, false) && (s.ready || s.ownershipState === "skipped");
2066
+ }
2067
+ function getRuntimeSnapshot() {
2068
+ const s = state();
2069
+ return {
2070
+ dshInstanceId: s.identity?.dshInstanceId ?? null,
2071
+ instanceDir: s.instanceDir,
2072
+ logFile: s.writer?.path ?? null,
2073
+ logRoot: s.context?.dshLogRoot ?? null,
2074
+ ready: s.ready,
2075
+ ownership: s.ownershipState,
2076
+ degradedReason: s.degradedReason,
2077
+ droppedBeforeReady: s.droppedBeforeReady,
2078
+ health: s.writer?.getHealth() ?? null
2079
+ };
2080
+ }
2081
+ /** Identity of this DSH process, or null before initialization. */
2082
+ function getDshIdentity() {
2083
+ return state().identity;
2084
+ }
2085
+ /**
2086
+ * Repairs and prunes HISTORICAL sibling directories. Runs on the serialized
2087
+ * writer chain's behalf but touches only directories whose ownership lock is
2088
+ * free — i.e. whose DSH process is gone.
2089
+ */
2090
+ async function runRuntimeMaintenance(options = {}) {
2091
+ const s = state();
2092
+ if (!s.instanceDir || !s.context) return;
2093
+ if (s.shutdown) return;
2094
+ const ownInstanceDir = s.instanceDir;
2095
+ const instancesRoot = s.context.dshLogRoot;
2096
+ const report = (record) => {
2097
+ appendDiagnostic(join(ownInstanceDir, "maintenance.log"), record);
2098
+ };
2099
+ try {
2100
+ await recoverDshInstances({
2101
+ instancesRoot,
2102
+ ownInstanceDir,
2103
+ timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
2104
+ minAgeMs: options.minAgeMs,
2105
+ report
2106
+ });
2107
+ await cleanupExpiredDshInstances({
2108
+ instancesRoot,
2109
+ ownInstanceDir,
2110
+ retentionDays: options.retentionDays ?? RETENTION_DAYS,
2111
+ timeBudgetMs: options.timeBudgetMs ?? MAINTENANCE_BUDGET_MS,
2112
+ report
2113
+ });
2114
+ const legacy = await reportLegacyPluginLogs(getLogBaseDir(s.config?.baseDir));
2115
+ if (legacy.files.length > 0) report({
2116
+ event: "legacy-plugin-logs",
2117
+ ...legacy
2118
+ });
2119
+ } catch {}
2120
+ }
2121
+ function scheduleMaintenance() {
2122
+ const s = state();
2123
+ if (s.maintenanceScheduled) return;
2124
+ s.maintenanceScheduled = true;
2125
+ setTimeout(() => {
2126
+ runRuntimeMaintenance();
2127
+ }, MAINTENANCE_DELAY_MS).unref();
2128
+ }
2129
+ /** Waits for everything enqueued so far, bounded. */
2130
+ async function flushRuntime() {
2131
+ const s = state();
2132
+ const sink = hostSink();
2133
+ if (sink !== null) {
2134
+ try {
2135
+ await sink.flush?.();
2136
+ } catch {}
2137
+ return;
2138
+ }
2139
+ if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, void 0);
2140
+ if (s.writer) await withTimeout(s.writer.flush(), FLUSH_TIMEOUT_MS, void 0);
2141
+ }
2142
+ /**
2143
+ * Final flush + close + ownership release. Owned by the DSH host only: a
2144
+ * plugin unload must never call this, because it would close the destination
2145
+ * for every other plugin in the process.
2146
+ */
2147
+ async function shutdownRuntime() {
2148
+ const s = state();
2149
+ if (s.shutdownPromise) return s.shutdownPromise;
2150
+ s.shutdown = true;
2151
+ s.shutdownPromise = (async () => {
2152
+ const sink = hostSink();
2153
+ if (sink !== null) {
2154
+ try {
2155
+ await sink.flush?.();
2156
+ sink.close?.();
2157
+ } catch {}
2158
+ return;
2159
+ }
2160
+ if (s.ownershipPromise) await withTimeout(s.ownershipPromise, FLUSH_TIMEOUT_MS, void 0);
2161
+ const writer = s.writer;
2162
+ s.writer = null;
2163
+ if (writer) {
2164
+ await withTimeout(writer.flush(), FLUSH_TIMEOUT_MS, void 0);
2165
+ await withTimeout(writer.close(), FLUSH_TIMEOUT_MS, void 0);
2166
+ }
2167
+ const ownership = s.ownership;
2168
+ s.ownership = null;
2169
+ ownership?.release();
2170
+ })();
2171
+ return s.shutdownPromise;
2172
+ }
2173
+ /**
2174
+ * Test/teardown helper: shuts the runtime down and forgets all state so a test
2175
+ * can re-initialize with different configuration. Never called in production.
2176
+ */
2177
+ async function resetRuntime() {
2178
+ const s = state();
2179
+ await shutdownRuntime();
2180
+ const registry = globalThis;
2181
+ const fresh = freshState();
2182
+ fresh.generation = s.generation + 1;
2183
+ registry[STATE_KEY] = fresh;
2184
+ }
2185
+ //#endregion
2186
+ //#region src/index.ts
2187
+ /**
2188
+ * `@huaqiu/dsh-plugin-log` — one shared, per-DSH-process log for every Huaqiu
2189
+ * DSH plugin.
2190
+ *
2191
+ * ## Why this exists
2192
+ *
2193
+ * Plugin diagnostics used to live only in the browser console: each plugin's
2194
+ * browser half logged to `console.*`, and the node half — the half that
2195
+ * actually owns credentials, HTTP routes and agent tools — logged nothing at
2196
+ * all outside the DSH process's stdout, which HQ Edge only captures as an
2197
+ * opaque text blob.
2198
+ *
2199
+ * ## What changed (docs/tasks/dsh-plugin-log-isolation.md)
2200
+ *
2201
+ * The package is shared by every plugin, but the logging RESOURCE belongs to
2202
+ * the DSH process that loads them. So:
2203
+ *
2204
+ * - one DSH process = one log directory = one active file;
2205
+ * - the directory is `<dsh-root>/<dsh_instance_id>/`, where `dsh-root` is the
2206
+ * parent HQ Edge instance's `dsh/` directory;
2207
+ * - `dsh_instance_id` is generated per DSH LAUNCH — a restart produces a new
2208
+ * directory, a plugin reload does not;
2209
+ * - plugins never configure a destination or a rotation; they only name
2210
+ * themselves (`pluginId`) and get a namespaced logger;
2211
+ * - the DSH process owns rotation, compression, retention and shutdown.
2212
+ *
2213
+ * Layout:
2214
+ *
2215
+ * <HQ_EDGE_HOME>/logs/instances/<edge-instance-id>/dsh/
2216
+ * <dsh-instance-id>/
2217
+ * instance.json ← identity of this DSH process
2218
+ * owner.lock ← diagnostic only; existence ≠ ownership
2219
+ * dsh.2026-11-11.log ← active log (owned by this process)
2220
+ * dsh.2026-11-11.log.gz ← published archive
2221
+ *
2222
+ * ## Guarantees
2223
+ *
2224
+ * - `getLogger()` and every log call are synchronous, never throw, and never
2225
+ * fail plugin business logic because a destination failed;
2226
+ * - initialization is idempotent across duplicated package copies (the state
2227
+ * lives in a process-wide `globalThis` registry);
2228
+ * - a plugin's `fields` can never override identity or level fields;
2229
+ * - plugin unload/reload never creates a second transport and never closes
2230
+ * the shared one — only DSH shutdown flushes and closes.
2231
+ */
2232
+ const DEFAULT_LEVEL = "info";
2233
+ const DEFAULT_CONSOLE_LEVEL = "warn";
2234
+ let override = null;
2235
+ let resolved = null;
2236
+ let bootstrapped = false;
2237
+ /**
2238
+ * Pending boot-banner emission. `flushLogs()` must await it: the banner is
2239
+ * written once the destination is decided, so without this barrier a flush
2240
+ * could return before the banner (and any rotation it triggers) had landed.
2241
+ */
2242
+ let bootPromise = null;
2243
+ function env(name) {
2244
+ const value = process.env[name];
2245
+ if (value === void 0) return void 0;
2246
+ const trimmed = value.trim();
2247
+ return trimmed.length > 0 ? trimmed : void 0;
2248
+ }
2249
+ function readInt(value, fallback) {
2250
+ if (value === void 0) return fallback;
2251
+ const parsed = Number.parseInt(value, 10);
2252
+ return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
2253
+ }
2254
+ function readBool(value, fallback) {
2255
+ if (value === void 0) return fallback;
2256
+ const normalized = value.trim().toLowerCase();
2257
+ if ([
2258
+ "1",
2259
+ "true",
2260
+ "yes",
2261
+ "on"
2262
+ ].includes(normalized)) return true;
2263
+ if ([
2264
+ "0",
2265
+ "false",
2266
+ "no",
2267
+ "off"
2268
+ ].includes(normalized)) return false;
2269
+ return fallback;
2270
+ }
2271
+ function consoleLevelFrom(raw, explicit) {
2272
+ if (explicit === "off") return "off";
2273
+ if (explicit !== void 0) return explicit;
2274
+ if (raw === "off" || raw === "none" || raw === "0") return "off";
2275
+ if (raw === "all" || raw === "1" || raw === "true") return "debug";
2276
+ return parseLevel(raw, DEFAULT_CONSOLE_LEVEL);
2277
+ }
2278
+ function currentConfig() {
2279
+ if (resolved) return resolved;
2280
+ const o = override ?? {};
2281
+ const rootFromOption = o.dshLogRoot ?? o.dir;
2282
+ const rootFromEnv = env("DSH_LOG_ROOT") ?? env("DSH_PLUGIN_LOG_DIR");
2283
+ const maxSize = o.maxSize ?? (o.maxBytes !== void 0 ? `${Math.max(1, Math.floor(o.maxBytes / 1048576))}m` : void 0);
2284
+ resolved = {
2285
+ dshLogRoot: rootFromOption ?? rootFromEnv,
2286
+ dshInstanceId: o.dshInstanceId,
2287
+ level: o.level ?? parseLevel(env("DSH_PLUGIN_LOG_LEVEL"), DEFAULT_LEVEL),
2288
+ consoleLevel: consoleLevelFrom(env("DSH_PLUGIN_LOG_CONSOLE"), o.consoleLevel),
2289
+ maxSize: maxSize ?? env("DSH_PLUGIN_LOG_MAX_BYTES_SIZE") ?? "10m",
2290
+ retentionDays: o.retentionDays ?? readInt(env("DSH_PLUGIN_LOG_RETENTION_DAYS"), 14),
2291
+ maxStorageBytes: o.maxStorageBytes ?? readInt(env("DSH_PLUGIN_LOG_MAX_STORAGE_BYTES"), 268435456),
2292
+ compress: o.compress ?? readBool(env("DSH_PLUGIN_LOG_COMPRESS"), true),
2293
+ faults: o.faults,
2294
+ skipOwnership: o.skipOwnership === true,
2295
+ now: o.now,
2296
+ onDiagnostic: o.onDiagnostic
2297
+ };
2298
+ return resolved;
2299
+ }
2300
+ function runtimeConfig(cfg) {
2301
+ return {
2302
+ dshLogRoot: cfg.dshLogRoot,
2303
+ dshInstanceId: cfg.dshInstanceId,
2304
+ rotation: {
2305
+ frequency: "daily",
2306
+ maxSize: cfg.maxSize,
2307
+ retentionDays: cfg.retentionDays,
2308
+ maxStorageBytes: cfg.maxStorageBytes,
2309
+ compress: cfg.compress
2310
+ },
2311
+ faults: cfg.faults,
2312
+ skipOwnership: cfg.skipOwnership,
2313
+ now: cfg.now,
2314
+ onDiagnostic: cfg.onDiagnostic
2315
+ };
2316
+ }
2317
+ /**
2318
+ * Programmatically configure logging. Call before the first `getLogger()`;
2319
+ * once the destination is established a later call only takes effect after
2320
+ * {@link shutdownLogging} + {@link resetLogging} (tests, host re-init).
2321
+ */
2322
+ function configureLogging(options) {
2323
+ override = {
2324
+ ...override ?? {},
2325
+ ...options
2326
+ };
2327
+ resolved = null;
2328
+ if (getDshIdentity() !== null) enqueueRecord(serialize({
2329
+ time: Date.now(),
2330
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
2331
+ level: "warn",
2332
+ msg: "configureLogging called after logging started; restart required for it to take effect",
2333
+ pluginId: "dsh-plugin-log",
2334
+ component: "dsh-plugin-log",
2335
+ pid: process.pid
2336
+ }));
2337
+ }
2338
+ /** Forgets all configuration and cached state. Test/teardown helper. */
2339
+ async function resetLogging() {
2340
+ if (bootPromise) await bootPromise;
2341
+ await resetRuntime();
2342
+ override = null;
2343
+ resolved = null;
2344
+ bootstrapped = false;
2345
+ bootPromise = null;
2346
+ }
2347
+ /** Drops reserved keys so a plugin cannot spoof identity or level. */
2348
+ function sanitize(fields) {
2349
+ if (!fields) return {};
2350
+ const out = {};
2351
+ for (const [key, value] of Object.entries(fields)) {
2352
+ if (RESERVED_FIELDS.has(key)) continue;
2353
+ out[key] = value;
2354
+ }
2355
+ return out;
2356
+ }
2357
+ /** JSON.stringify that can never throw (BigInt, cycles in exotic values). */
2358
+ function serialize(record) {
2359
+ try {
2360
+ return JSON.stringify(record);
2361
+ } catch {
2362
+ try {
2363
+ return JSON.stringify({
2364
+ time: Date.now(),
2365
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
2366
+ level: "error",
2367
+ msg: "[unserializable log record]",
2368
+ pluginId: typeof record.pluginId === "string" ? record.pluginId : "unknown",
2369
+ pid: process.pid
2370
+ });
2371
+ } catch {
2372
+ return "{\"level\":\"error\",\"msg\":\"[unserializable log record]\"}";
2373
+ }
2374
+ }
2375
+ }
2376
+ function consoleMethod(level) {
2377
+ if (level === "error") return "error";
2378
+ if (level === "warn") return "warn";
2379
+ if (level === "info") return "info";
2380
+ return "log";
2381
+ }
2382
+ function emit(pluginId, defaults, level, message, fields) {
2383
+ try {
2384
+ const cfg = currentConfig();
2385
+ const fileEnabled = isEnabled(level, cfg.level);
2386
+ const consoleEnabled = cfg.consoleLevel !== "off" && isEnabled(level, cfg.consoleLevel);
2387
+ if (!fileEnabled && !consoleEnabled) return;
2388
+ ensureInitialized();
2389
+ const identity = getDshIdentity();
2390
+ const record = {
2391
+ time: Date.now(),
2392
+ ts: (/* @__PURE__ */ new Date()).toISOString(),
2393
+ level,
2394
+ msg: message,
2395
+ pluginId,
2396
+ component: pluginId,
2397
+ installationId: identity?.installationId ?? null,
2398
+ hostType: identity?.hostType ?? null,
2399
+ hostInstanceId: identity?.hostInstanceId ?? null,
2400
+ edgeInstanceId: identity?.edgeInstanceId ?? null,
2401
+ dshInstanceId: identity?.dshInstanceId ?? null,
2402
+ pid: identity?.pid ?? process.pid
2403
+ };
2404
+ Object.assign(record, sanitize(defaults));
2405
+ Object.assign(record, sanitize(fields));
2406
+ const safe = redact(record);
2407
+ if (fileEnabled) enqueueRecord(`${serialize(safe)}\n`);
2408
+ if (consoleEnabled) {
2409
+ const { msg, ...rest } = safe;
2410
+ console[consoleMethod(level)](`[${pluginId}] ${String(msg)}`, rest);
2411
+ }
2412
+ } catch {}
2413
+ }
2414
+ function createLoggerFor(pluginId, defaults) {
2415
+ return {
2416
+ pluginId,
2417
+ component: pluginId,
2418
+ debug: (message, fields) => emit(pluginId, defaults, "debug", message, fields),
2419
+ info: (message, fields) => emit(pluginId, defaults, "info", message, fields),
2420
+ warn: (message, fields) => emit(pluginId, defaults, "warn", message, fields),
2421
+ error: (message, fields) => emit(pluginId, defaults, "error", message, fields),
2422
+ child: (fields) => createLoggerFor(pluginId, {
2423
+ ...defaults,
2424
+ ...fields
2425
+ })
2426
+ };
2427
+ }
2428
+ /**
2429
+ * Gets (or creates) the logger for `pluginId`.
2430
+ *
2431
+ * `pluginId` should be the value used everywhere else in that plugin's output —
2432
+ * `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen`, or the full package name
2433
+ * (`@huaqiu/dsh-plugin-eda`) when that is less ambiguous. It is attached to
2434
+ * every record, which is what makes per-plugin filtering possible without a
2435
+ * file per plugin.
2436
+ */
2437
+ function getLogger(pluginId, defaults = {}) {
2438
+ ensureInitialized();
2439
+ bootstrap();
2440
+ return createLoggerFor(pluginId, defaults);
2441
+ }
2442
+ /** Spec-shaped factory: `createLogger({ pluginId })`. Equivalent to `getLogger`. */
2443
+ function createLogger(options) {
2444
+ return getLogger(options.pluginId);
2445
+ }
2446
+ function ensureInitialized() {
2447
+ if (getDshIdentity() !== null) return;
2448
+ initializeDshRuntime(runtimeConfig(currentConfig()));
2449
+ }
2450
+ /**
2451
+ * One record describing where this process logs and which identities it
2452
+ * carries. This is the line that makes the next "one editor logged, the other
2453
+ * did not" investigation cheap.
2454
+ *
2455
+ * Emitted AFTER the destination is decided, so `ownership` and `logFile` in the
2456
+ * banner describe reality instead of the transient "pending" state. Records
2457
+ * logged before then are buffered and appear before it in the file.
2458
+ */
2459
+ function bootstrap() {
2460
+ if (bootstrapped) return;
2461
+ bootstrapped = true;
2462
+ bootPromise = awaitRuntimeReady().then(() => emitBootRecord());
2463
+ }
2464
+ function emitBootRecord() {
2465
+ const snapshot = getRuntimeSnapshot();
2466
+ const identity = getDshIdentity();
517
2467
  let hqEdgeHome = null;
518
2468
  try {
519
2469
  hqEdgeHome = getHqEdgeHome();
520
2470
  } catch {
521
2471
  hqEdgeHome = null;
522
2472
  }
523
- logger.info("plugin log ready", {
524
- logFile: join(cfg.dir, cfg.fileName),
525
- logDir: cfg.dir,
2473
+ emit("dsh-plugin-log", {}, "info", "dsh plugin log ready", {
2474
+ logRoot: snapshot.logRoot,
2475
+ instanceDir: snapshot.instanceDir,
2476
+ logFile: snapshot.logFile,
2477
+ ownership: snapshot.ownership,
2478
+ degradedReason: snapshot.degradedReason,
2479
+ version: identity?.version ?? null,
2480
+ targetHost: identity?.targetHost ?? null,
2481
+ dshHome: identity?.dshHome ?? null,
526
2482
  hqEdgeHome,
527
- level: cfg.level,
528
- consoleLevel: cfg.consoleLevel,
529
- pid: process.pid,
2483
+ level: currentConfig().level,
2484
+ consoleLevel: currentConfig().consoleLevel,
530
2485
  node: process.version,
531
2486
  platform: process.platform,
532
2487
  arch: process.arch
533
2488
  });
534
2489
  }
2490
+ /** Absolute directory this DSH process exclusively owns, or null before init. */
2491
+ function logDir() {
2492
+ ensureInitialized();
2493
+ return getRuntimeSnapshot().instanceDir;
2494
+ }
2495
+ /** Absolute path of the active log file, or null before it is open. */
2496
+ function logFilePath() {
2497
+ return getRuntimeSnapshot().logFile;
2498
+ }
2499
+ /** Root that contains one directory per DSH instance. */
2500
+ function logRoot() {
2501
+ ensureInitialized();
2502
+ return getRuntimeSnapshot().logRoot;
2503
+ }
2504
+ /** Identity of this DSH process (null before initialization). */
2505
+ function dshInstanceInfo() {
2506
+ return getRuntimeSnapshot();
2507
+ }
2508
+ /** Destination health, for a diagnostics/health endpoint or a support bundle. */
2509
+ function getLoggingHealth() {
2510
+ const snapshot = getRuntimeSnapshot();
2511
+ const health = snapshot.health;
2512
+ return {
2513
+ state: health ? health.state : snapshot.degradedReason !== null ? "unavailable" : snapshot.ready ? "healthy" : "initializing",
2514
+ reason: health?.reason ?? snapshot.degradedReason ?? (snapshot.ready ? "destination open" : "not initialized"),
2515
+ droppedRecords: (health?.droppedRecords ?? 0) + snapshot.droppedBeforeReady,
2516
+ rotationCount: health?.rotationCount ?? 0,
2517
+ lastError: health?.lastError ?? null,
2518
+ instanceDir: snapshot.instanceDir,
2519
+ logFile: snapshot.logFile,
2520
+ ownership: snapshot.ownership,
2521
+ degradedReason: snapshot.degradedReason
2522
+ };
2523
+ }
2524
+ /** Waits until the destination is decided. For tests and startup diagnostics. */
2525
+ function ready() {
2526
+ ensureInitialized();
2527
+ return awaitRuntimeReady();
2528
+ }
2529
+ /** Waits for all pending records (and any rotation they triggered) to land. */
2530
+ async function flushLogs() {
2531
+ if (bootPromise) await bootPromise;
2532
+ await flushRuntime();
2533
+ }
2534
+ /**
2535
+ * Final flush + close + ownership release.
2536
+ *
2537
+ * Owned by the DSH host. A plugin must NEVER call this: it would close the
2538
+ * shared destination for every other plugin in the process.
2539
+ */
2540
+ async function shutdownLogging() {
2541
+ if (bootPromise) await bootPromise;
2542
+ await shutdownRuntime();
2543
+ }
2544
+ /** Runs historical recovery/retention now (tests, or a DSH maintenance hook). */
2545
+ async function runMaintenance(options = {}) {
2546
+ ensureInitialized();
2547
+ await awaitRuntimeReady();
2548
+ await runRuntimeMaintenance(options);
2549
+ }
2550
+ /**
2551
+ * Creates the log root if it does not exist. Exposed for the DSH host's
2552
+ * startup path, which may want to validate the destination before plugins load.
2553
+ */
2554
+ function ensureLogRoot() {
2555
+ const root = currentConfig().dshLogRoot ?? getDshLogRoot(getDshIdentity()?.edgeInstanceId ?? null);
2556
+ try {
2557
+ if (!existsSync(root)) mkdirSync(root, { recursive: true });
2558
+ } catch {}
2559
+ return root;
2560
+ }
535
2561
  //#endregion
536
- export { LOG_LEVELS, REDACTED, configureLogging, flushLogs, getLogger, levelRank, logDir, logFilePath, parseLevel, redact, resetLogging };
2562
+ export { DSH_ROTATION, INSTANCE_METADATA_FILENAME, LOG_LEVELS, OWNER_LOCK_FILENAME, REDACTED, RESERVED_FIELDS, acquireDshOwnership, cleanupExpiredDshInstances, configureLogging, createLogger, dshInstanceInfo, ensureLogRoot, flushLogs, getLogger, getLoggingHealth, installHostLogSink, levelRank, logDir, logFilePath, logRoot, parseLevel, parseSize, probeDshOwnership, ready, recoverDshInstances, redact, reportLegacyPluginLogs, resetLogging, runMaintenance, shutdownLogging, todayString };