@huaqiu/dsh-plugin-log 0.3.11

package/lib/index.mjs

@@ -0,0 +1,456 @@
+import { mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { appendFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { dshHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+//#region src/levels.ts
+/** Levels ordered from most to least verbose. */
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+const RANK = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40
+};
+/** Numeric rank of a level — higher means more severe. */
+function levelRank(level) {
+	return RANK[level];
+}
+/**
+* Parse a level from an arbitrary (env-supplied) value.
+*
+* Unparseable or empty input falls back instead of throwing: a bad
+* `DSH_PLUGIN_LOG_LEVEL` in a customer environment must degrade to "log
+* normally", never to "crash the plugin host".
+*/
+function parseLevel(value, fallback) {
+	if (typeof value !== "string") return fallback;
+	const normalized = value.trim().toLowerCase();
+	return LOG_LEVELS.includes(normalized) ? normalized : fallback;
+}
+/** True when `level` is at least as severe as `threshold`. */
+function isEnabled(level, threshold) {
+	return levelRank(level) >= levelRank(threshold);
+}
+//#endregion
+//#region src/redact.ts
+/**
+* Credential redaction for `@huaqiu/dsh-plugin-log`.
+*
+* The whole point of a shared plugin log is that it is safe to hand to someone
+* else when debugging — which means it must never become a second, unmanaged
+* copy of the user's credential. Everything written through this logger goes
+* through `redact()` first, so a caller cannot leak a token by accident.
+*
+* Two rules:
+*
+*  1. **Key-based** — any field whose name looks credential-ish
+*     (`token`, `authorization`, `password`, `cookie`, `apiKey`, …) has its
+*     value replaced, at any nesting depth.
+*  2. **Shape-based** — string values that look like a bearer header or a
+*     long opaque secret are replaced even when the key is innocent
+*     (`headers: ['Authorization: Bearer ey…']`).
+*
+* Redaction is deliberately key-name based rather than "redact every long
+* string": log readability matters, and most long strings (project paths,
+* URLs, artifact ids) carry no secret.
+*/
+/** Field names whose values are always replaced. Matches at any depth. */
+const SENSITIVE_KEY = /(token|secret|password|passwd|pwd|authorization|cookie|api[-_]?key|access[-_]?key|credential)/i;
+/** `Bearer <opaque>` / `Basic <opaque>` inside a free-form string. */
+const BEARER_IN_STRING = /\b(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/i;
+/** Strings at least this long that look like a single opaque credential blob. */
+const OPAQUE_SECRET = /^[A-Za-z0-9_-]{32,}$/;
+const REDACTED = "[redacted]";
+/** Maximum object depth walked before the value is collapsed. Cycle-safe. */
+const MAX_DEPTH = 6;
+/**
+* Return a copy of `value` with credential-ish fields replaced.
+*
+* Never throws and never mutates the caller's object — a logging call must not
+* be able to change plugin state or crash the host.
+*/
+function redact(value, depth = 0) {
+	try {
+		return redactInner(value, depth, /* @__PURE__ */ new WeakSet());
+	} catch {
+		return REDACTED;
+	}
+}
+function redactInner(value, depth, seen) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "string") return redactString(value);
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return value;
+	if (typeof value === "function") return "[function]";
+	if (typeof value === "symbol") return value.toString();
+	if (value instanceof Error) return {
+		name: value.name,
+		message: redactString(value.message),
+		...value.stack ? { stack: value.stack } : {}
+	};
+	if (value instanceof Date) return value.toISOString();
+	if (depth >= MAX_DEPTH) return "[deep]";
+	if (seen.has(value)) return "[circular]";
+	if (Array.isArray(value)) {
+		seen.add(value);
+		const out = value.map((item) => redactInner(item, depth + 1, seen));
+		seen.delete(value);
+		return out;
+	}
+	if (typeof value === "object") {
+		seen.add(value);
+		const out = {};
+		for (const [key, raw] of Object.entries(value)) out[key] = SENSITIVE_KEY.test(key) ? REDACTED : redactInner(raw, depth + 1, seen);
+		seen.delete(value);
+		return out;
+	}
+	return String(value);
+}
+/** Redact credentials embedded in an otherwise ordinary string. */
+function redactString(value) {
+	if (BEARER_IN_STRING.test(value)) return value.replace(BEARER_IN_STRING, "$1 " + REDACTED);
+	if (OPAQUE_SECRET.test(value)) return REDACTED;
+	return value;
+}
+//#endregion
+//#region src/index.ts
+/**
+* `@huaqiu/dsh-plugin-log` — one server-side log for every Huaqiu DSH plugin.
+*
+* ## Why this exists
+*
+* Plugin diagnostics used to live only in the browser console: each plugin's
+* browser half logged to `console.*`, and the node half — the half that
+* actually owns credentials, HTTP routes and agent tools — logged nothing at
+* all outside the DSH process's stdout, which HQ Edge only captures as an
+* opaque text blob. When a `deepseek-harness` upgrade broke credential
+* propagation, the only way to see what the node half resolved was to add
+* temporary prints and re-run.
+*
+* This package gives every plugin one shared, file-backed, cross-platform log
+* under the DSH home:
+*
+*   <DSH_HOME>/logs/dsh-plugins.log      (current)
+*   <DSH_HOME>/logs/dsh-plugins.1.log    (previous, after rotation)
+*
+* ## DSH home resolution
+*
+* The directory comes from `@deepseek-ai/dsh-home-paths`, the same single-root
+* helper the rest of DSH uses, so every override HQ Edge (or any other host)
+* performs is honoured for free:
+*
+*   explicit `configure({ dir })`  >  $DSH_PLUGIN_LOG_DIR  >  $DSH_HOME  >  ~/.dsh
+*
+* HQ Edge spawns DSH with `DSH_HOME` pointing at its own versioned, per-user
+* data directory (`…/HQ/hq-edge/<ver>/dsh-home`), so plugin logs land next to
+* the rest of that installation's state and never in the user's `~/.dsh`.
+*
+* ## Cross-platform notes
+*
+*  - Pure `node:fs` / `node:os` / `node:path` — no native modules, no shelling
+*    out, nothing that differs between macOS, Linux and Windows but the path
+*    separators (handled by `node:path`).
+*  - Rotation uses unlink-then-rename, because Windows cannot rename over an
+*    existing file.
+*  - File names never embed `:` or other Windows-illegal characters.
+*  - If the log directory cannot be created (read-only install, locked-down
+*    profile) we fall back to the OS temp dir, and if that also fails we keep
+*    logging to the console. A logging failure must never take a plugin down.
+*
+* ## Safety
+*
+*  - Every field passes through `redact()`: credential-shaped keys and values
+*    are replaced with `[redacted]`, so the log is safe to share.
+*  - `getLogger()` never throws. Neither does any log call.
+*/
+const DEFAULT_FILE_NAME = "dsh-plugins.log";
+const DEFAULT_MAX_BYTES = 5242880;
+const DEFAULT_MAX_FILES = 4;
+const DEFAULT_LEVEL = "info";
+const DEFAULT_CONSOLE_LEVEL = "warn";
+/**
+* Process-wide logger state, held on `globalThis`.
+*
+* Plugins are built independently, so each one gets its OWN bundled copy of
+* this module. Without a shared home, "one unified log" would degrade into one
+* sink (and one rotation counter) per plugin. Keying the state off a
+* `Symbol.for` on `globalThis` makes every copy — bundled, external, or
+* duplicated across installs — cooperate inside the same DSH process.
+*/
+const STATE_KEY = Symbol.for("@huaqiu/dsh-plugin-log/state");
+function state() {
+	const g = globalThis;
+	const existing = g[STATE_KEY];
+	if (existing) return existing;
+	const fresh = {
+		override: null,
+		resolved: null,
+		sink: null,
+		bootstrapped: false
+	};
+	g[STATE_KEY] = fresh;
+	return fresh;
+}
+const getOverride = () => state().override;
+const setOverride = (value) => {
+	state().override = value;
+};
+const getSink = () => state().sink;
+const setSink = (value) => {
+	state().sink = value;
+};
+/**
+* Programmatically configure logging. Call before the first `getLogger()`;
+* later calls take effect on the next `resetLogging()` (tests, host re-init).
+*/
+function configureLogging(options) {
+	setOverride({
+		...getOverride() ?? {},
+		...options
+	});
+	state().resolved = null;
+}
+/** Forget all configuration and cached loggers. Test/teardown helper. */
+function resetLogging() {
+	const s = state();
+	s.override = null;
+	s.resolved = null;
+	s.sink = null;
+	s.bootstrapped = false;
+}
+function env(name) {
+	const value = process.env[name];
+	return value !== void 0 && value.trim().length > 0 ? value.trim() : void 0;
+}
+function readInt(value, fallback) {
+	if (value === void 0) return fallback;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+/**
+* Pick the log directory, honouring every override in precedence order.
+* Falls back to the OS temp directory when the DSH home is not writable — a
+* plugin that cannot log to its preferred location still logs somewhere.
+*/
+function resolveLogDir(explicit) {
+	const candidates = [];
+	if (explicit !== void 0 && explicit.length > 0) candidates.push(explicit);
+	const fromEnv = env("DSH_PLUGIN_LOG_DIR");
+	if (fromEnv) candidates.push(fromEnv);
+	candidates.push(dshHomePath("logs"));
+	candidates.push(join(tmpdir(), "hq-dsh-plugins", "logs"));
+	for (let i = 0; i < candidates.length; i += 1) {
+		const dir = candidates[i];
+		if (!dir) continue;
+		try {
+			mkdirSync(dir, { recursive: true });
+			return {
+				dir,
+				fallback: i > 0
+			};
+		} catch {}
+	}
+	return {
+		dir: candidates[candidates.length - 1] ?? ".",
+		fallback: true
+	};
+}
+function currentConfig() {
+	const s = state();
+	if (s.resolved) return s.resolved;
+	const o = s.override;
+	const { dir } = resolveLogDir(o?.dir);
+	const consoleRaw = o?.consoleLevel ?? env("DSH_PLUGIN_LOG_CONSOLE");
+	s.resolved = {
+		dir,
+		fileName: o?.fileName ?? env("DSH_PLUGIN_LOG_FILE") ?? DEFAULT_FILE_NAME,
+		level: o?.level ?? parseLevel(env("DSH_PLUGIN_LOG_LEVEL"), DEFAULT_LEVEL),
+		consoleLevel: o?.consoleLevel === "off" ? "off" : consoleRaw === "off" || consoleRaw === "none" || consoleRaw === "0" ? "off" : consoleRaw === "all" || consoleRaw === "1" || consoleRaw === "true" ? "debug" : parseLevel(consoleRaw, DEFAULT_CONSOLE_LEVEL),
+		maxBytes: o?.maxBytes ?? readInt(env("DSH_PLUGIN_LOG_MAX_BYTES"), DEFAULT_MAX_BYTES),
+		maxFiles: o?.maxFiles ?? readInt(env("DSH_PLUGIN_LOG_MAX_FILES"), DEFAULT_MAX_FILES)
+	};
+	return s.resolved;
+}
+/** Absolute path of the current log file, or `null` before first use. */
+function logFilePath() {
+	const s = getSink();
+	return s ? s.path : null;
+}
+/** Absolute directory plugin logs are written to. */
+function logDir() {
+	return currentConfig().dir;
+}
+/**
+* Serialized appender with size-based rotation.
+*
+* Writes are chained on a single promise so concurrent log calls from different
+* plugins in the same process can never interleave or race the rotation.
+*/
+var FileSink = class {
+	dir;
+	fileName;
+	maxBytes;
+	maxFiles;
+	path;
+	queue = Promise.resolve();
+	bytes;
+	constructor(dir, fileName, maxBytes, maxFiles) {
+		this.dir = dir;
+		this.fileName = fileName;
+		this.maxBytes = maxBytes;
+		this.maxFiles = maxFiles;
+		this.path = join(dir, fileName);
+		this.bytes = this.currentSize();
+	}
+	currentSize() {
+		try {
+			return statSync(this.path).size;
+		} catch {
+			return 0;
+		}
+	}
+	/** Rotate when appending `next` bytes would exceed the cap. */
+	rotateIfNeeded(next) {
+		if (this.maxBytes <= 0) return;
+		if (this.bytes + next <= this.maxBytes) return;
+		try {
+			for (let i = this.maxFiles - 1; i >= 1; i -= 1) {
+				const from = i === 1 ? join(this.dir, this.fileName) : this.rotated(i - 1);
+				const to = this.rotated(i);
+				if (!exists(from)) continue;
+				if (exists(to)) rmSync(to, { force: true });
+				renameSync(from, to);
+			}
+			this.bytes = this.currentSize();
+		} catch {}
+	}
+	rotated(index) {
+		const dot = this.fileName.lastIndexOf(".");
+		const stem = dot > 0 ? this.fileName.slice(0, dot) : this.fileName;
+		const ext = dot > 0 ? this.fileName.slice(dot) : "";
+		return join(this.dir, `${stem}.${index}${ext}`);
+	}
+	/** Enqueue one already-serialized line. Never rejects. */
+	write(line) {
+		const size = Buffer.byteLength(line, "utf8");
+		this.bytes += size;
+		this.queue = this.queue.then(async () => {
+			this.rotateIfNeeded(size);
+			await appendFile(this.path, line, "utf8");
+		}).catch(() => {});
+	}
+	/** Wait for everything enqueued so far to reach the file. */
+	flush() {
+		return this.queue;
+	}
+};
+function exists(path) {
+	try {
+		statSync(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function currentSink() {
+	const existing = getSink();
+	if (existing) return existing;
+	const cfg = currentConfig();
+	const created = new FileSink(cfg.dir, cfg.fileName, cfg.maxBytes, cfg.maxFiles);
+	setSink(created);
+	return created;
+}
+/** Wait for all pending writes to land (shutdown hooks, tests). */
+async function flushLogs() {
+	await getSink()?.flush();
+}
+function consoleMethod(level) {
+	if (level === "error") return "error";
+	if (level === "warn") return "warn";
+	if (level === "info") return "info";
+	return "log";
+}
+function createLogger(component, defaults) {
+	const emit = (level, message, fields) => {
+		try {
+			const cfg = currentConfig();
+			if (!isEnabled(level, cfg.level) && !(cfg.consoleLevel !== "off" && isEnabled(level, cfg.consoleLevel))) return;
+			const record = {
+				ts: (/* @__PURE__ */ new Date()).toISOString(),
+				level,
+				component,
+				pid: process.pid,
+				msg: message
+			};
+			if (Object.keys(defaults).length > 0) Object.assign(record, defaults);
+			if (fields && Object.keys(fields).length > 0) Object.assign(record, fields);
+			const safe = redact(record);
+			if (isEnabled(level, cfg.level)) currentSink().write(`${JSON.stringify(safe)}\n`);
+			if (cfg.consoleLevel !== "off" && isEnabled(level, cfg.consoleLevel)) {
+				const { msg, ...rest } = safe;
+				console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest);
+			}
+		} catch {}
+	};
+	return {
+		component,
+		debug: (message, fields) => emit("debug", message, fields),
+		info: (message, fields) => emit("info", message, fields),
+		warn: (message, fields) => emit("warn", message, fields),
+		error: (message, fields) => emit("error", message, fields),
+		child: (fields) => createLogger(component, {
+			...defaults,
+			...fields
+		})
+	};
+}
+/**
+* Get (or create) the logger for `component`.
+*
+* `component` should be the short plugin name used everywhere else in its
+* output — `dsh-auth`, `dsh-artifacts`, `dsh-schematic-gen` — so the unified
+* file can be filtered with a single grep.
+*/
+function getLogger(component, defaults = {}) {
+	bootstrap();
+	return createLogger(component, defaults);
+}
+/**
+* Write one record describing where this process is logging.
+*
+* This is the line that makes the next "we upgraded deepseek-harness and
+* something stopped syncing" investigation cheap: it pins the DSH home, the
+* resolved log file, the platform and the DSH/plugin versions in use at the
+* moment the first plugin touched the log.
+*/
+function bootstrap() {
+	const s = state();
+	if (s.bootstrapped) return;
+	s.bootstrapped = true;
+	const cfg = currentConfig();
+	const logger = createLogger("dsh-plugin-log", {});
+	let dshHome = null;
+	try {
+		dshHome = resolveDshHome();
+	} catch {
+		dshHome = null;
+	}
+	logger.info("plugin log ready", {
+		logFile: join(cfg.dir, cfg.fileName),
+		logDir: cfg.dir,
+		dshHome,
+		level: cfg.level,
+		consoleLevel: cfg.consoleLevel,
+		pid: process.pid,
+		node: process.version,
+		platform: process.platform,
+		arch: process.arch
+	});
+}
+//#endregion
+export { LOG_LEVELS, REDACTED, configureLogging, flushLogs, getLogger, levelRank, logDir, logFilePath, parseLevel, redact, resetLogging };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@huaqiu/dsh-plugin-log",
+  "version": "0.3.11",
+  "type": "module",
+  "main": "./lib/index.mjs",
+  "types": "./lib/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.mts",
+      "default": "./lib/index.mjs"
+    },
+    "./client": {
+      "types": "./lib/client.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,94 @@
+/**
+ * `@huaqiu/dsh-plugin-log/client` — browser half of the shared plugin log.
+ *
+ * The browser has no filesystem, so there is nothing to unify: this module
+ * keeps the *same* `PluginLogger` surface as the node half (so a plugin can log
+ * identically from either half) but writes to the console with a stable
+ * `[component] message` prefix and a structured payload as the second
+ * argument — which is what the existing client-side debugging already relies on.
+ *
+ * It also keeps a small in-memory ring of the most recent records. That costs
+ * nothing and gives a user something to copy out of the devtools console
+ * (`dumpPluginLogs()`) when a file is not available.
+ *
+ * Redaction is shared with the node half, so a credential can never reach the
+ * browser console through this logger either.
+ */
+
+import { isEnabled, parseLevel, type LogLevel } from './levels.js'
+import { redact } from './redact.js'
+
+export type { LogLevel } from './levels.js'
+export type LogFields = Record<string, unknown>
+
+export interface PluginLogger {
+  readonly component: string
+  debug(message: string, fields?: LogFields): void
+  info(message: string, fields?: LogFields): void
+  warn(message: string, fields?: LogFields): void
+  error(message: string, fields?: LogFields): void
+  child(fields: LogFields): PluginLogger
+}
+
+/** Most recent records kept in memory for `dumpPluginLogs()`. */
+const RING_SIZE = 200
+const ring: Array<Record<string, unknown>> = []
+
+const DEFAULT_LEVEL: LogLevel = 'debug'
+
+function currentLevel(): LogLevel {
+  const global = globalThis as { DSH_PLUGIN_LOG_LEVEL?: string }
+  return parseLevel(global.DSH_PLUGIN_LOG_LEVEL, DEFAULT_LEVEL)
+}
+
+function consoleMethod(level: LogLevel): 'log' | 'info' | 'warn' | 'error' {
+  if (level === 'error') return 'error'
+  if (level === 'warn') return 'warn'
+  if (level === 'info') return 'info'
+  return 'log'
+}
+
+function createLogger(component: string, defaults: LogFields): PluginLogger {
+  const emit = (level: LogLevel, message: string, fields?: LogFields): void => {
+    try {
+      if (!isEnabled(level, currentLevel())) return
+      const record: Record<string, unknown> = {
+        ts: new Date().toISOString(),
+        level,
+        component,
+        msg: message,
+      }
+      if (Object.keys(defaults).length > 0) Object.assign(record, defaults)
+      if (fields && Object.keys(fields).length > 0) Object.assign(record, fields)
+
+      const safe = redact(record) as Record<string, unknown>
+      ring.push(safe)
+      if (ring.length > RING_SIZE) ring.shift()
+
+      const { msg, ...rest } = safe
+      // eslint-disable-next-line no-console
+      console[consoleMethod(level)](`[${component}] ${String(msg)}`, rest)
+    } catch {
+      /* logging must never throw */
+    }
+  }
+
+  return {
+    component,
+    debug: (message, fields) => emit('debug', message, fields),
+    info: (message, fields) => emit('info', message, fields),
+    warn: (message, fields) => emit('warn', message, fields),
+    error: (message, fields) => emit('error', message, fields),
+    child: (fields) => createLogger(component, { ...defaults, ...fields }),
+  }
+}
+
+/** Get (or create) the browser logger for `component`. */
+export function getLogger(component: string, defaults: LogFields = {}): PluginLogger {
+  return createLogger(component, defaults)
+}
+
+/** Snapshot of the in-memory ring — handy from the devtools console. */
+export function dumpPluginLogs(): Array<Record<string, unknown>> {
+  return ring.slice()
+}