@huaqiu/dsh-plugin-log 0.3.11 → 0.3.14

package/lib/index.mjs

@@ -1,8 +1,99 @@
 import { mkdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { appendFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { homedir, platform, tmpdir } from "node:os";
 import { join } from "node:path";
-import { dshHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+//#region src/paths.ts
+/**
+* Inlined from `@hqedge/paths` (hq-edge/packages/paths/src/index.ts) so this
+* plugin stays fully self-contained — no runtime dependency on the published
+* package. Keep in sync when `@hqedge/paths` changes its path conventions.
+*
+* ────────────────────────────────────────────────────────────────────────────
+* Shared OS-native path resolution for HQ Edge runtimes.
+*
+* The single source of truth for where HQ Edge places per-user directories.
+* `getHqEdgeHome()` is the root: every other path getter (`getLogBaseDir`,
+* `getLogDir`) is derived from it, so all HQ Edge user directories live under
+* one self-contained tree and every consumer resolves the same location.
+*
+* Path conventions by platform (env-paths `data` shape, except macOS — see
+* below):
+*
+*   - macOS:   ~/.hq-edge/                                  (this override)
+*   - Linux:   ~/.local/share/hq-edge/   (honors $XDG_DATA_HOME)
+*   - Windows: %LOCALAPPDATA%\hq-edge\
+*
+* macOS deviates from `env-paths`: a dotfile under `$HOME` rather than the
+* `~/Library/Application Support/hq-edge/` sandbox location. Rationale: HQ
+* Edge is a single-developer EDA workstation tool, not a sandboxed macOS app.
+* A dotfile in `$HOME` is more discoverable (one `ls -la` shows every HQ Edge
+* user-data tree), survives sandbox / permission oddities, and aligns with the
+* historical `~/.hq` location users already had from `dshHome.ts` before this
+* unification. It also means DSH plugin code that imports `@hqedge/paths` does
+* not need to branch on platform for the macOS case.
+*/
+/**
+* Application identifier used for OS-native directories.
+*/
+const APP_ID = "hq-edge";
+/**
+* Resolves the OS-native per-user home/data directory for HQ Edge — the single
+* root from which every other HQ Edge path getter is derived.
+*
+*   - macOS:   ~/.hq-edge/                                  (override)
+*   - Linux:   ~/.local/share/hq-edge/   (honors $XDG_DATA_HOME)
+*   - Windows: %LOCALAPPDATA%\hq-edge\
+*
+* The macOS override is documented above. The path may also be overridden
+* explicitly via `override` or the `HQ_EDGE_HOME` environment variable (useful
+* for tests / bundling / portable installs).
+*/
+function getHqEdgeHome(override) {
+	if (override) return override;
+	if (process.env.HQ_EDGE_HOME) return process.env.HQ_EDGE_HOME;
+	const home = homedir();
+	if (platform() === "darwin") return join(home, ".hq-edge");
+	if (platform() === "win32") {
+		const localAppData = process.env.LOCALAPPDATA;
+		if (localAppData) return join(localAppData, APP_ID);
+		return join(home, "AppData", "Local", APP_ID);
+	}
+	const xdgDataHome = process.env.XDG_DATA_HOME;
+	return xdgDataHome ? join(xdgDataHome, APP_ID) : join(home, ".local", "share", APP_ID);
+}
+/**
+* Resolves the OS-native base log directory for HQ Edge.
+*
+* Built on top of `getHqEdgeHome()` as `<home>/logs` on every platform, so
+* logs live inside the HQ Edge home tree:
+*
+*   macOS:   ~/.hq-edge/logs/
+*   Linux:   ~/.local/share/hq-edge/logs/
+*   Windows: %LOCALAPPDATA%\hq-edge\logs\
+*
+* The path may be overridden explicitly via `override` or the
+* `HQ_EDGE_LOG_DIR` environment variable.
+*/
+function getLogBaseDir(override) {
+	if (override) return override;
+	if (process.env.HQ_EDGE_LOG_DIR) return process.env.HQ_EDGE_LOG_DIR;
+	return join(getHqEdgeHome(), "logs");
+}
+/**
+* Resolves the per-component log directory, e.g. `<base>/dsh-plugins/`.
+*
+* The directory is created on demand by the rotating file stream.
+*
+* Note: the directory name is the component verbatim — there is no implicit
+* version scoping. Callers that need version isolation (e.g. the DSH home,
+* which keeps one tree per HQ Edge release) must layer it on top of
+* `getHqEdgeHome()` themselves. Cross-version logs (server, plugin diagnostics)
+* intentionally share a tree so a single `tail -F` follows them across upgrades.
+*/
+function getLogDir(component, baseDirOverride) {
+	return join(getLogBaseDir(baseDirOverride), component);
+}
+//#endregion
 //#region src/levels.ts
 /** Levels ordered from most to least verbose. */
 const LOG_LEVELS = [
@@ -133,22 +224,27 @@ function redactString(value) {
 * temporary prints and re-run.
 *
 * This package gives every plugin one shared, file-backed, cross-platform log
-* under the DSH home:
+* inside the current HQ Edge log tree:
+*
+*   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log      (current)
+*   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log    (previous, after rotation)
+*
+* ## HQ Edge home resolution
 *
-*   <DSH_HOME>/logs/dsh-plugins.log      (current)
-*   <DSH_HOME>/logs/dsh-plugins.1.log    (previous, after rotation)
+* The directory comes from the inlined `@hqedge/paths` resolution
+* (`src/paths.ts`): the same root every HQ Edge runtime uses, so plugin logs
+* land inside the current HQ Edge log tree:
 *
-* ## DSH home resolution
+*   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log      (current)
+*   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log    (previous, after rotation)
 *
-* 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:
+* Resolution honours the same overrides as the rest of HQ Edge:
 *
-*   explicit `configure({ dir })`  >  $DSH_PLUGIN_LOG_DIR  >  $DSH_HOME  >  ~/.dsh
+*   explicit `configure({ dir })`  >  $DSH_PLUGIN_LOG_DIR  >  $HQ_EDGE_LOG_DIR / $HQ_EDGE_HOME
 *
-* 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`.
+* HQ Edge runs DSH with `HQ_EDGE_HOME` set to its own per-user data directory,
+* so plugin logs live next to the rest of that installation's state and never
+* in the user's default home.
 *
 * ## Cross-platform notes
 *
@@ -242,7 +338,7 @@ function resolveLogDir(explicit) {
 	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(getLogDir("dsh-plugins"));
 	candidates.push(join(tmpdir(), "hq-dsh-plugins", "logs"));
 	for (let i = 0; i < candidates.length; i += 1) {
 		const dir = candidates[i];
@@ -434,16 +530,16 @@ function bootstrap() {
 	s.bootstrapped = true;
 	const cfg = currentConfig();
 	const logger = createLogger("dsh-plugin-log", {});
-	let dshHome = null;
+	let hqEdgeHome = null;
 	try {
-		dshHome = resolveDshHome();
+		hqEdgeHome = getHqEdgeHome();
 	} catch {
-		dshHome = null;
+		hqEdgeHome = null;
 	}
 	logger.info("plugin log ready", {
 		logFile: join(cfg.dir, cfg.fileName),
 		logDir: cfg.dir,
-		dshHome,
+		hqEdgeHome,
 		level: cfg.level,
 		consoleLevel: cfg.consoleLevel,
 		pid: process.pid,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huaqiu/dsh-plugin-log",
-  "version": "0.3.11",
+  "version": "0.3.14",
   "type": "module",
   "main": "./lib/index.mjs",
   "types": "./lib/index.d.mts",
@@ -22,9 +22,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@deepseek-ai/dsh-home-paths": "^0.1.0-rc.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/node": "^24.0.0"
   },

package/src/index.ts

@@ -12,22 +12,27 @@
  * temporary prints and re-run.
  *
  * This package gives every plugin one shared, file-backed, cross-platform log
- * under the DSH home:
+ * inside the current HQ Edge log tree:
  *
- *   <DSH_HOME>/logs/dsh-plugins.log      (current)
- *   <DSH_HOME>/logs/dsh-plugins.1.log    (previous, after rotation)
+ *   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log      (current)
+ *   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log    (previous, after rotation)
  *
- * ## DSH home resolution
+ * ## HQ Edge 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:
+ * The directory comes from the inlined `@hqedge/paths` resolution
+ * (`src/paths.ts`): the same root every HQ Edge runtime uses, so plugin logs
+ * land inside the current HQ Edge log tree:
  *
- *   explicit `configure({ dir })`  >  $DSH_PLUGIN_LOG_DIR  >  $DSH_HOME  >  ~/.dsh
+ *   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.log      (current)
+ *   <HQ_EDGE_HOME>/logs/dsh-plugins/dsh-plugins.1.log    (previous, after rotation)
  *
- * 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`.
+ * Resolution honours the same overrides as the rest of HQ Edge:
+ *
+ *   explicit `configure({ dir })`  >  $DSH_PLUGIN_LOG_DIR  >  $HQ_EDGE_LOG_DIR / $HQ_EDGE_HOME
+ *
+ * HQ Edge runs DSH with `HQ_EDGE_HOME` set to its own per-user data directory,
+ * so plugin logs live next to the rest of that installation's state and never
+ * in the user's default home.
  *
  * ## Cross-platform notes
  *
@@ -57,7 +62,7 @@ import {
 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'
+import { getHqEdgeHome, getLogDir } from './paths.js'
 
 import { isEnabled, parseLevel, type LogLevel } from './levels.js'
 import { redact } from './redact.js'
@@ -187,9 +192,9 @@ function resolveLogDir(explicit?: string): { dir: string; fallback: boolean } {
   if (explicit !== undefined && explicit.length > 0) candidates.push(explicit)
   const fromEnv = env('DSH_PLUGIN_LOG_DIR')
   if (fromEnv) candidates.push(fromEnv)
-  // The DSH home is always a candidate, so a host that overrides DSH_HOME (HQ
-  // Edge does) gets its logs in its own tree without setting anything else.
-  candidates.push(dshHomePath('logs'))
+  // Inside the current HQ Edge log tree (honours $HQ_EDGE_HOME / $HQ_EDGE_LOG_DIR
+  // through the inlined paths resolver), so plugin logs follow the host install.
+  candidates.push(getLogDir('dsh-plugins'))
   candidates.push(join(tmpdir(), 'hq-dsh-plugins', 'logs'))
 
   for (let i = 0; i < candidates.length; i += 1) {
@@ -425,16 +430,16 @@ function bootstrap(): void {
   s.bootstrapped = true
   const cfg = currentConfig()
   const logger = createLogger('dsh-plugin-log', {})
-  let dshHome: string | null = null
+  let hqEdgeHome: string | null = null
   try {
-    dshHome = resolveDshHome()
+    hqEdgeHome = getHqEdgeHome()
   } catch {
-    dshHome = null
+    hqEdgeHome = null
   }
   logger.info('plugin log ready', {
     logFile: join(cfg.dir, cfg.fileName),
     logDir: cfg.dir,
-    dshHome,
+    hqEdgeHome,
     level: cfg.level,
     consoleLevel: cfg.consoleLevel,
     pid: process.pid,

package/src/paths.ts

@@ -0,0 +1,102 @@
+/**
+ * Inlined from `@hqedge/paths` (hq-edge/packages/paths/src/index.ts) so this
+ * plugin stays fully self-contained — no runtime dependency on the published
+ * package. Keep in sync when `@hqedge/paths` changes its path conventions.
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * Shared OS-native path resolution for HQ Edge runtimes.
+ *
+ * The single source of truth for where HQ Edge places per-user directories.
+ * `getHqEdgeHome()` is the root: every other path getter (`getLogBaseDir`,
+ * `getLogDir`) is derived from it, so all HQ Edge user directories live under
+ * one self-contained tree and every consumer resolves the same location.
+ *
+ * Path conventions by platform (env-paths `data` shape, except macOS — see
+ * below):
+ *
+ *   - macOS:   ~/.hq-edge/                                  (this override)
+ *   - Linux:   ~/.local/share/hq-edge/   (honors $XDG_DATA_HOME)
+ *   - Windows: %LOCALAPPDATA%\hq-edge\
+ *
+ * macOS deviates from `env-paths`: a dotfile under `$HOME` rather than the
+ * `~/Library/Application Support/hq-edge/` sandbox location. Rationale: HQ
+ * Edge is a single-developer EDA workstation tool, not a sandboxed macOS app.
+ * A dotfile in `$HOME` is more discoverable (one `ls -la` shows every HQ Edge
+ * user-data tree), survives sandbox / permission oddities, and aligns with the
+ * historical `~/.hq` location users already had from `dshHome.ts` before this
+ * unification. It also means DSH plugin code that imports `@hqedge/paths` does
+ * not need to branch on platform for the macOS case.
+ */
+import { homedir, platform } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * Application identifier used for OS-native directories.
+ */
+export const APP_ID = 'hq-edge'
+
+/**
+ * Resolves the OS-native per-user home/data directory for HQ Edge — the single
+ * root from which every other HQ Edge path getter is derived.
+ *
+ *   - macOS:   ~/.hq-edge/                                  (override)
+ *   - Linux:   ~/.local/share/hq-edge/   (honors $XDG_DATA_HOME)
+ *   - Windows: %LOCALAPPDATA%\hq-edge\
+ *
+ * The macOS override is documented above. The path may also be overridden
+ * explicitly via `override` or the `HQ_EDGE_HOME` environment variable (useful
+ * for tests / bundling / portable installs).
+ */
+export function getHqEdgeHome(override?: string): string {
+  if (override) return override
+  if (process.env.HQ_EDGE_HOME) return process.env.HQ_EDGE_HOME
+
+  const home = homedir()
+  // macOS override: dotfile under $HOME, not the Library sandbox.
+  // See the file header for the rationale.
+  if (platform() === 'darwin') {
+    return join(home, '.hq-edge')
+  }
+  if (platform() === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA
+    if (localAppData) return join(localAppData, APP_ID)
+    return join(home, 'AppData', 'Local', APP_ID)
+  }
+  // Linux / other POSIX — follows the XDG_DATA_HOME convention.
+  const xdgDataHome = process.env.XDG_DATA_HOME
+  return xdgDataHome ? join(xdgDataHome, APP_ID) : join(home, '.local', 'share', APP_ID)
+}
+
+/**
+ * Resolves the OS-native base log directory for HQ Edge.
+ *
+ * Built on top of `getHqEdgeHome()` as `<home>/logs` on every platform, so
+ * logs live inside the HQ Edge home tree:
+ *
+ *   macOS:   ~/.hq-edge/logs/
+ *   Linux:   ~/.local/share/hq-edge/logs/
+ *   Windows: %LOCALAPPDATA%\hq-edge\logs\
+ *
+ * The path may be overridden explicitly via `override` or the
+ * `HQ_EDGE_LOG_DIR` environment variable.
+ */
+export function getLogBaseDir(override?: string): string {
+  if (override) return override
+  if (process.env.HQ_EDGE_LOG_DIR) return process.env.HQ_EDGE_LOG_DIR
+  return join(getHqEdgeHome(), 'logs')
+}
+
+/**
+ * Resolves the per-component log directory, e.g. `<base>/dsh-plugins/`.
+ *
+ * The directory is created on demand by the rotating file stream.
+ *
+ * Note: the directory name is the component verbatim — there is no implicit
+ * version scoping. Callers that need version isolation (e.g. the DSH home,
+ * which keeps one tree per HQ Edge release) must layer it on top of
+ * `getHqEdgeHome()` themselves. Cross-version logs (server, plugin diagnostics)
+ * intentionally share a tree so a single `tail -F` follows them across upgrades.
+ */
+export function getLogDir(component: string, baseDirOverride?: string): string {
+  return join(getLogBaseDir(baseDirOverride), component)
+}