@ac-kit/app-system 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @ac-kit/app-system
 
+## 0.2.0
+
+### Minor Changes
+
+- 6cce28a: `getXdgBaseDirectories` resolves the XDG Base Directory specification's data,
+  configuration, state, cache, executable and runtime directories and search
+  lists, ignoring the empty and relative values the specification rules out.
+
+### Patch Changes
+
+- Updated dependencies [aca1cb1]
+  - @ac-kit/core@0.4.0
+  - @ac-kit/app-report@0.1.3
+  - @ac-kit/async@0.1.3
+  - @ac-kit/crypto-hash@0.1.3
+  - @ac-kit/data@0.1.3
+  - @ac-kit/format-ansi@0.1.3
+  - @ac-kit/format-shell@0.1.2
+  - @ac-kit/node@0.3.1
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [a5c4d66]
+- Updated dependencies [a5c4d66]
+- Updated dependencies [a5c4d66]
+  - @ac-kit/node@0.3.0
+  - @ac-kit/core@0.3.0
+  - @ac-kit/async@0.1.2
+  - @ac-kit/format-ansi@0.1.2
+  - @ac-kit/app-report@0.1.2
+  - @ac-kit/crypto-hash@0.1.2
+  - @ac-kit/data@0.1.2
+  - @ac-kit/format-shell@0.1.1
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -33,7 +33,8 @@ teardown order is declared rather than implied by registration order.
 - **Process inspection** — `ps` with filters, `getProcessesSnapshot`,
   `hostMetrics`, and `sysfs` readers.
 - **Files** — `rotateLogFiles`, `RotatingFileSink` (optionally gzip-compressed),
-  and an artifact cache.
+  an artifact cache, and `getXdgBaseDirectories` for where an application keeps
+  its data, configuration, state and cache.
 - **Locks** — `FileLock` and `UdpBindLock`, for single-instance enforcement.
 - **Terminal and text** — `nodeTerminal`, the Node adapter for
   `@ac-kit/app-terminal`'s `Terminal`, plus charset encode/decode streams.
@@ -41,5 +42,5 @@ teardown order is declared rather than implied by registration order.
 Node only, by definition: this is the host-bound layer.
 
 See the
-[generated API docs](https://anthochamp.github.io/node-essentials/api/app-system/)
+[generated API docs](https://anthochamp.pages.grenadine.io/node-essentials/api/app-system/)
 for the full reference.

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./os/process-kill-by-pid-file.js";
 export * from "./os/process-wait-pid.js";
 export * from "./os/ps.js";
 export * from "./os/sysfs.js";
+export * from "./os/xdg-base-directories.js";
 export * from "./process/child-process-message-sink.js";
 export * from "./process/error-listeners.js";
 export * from "./process/exit-manager.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC"}

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./os/process-kill-by-pid-file.js";
 export * from "./os/process-wait-pid.js";
 export * from "./os/ps.js";
 export * from "./os/sysfs.js";
+export * from "./os/xdg-base-directories.js";
 export * from "./process/child-process-message-sink.js";
 export * from "./process/error-listeners.js";
 export * from "./process/exit-manager.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yCAAyC,CAAC;AACxD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC"}

package/dist/os/xdg-base-directories.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Where an application keeps its files, per the XDG Base Directory
+ * specification.
+ */
+export type XdgBaseDirectories = {
+    /** `$XDG_DATA_HOME`: user data files, `~/.local/share` by default. */
+    dataHome: string;
+    /** `$XDG_CONFIG_HOME`: user configuration, `~/.config` by default. */
+    configHome: string;
+    /**
+     * `$XDG_STATE_HOME`: state worth keeping across restarts but not backing up —
+     * logs, history — `~/.local/state` by default.
+     */
+    stateHome: string;
+    /** `$XDG_CACHE_HOME`: non-essential cached data, `~/.cache` by default. */
+    cacheHome: string;
+    /**
+     * `~/.local/bin`: user executables. The specification names no variable for
+     * it.
+     */
+    binHome: string;
+    /**
+     * `$XDG_RUNTIME_DIR`: sockets, pipes and other runtime files, owned by the
+     * user and removed at logout. `undefined` when unset, since the specification
+     * gives it no default: the application picks its own fallback.
+     */
+    runtimeDir: string | undefined;
+    /** `$XDG_DATA_DIRS`: data directories to search after `dataHome`, in order. */
+    dataDirs: string[];
+    /**
+     * `$XDG_CONFIG_DIRS`: configuration directories to search after `configHome`,
+     * in order.
+     */
+    configDirs: string[];
+};
+/** Options of {@link getXdgBaseDirectories}. */
+export type GetXdgBaseDirectoriesOptions = {
+    /** The environment to read, `process.env` by default. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** The home directory, `os.homedir()` by default. */
+    home?: string;
+};
+/**
+ * Resolves the XDG base directories (specification 0.8): where an application
+ * should read and write its data, configuration, state, cache and runtime files
+ * on Linux and other freedesktop.org systems.
+ *
+ * Append the application's own directory name to the one it needs:
+ * `join(getXdgBaseDirectories().dataHome, "myapp")`. Nothing is created.
+ *
+ * A variable that is unset, empty or holds a relative path falls back to its
+ * default, as the specification requires; in a list, relative entries are
+ * dropped, and a list left empty falls back too.
+ *
+ * Time complexity: O(n) in the length of the variables read. Memory: O(n).
+ *
+ * @example
+ * 	getXdgBaseDirectories({ env: {}, home: "/home/ada" }).dataHome;
+ * 	// "/home/ada/.local/share"
+ *
+ * @param options - The environment and home directory to read.
+ * @returns The directories, as absolute paths.
+ */
+export declare function getXdgBaseDirectories(options?: GetXdgBaseDirectoriesOptions): XdgBaseDirectories;
+//# sourceMappingURL=xdg-base-directories.d.ts.map

package/dist/os/xdg-base-directories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xdg-base-directories.d.ts","sourceRoot":"","sources":["../../src/os/xdg-base-directories.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,4BAA4B,GAAG;IAC1C,yDAAyD;IACzD,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnD,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,CAAC,EAAE,4BAA4B,GACpC,kBAAkB,CA8BpB"}

package/dist/os/xdg-base-directories.js

@@ -0,0 +1,51 @@
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+/**
+ * Resolves the XDG base directories (specification 0.8): where an application
+ * should read and write its data, configuration, state, cache and runtime files
+ * on Linux and other freedesktop.org systems.
+ *
+ * Append the application's own directory name to the one it needs:
+ * `join(getXdgBaseDirectories().dataHome, "myapp")`. Nothing is created.
+ *
+ * A variable that is unset, empty or holds a relative path falls back to its
+ * default, as the specification requires; in a list, relative entries are
+ * dropped, and a list left empty falls back too.
+ *
+ * Time complexity: O(n) in the length of the variables read. Memory: O(n).
+ *
+ * @example
+ * 	getXdgBaseDirectories({ env: {}, home: "/home/ada" }).dataHome;
+ * 	// "/home/ada/.local/share"
+ *
+ * @param options - The environment and home directory to read.
+ * @returns The directories, as absolute paths.
+ */
+export function getXdgBaseDirectories(options) {
+    const env = options?.env ?? process.env;
+    const home = options?.home ?? homedir();
+    const single = (name, fallback) => {
+        const value = env[name];
+        return value !== undefined && isAbsolute(value) ? value : fallback;
+    };
+    const list = (name, fallback) => {
+        const values = (env[name] ?? "")
+            .split(":")
+            .filter((value) => isAbsolute(value));
+        return values.length > 0 ? values : fallback;
+    };
+    const runtimeDir = env["XDG_RUNTIME_DIR"];
+    return {
+        dataHome: single("XDG_DATA_HOME", join(home, ".local", "share")),
+        configHome: single("XDG_CONFIG_HOME", join(home, ".config")),
+        stateHome: single("XDG_STATE_HOME", join(home, ".local", "state")),
+        cacheHome: single("XDG_CACHE_HOME", join(home, ".cache")),
+        binHome: join(home, ".local", "bin"),
+        runtimeDir: runtimeDir !== undefined && isAbsolute(runtimeDir)
+            ? runtimeDir
+            : undefined,
+        dataDirs: list("XDG_DATA_DIRS", ["/usr/local/share", "/usr/share"]),
+        configDirs: list("XDG_CONFIG_DIRS", ["/etc/xdg"]),
+    };
+}
+//# sourceMappingURL=xdg-base-directories.js.map

package/dist/os/xdg-base-directories.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xdg-base-directories.js","sourceRoot":"","sources":["../../src/os/xdg-base-directories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA8C7C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,qBAAqB,CACpC,OAAsC;IAEtC,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACxC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,OAAO,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,QAAgB,EAAU,EAAE;QACzD,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAC;QAExB,OAAO,KAAK,KAAK,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC;IACpE,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,QAAkB,EAAY,EAAE;QAC3D,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;aAC9B,KAAK,CAAC,GAAG,CAAC;aACV,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QAEvC,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC9C,CAAC,CAAC;IACF,MAAM,UAAU,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAE1C,OAAO;QACN,QAAQ,EAAE,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChE,UAAU,EAAE,MAAM,CAAC,iBAAiB,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC5D,SAAS,EAAE,MAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QAClE,SAAS,EAAE,MAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACzD,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC;QACpC,UAAU,EACT,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,UAAU,CAAC;YACjD,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,SAAS;QACb,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,kBAAkB,EAAE,YAAY,CAAC,CAAC;QACnE,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,UAAU,CAAC,CAAC;KACjD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ac-kit/app-system",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Process lifecycle helpers: PID files, process inspection, log rotation and command execution.",
   "keywords": [
     "log-rotation",
@@ -9,15 +9,15 @@
     "process",
     "system"
   ],
-  "homepage": "https://anthochamp.github.io/node-essentials/api/app-system/",
+  "homepage": "https://anthochamp.pages.grenadine.io/node-essentials/api/app-system/",
   "bugs": {
-    "url": "https://github.com/anthochamp/node-essentials/issues"
+    "url": "https://git.grenadine.io/anthochamp/node-essentials/issues"
   },
   "license": "BSD-3-Clause",
   "author": "Anthony Champagne <dev@anthonychampagne.fr>",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/anthochamp/node-essentials.git",
+    "url": "git+https://git.grenadine.io/anthochamp/node-essentials.git",
     "directory": "packages/app-system"
   },
   "files": [
@@ -39,15 +39,15 @@
     "prepack": "yarn build"
   },
   "dependencies": {
-    "@ac-kit/app-report": "^0.1.1",
+    "@ac-kit/app-report": "^0.1.3",
     "@ac-kit/app-terminal": "^0.1.0",
-    "@ac-kit/async": "^0.1.1",
-    "@ac-kit/core": "0.2.0",
-    "@ac-kit/crypto-hash": "^0.1.1",
-    "@ac-kit/data": "^0.1.1",
-    "@ac-kit/format-ansi": "^0.1.1",
-    "@ac-kit/format-shell": "^0.1.0",
-    "@ac-kit/node": "0.2.0",
+    "@ac-kit/async": "^0.1.3",
+    "@ac-kit/core": "0.4.0",
+    "@ac-kit/crypto-hash": "^0.1.3",
+    "@ac-kit/data": "^0.1.3",
+    "@ac-kit/format-ansi": "^0.1.3",
+    "@ac-kit/format-shell": "^0.1.2",
+    "@ac-kit/node": "0.3.1",
     "@types/node": "^26.5.1",
     "type-fest": "^5.8.0"
   },
@@ -58,7 +58,7 @@
     "@typescript/native": "typescript@7.0.2",
     "iconv-lite": "0.7.3",
     "rimraf": "6.1.3",
-    "tsx": "4.23.12",
+    "tsx": "4.23.15",
     "typedoc": "0.28.20",
     "typescript": "@typescript/typescript6@6.0.2"
   },