@huaqiu/dsh-plugin-log 0.4.4 → 0.4.6

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.
Files changed (3) hide show
  1. package/lib/index.mjs +26 -42
  2. package/package.json +1 -1
  3. package/src/paths.ts +25 -42
package/lib/index.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  import { mkdirSync, renameSync, rmSync, statSync } from "node:fs";
2
2
  import { appendFile } from "node:fs/promises";
3
- import { homedir, platform, tmpdir } from "node:os";
3
+ import { homedir, tmpdir } from "node:os";
4
4
  import { join } from "node:path";
5
5
  //#region src/paths.ts
6
6
  /**
@@ -9,67 +9,51 @@ import { join } from "node:path";
9
9
  * package. Keep in sync when `@hqedge/paths` changes its path conventions.
10
10
  *
11
11
  * ────────────────────────────────────────────────────────────────────────────
12
- * Shared OS-native path resolution for HQ Edge runtimes.
12
+ * Shared path resolution for HQ Edge runtimes.
13
13
  *
14
14
  * The single source of truth for where HQ Edge places per-user directories.
15
15
  * `getHqEdgeHome()` is the root: every other path getter (`getLogBaseDir`,
16
16
  * `getLogDir`) is derived from it, so all HQ Edge user directories live under
17
17
  * one self-contained tree and every consumer resolves the same location.
18
18
  *
19
- * Path conventions by platform (env-paths `data` shape, except macOS — see
20
- * below):
21
- *
22
- * - macOS: ~/.hq-edge/ (this override)
23
- * - Linux: ~/.local/share/hq-edge/ (honors $XDG_DATA_HOME)
24
- * - Windows: %LOCALAPPDATA%\hq-edge\
25
- *
26
- * macOS deviates from `env-paths`: a dotfile under `$HOME` rather than the
27
- * `~/Library/Application Support/hq-edge/` sandbox location. Rationale: HQ
28
- * Edge is a single-developer EDA workstation tool, not a sandboxed macOS app.
29
- * A dotfile in `$HOME` is more discoverable (one `ls -la` shows every HQ Edge
30
- * user-data tree), survives sandbox / permission oddities, and aligns with the
31
- * historical `~/.hq` location users already had from `dshHome.ts` before this
32
- * unification. It also means DSH plugin code that imports `@hqedge/paths` does
33
- * not need to branch on platform for the macOS case.
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
34
  */
35
35
  /**
36
- * Application identifier used for OS-native directories.
37
- */
38
- const APP_ID = "hq-edge";
39
- /**
40
- * Resolves the OS-native per-user home/data directory for HQ Edge — the single
41
- * root from which every other HQ Edge path getter is derived.
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.
42
38
  *
43
- * - macOS: ~/.hq-edge/ (override)
44
- * - Linux: ~/.local/share/hq-edge/ (honors $XDG_DATA_HOME)
45
- * - Windows: %LOCALAPPDATA%\hq-edge\
39
+ * macOS / Linux / Windows: ~/.hq-edge/
46
40
  *
47
- * The macOS override is documented above. The path may also be overridden
48
- * explicitly via `override` or the `HQ_EDGE_HOME` environment variable (useful
49
- * for tests / bundling / portable installs).
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).
50
44
  */
51
45
  function getHqEdgeHome(override) {
52
46
  if (override) return override;
53
47
  if (process.env.HQ_EDGE_HOME) return process.env.HQ_EDGE_HOME;
54
- const home = homedir();
55
- if (platform() === "darwin") return join(home, ".hq-edge");
56
- if (platform() === "win32") {
57
- const localAppData = process.env.LOCALAPPDATA;
58
- if (localAppData) return join(localAppData, APP_ID);
59
- return join(home, "AppData", "Local", APP_ID);
60
- }
61
- const xdgDataHome = process.env.XDG_DATA_HOME;
62
- return xdgDataHome ? join(xdgDataHome, APP_ID) : join(home, ".local", "share", APP_ID);
48
+ return join(homedir(), ".hq-edge");
63
49
  }
64
50
  /**
65
- * Resolves the OS-native base log directory for HQ Edge.
51
+ * Resolves the base log directory for HQ Edge.
66
52
  *
67
53
  * Built on top of `getHqEdgeHome()` as `<home>/logs` on every platform, so
68
54
  * logs live inside the HQ Edge home tree:
69
55
  *
70
- * macOS: ~/.hq-edge/logs/
71
- * Linux: ~/.local/share/hq-edge/logs/
72
- * Windows: %LOCALAPPDATA%\hq-edge\logs\
56
+ * macOS / Linux / Windows: ~/.hq-edge/logs/
73
57
  *
74
58
  * The path may be overridden explicitly via `override` or the
75
59
  * `HQ_EDGE_LOG_DIR` environment variable.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@huaqiu/dsh-plugin-log",
3
- "version": "0.4.4",
3
+ "version": "0.4.6",
4
4
  "type": "module",
5
5
  "main": "./lib/index.mjs",
6
6
  "types": "./lib/index.d.mts",
package/src/paths.ts CHANGED
@@ -4,30 +4,30 @@
4
4
  * package. Keep in sync when `@hqedge/paths` changes its path conventions.
5
5
  *
6
6
  * ────────────────────────────────────────────────────────────────────────────
7
- * Shared OS-native path resolution for HQ Edge runtimes.
7
+ * Shared path resolution for HQ Edge runtimes.
8
8
  *
9
9
  * The single source of truth for where HQ Edge places per-user directories.
10
10
  * `getHqEdgeHome()` is the root: every other path getter (`getLogBaseDir`,
11
11
  * `getLogDir`) is derived from it, so all HQ Edge user directories live under
12
12
  * one self-contained tree and every consumer resolves the same location.
13
13
  *
14
- * Path conventions by platform (env-paths `data` shape, except macOS — see
15
- * below):
14
+ * The home is **the same on every platform** — `~/.hq-edge/` — because HQ Edge
15
+ * is a developer/EDA runtime environment rather than a conventional desktop
16
+ * app: a single dotfile under `$HOME` keeps logging, diagnostics, DSH
17
+ * integration, CLI behavior and documentation identical on macOS / Linux /
18
+ * Windows, instead of introducing a second filesystem convention
19
+ * (`%LOCALAPPDATA%\hq-edge` or `~/.local/share/hq-edge`) per platform.
20
+ * `HQ_EDGE_HOME` is the universal escape hatch (tests, bundling, portable
21
+ * installs, CI).
16
22
  *
17
- * - macOS: ~/.hq-edge/ (this override)
18
- * - Linux: ~/.local/share/hq-edge/ (honors $XDG_DATA_HOME)
19
- * - Windows: %LOCALAPPDATA%\hq-edge\
20
- *
21
- * macOS deviates from `env-paths`: a dotfile under `$HOME` rather than the
22
- * `~/Library/Application Support/hq-edge/` sandbox location. Rationale: HQ
23
- * Edge is a single-developer EDA workstation tool, not a sandboxed macOS app.
24
- * A dotfile in `$HOME` is more discoverable (one `ls -la` shows every HQ Edge
25
- * user-data tree), survives sandbox / permission oddities, and aligns with the
26
- * historical `~/.hq` location users already had from `dshHome.ts` before this
27
- * unification. It also means DSH plugin code that imports `@hqedge/paths` does
28
- * not need to branch on platform for the macOS case.
23
+ * Note: the immutable HQ Edge runtime (`<installRoot>/dsh`,
24
+ * `<installRoot>/dsh-plugins`) and `<KiCad installation>/` (application
25
+ * install) are deliberately NOT this home — user data, managed runtime and
26
+ * installation stay distinct. Mutable per-version DSH state lives UNDER this
27
+ * home at `<home>/<version>/dsh-home` (see dshHome.ts). The
28
+ * `~/.hq/hq-edge/<version>/` path from an earlier design draft never landed.
29
29
  */
30
- import { homedir, platform } from 'node:os'
30
+ import { homedir } from 'node:os'
31
31
  import { join } from 'node:path'
32
32
 
33
33
  /**
@@ -36,46 +36,29 @@ import { join } from 'node:path'
36
36
  export const APP_ID = 'hq-edge'
37
37
 
38
38
  /**
39
- * Resolves the OS-native per-user home/data directory for HQ Edge — the single
40
- * root from which every other HQ Edge path getter is derived.
39
+ * Resolves the per-user data home directory for HQ Edge — the single root from
40
+ * which every other HQ Edge path getter is derived.
41
41
  *
42
- * - macOS: ~/.hq-edge/ (override)
43
- * - Linux: ~/.local/share/hq-edge/ (honors $XDG_DATA_HOME)
44
- * - Windows: %LOCALAPPDATA%\hq-edge\
42
+ * macOS / Linux / Windows: ~/.hq-edge/
45
43
  *
46
- * The macOS override is documented above. The path may also be overridden
47
- * explicitly via `override` or the `HQ_EDGE_HOME` environment variable (useful
48
- * for tests / bundling / portable installs).
44
+ * Unconditional across platforms (see the file header for the rationale). The
45
+ * path may be overridden explicitly via `override` or the `HQ_EDGE_HOME`
46
+ * environment variable (useful for tests / bundling / portable installs).
49
47
  */
50
48
  export function getHqEdgeHome(override?: string): string {
51
49
  if (override) return override
52
50
  if (process.env.HQ_EDGE_HOME) return process.env.HQ_EDGE_HOME
53
51
 
54
- const home = homedir()
55
- // macOS override: dotfile under $HOME, not the Library sandbox.
56
- // See the file header for the rationale.
57
- if (platform() === 'darwin') {
58
- return join(home, '.hq-edge')
59
- }
60
- if (platform() === 'win32') {
61
- const localAppData = process.env.LOCALAPPDATA
62
- if (localAppData) return join(localAppData, APP_ID)
63
- return join(home, 'AppData', 'Local', APP_ID)
64
- }
65
- // Linux / other POSIX — follows the XDG_DATA_HOME convention.
66
- const xdgDataHome = process.env.XDG_DATA_HOME
67
- return xdgDataHome ? join(xdgDataHome, APP_ID) : join(home, '.local', 'share', APP_ID)
52
+ return join(homedir(), '.hq-edge')
68
53
  }
69
54
 
70
55
  /**
71
- * Resolves the OS-native base log directory for HQ Edge.
56
+ * Resolves the base log directory for HQ Edge.
72
57
  *
73
58
  * Built on top of `getHqEdgeHome()` as `<home>/logs` on every platform, so
74
59
  * logs live inside the HQ Edge home tree:
75
60
  *
76
- * macOS: ~/.hq-edge/logs/
77
- * Linux: ~/.local/share/hq-edge/logs/
78
- * Windows: %LOCALAPPDATA%\hq-edge\logs\
61
+ * macOS / Linux / Windows: ~/.hq-edge/logs/
79
62
  *
80
63
  * The path may be overridden explicitly via `override` or the
81
64
  * `HQ_EDGE_LOG_DIR` environment variable.