@huaqiu/dsh-plugin-log 0.3.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深圳华秋智联股份有限公司
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/client.d.ts

@@ -0,0 +1,26 @@
+//#region src/levels.d.ts
+/**
+ * Log levels for `@huaqiu/dsh-plugin-log`.
+ *
+ * Four levels only — enough to separate "noise while debugging" from "someone
+ * must look at this", and few enough that a reader of the log file can filter
+ * with a single grep.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+//#endregion
+//#region src/client.d.ts
+type LogFields = Record<string, unknown>;
+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;
+}
+/** Get (or create) the browser logger for `component`. */
+declare function getLogger(component: string, defaults?: LogFields): PluginLogger;
+/** Snapshot of the in-memory ring — handy from the devtools console. */
+declare function dumpPluginLogs(): Array<Record<string, unknown>>;
+//#endregion
+export { LogFields, type LogLevel, PluginLogger, dumpPluginLogs, getLogger };

package/lib/client.js

@@ -0,0 +1,186 @@
+//#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/client.ts
+/**
+* `@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.
+*/
+/** Most recent records kept in memory for `dumpPluginLogs()`. */
+const RING_SIZE = 200;
+const ring = [];
+const DEFAULT_LEVEL = "debug";
+function currentLevel() {
+	return parseLevel(globalThis.DSH_PLUGIN_LOG_LEVEL, DEFAULT_LEVEL);
+}
+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 {
+			if (!isEnabled(level, currentLevel())) return;
+			const record = {
+				ts: (/* @__PURE__ */ 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);
+			ring.push(safe);
+			if (ring.length > RING_SIZE) ring.shift();
+			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 browser logger for `component`. */
+function getLogger(component, defaults = {}) {
+	return createLogger(component, defaults);
+}
+/** Snapshot of the in-memory ring — handy from the devtools console. */
+function dumpPluginLogs() {
+	return ring.slice();
+}
+//#endregion
+export { dumpPluginLogs, getLogger };

package/lib/index.d.mts

@@ -0,0 +1,107 @@
+//#region src/levels.d.ts
+/**
+ * Log levels for `@huaqiu/dsh-plugin-log`.
+ *
+ * Four levels only — enough to separate "noise while debugging" from "someone
+ * must look at this", and few enough that a reader of the log file can filter
+ * with a single grep.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Levels ordered from most to least verbose. */
+declare const LOG_LEVELS: readonly LogLevel[];
+/** Numeric rank of a level — higher means more severe. */
+declare function levelRank(level: LogLevel): number;
+/**
+ * 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".
+ */
+declare function parseLevel(value: unknown, fallback: LogLevel): LogLevel;
+//#endregion
+//#region src/redact.d.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.
+ */
+declare const REDACTED = "[redacted]";
+/**
+ * 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.
+ */
+declare function redact(value: unknown, depth?: number): unknown;
+//#endregion
+//#region src/index.d.ts
+/** Arbitrary structured context attached to a log record. */
+type LogFields = Record<string, unknown>;
+/** The logger surface every plugin codes against. */
+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;
+  /** Derive a logger that always carries `fields`. */
+  child(fields: LogFields): PluginLogger;
+}
+interface LoggingOptions {
+  /** Override the log directory (highest precedence, beats every env var). */
+  dir?: string;
+  /** Base file name inside the directory. Default `dsh-plugins.log`. */
+  fileName?: string;
+  /** Minimum file level. Default from `$DSH_PLUGIN_LOG_LEVEL`, else `info`. */
+  level?: LogLevel;
+  /**
+   * Minimum level mirrored to the console. HQ Edge captures DSH's stdout, so
+   * this is how a plugin surfaces a problem without anyone opening a file.
+   * Default from `$DSH_PLUGIN_LOG_CONSOLE`, else `warn`.
+   */
+  consoleLevel?: LogLevel | 'off';
+  /** Rotate once the current file exceeds this many bytes. Default 5 MiB. */
+  maxBytes?: number;
+  /** Number of files kept (current + rotated). Default 4. */
+  maxFiles?: number;
+}
+/**
+ * Programmatically configure logging. Call before the first `getLogger()`;
+ * later calls take effect on the next `resetLogging()` (tests, host re-init).
+ */
+declare function configureLogging(options: LoggingOptions): void;
+/** Forget all configuration and cached loggers. Test/teardown helper. */
+declare function resetLogging(): void;
+/** Absolute path of the current log file, or `null` before first use. */
+declare function logFilePath(): string | null;
+/** Absolute directory plugin logs are written to. */
+declare function logDir(): string;
+/** Wait for all pending writes to land (shutdown hooks, tests). */
+declare function flushLogs(): Promise<void>;
+/**
+ * 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.
+ */
+declare function getLogger(component: string, defaults?: LogFields): PluginLogger;
+//#endregion
+export { LOG_LEVELS, LogFields, type LogLevel, LoggingOptions, PluginLogger, REDACTED, configureLogging, flushLogs, getLogger, levelRank, logDir, logFilePath, parseLevel, redact, resetLogging };