@hydraharness/harness-home-paths 0.1.1-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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/README.md

@@ -0,0 +1,28 @@
+# @hydraharness/harness-home-paths
+
+Shared filesystem path helpers for Hydra harness user data.
+
+## Hydra home
+
+`resolveHydraHome()` resolves the single-root Hydra harness home. Precedence, highest first: an explicit configured path, `$HYDRA_HOME`, then `~/.hydra`. The harness keeps all user data under one root.
+
+`hydraHomePath(...segments)` joins child segments onto that resolved home with Node's platform path rules. With no segments it returns the home itself.
+
+`hydraHomeDisplay()` names an active root symbolically for user-facing paths: `~/.hydra` for the default home, `$HYDRA_HOME` for any configured home. It never leaks an absolute machine path.
+
+`HYDRA_HOME_DIR_NAME` owns the default user-data directory name: `.hydra`.
+
+`defaultHydraHome()` returns the default Hydra harness home by joining the operating-system home directory with `.hydra`, using Node's platform path rules.
+
+`expandHomePath()` expands `~`, `~/...`, and Windows-style `~\...` prefixes against the operating-system home directory. It leaves non-tilde paths and `~user/...` untouched.
+
+## Watch paths
+
+`canonicalizeWatchPath()` gives a native filesystem watcher one stable spelling of its target. It resolves the deepest existing ancestor through `fs.realpath()` and restores any missing suffix, so a file or directory may still be watched before it is created. In particular, Windows 8.3 aliases cannot be mixed with the long paths emitted by the native watcher backend.
+
+This package is intentionally small and harness-dep-free so product packages can share user-data path conventions without depending on one another.
+
+## Known Limitations and Deferred Work
+
+- **Expansion is deliberately narrow** — only bare `~`, `~/...`, and `~\...` use the current operating-system home; named-user forms such as `~alice/...`, environment variables, and shell expressions remain unchanged.
+- **Canonicalization reads but never mutates** — `canonicalizeWatchPath()` performs `realpath` probes and propagates errors other than absence; callers still own directory creation, permissions, and trust policy for the resulting path.

package/lib/index.js

@@ -0,0 +1,97 @@
+import { opendir, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+//#region lib/types/index.js
+/**
+* Shared filesystem path helpers for Hydra harness user data.
+*
+* @module @hydraharness/harness-home-paths
+*/
+/** Directory name for the default Hydra harness home under the OS home. */
+const HYDRA_HOME_DIR_NAME = ".hydra";
+/** Stable user-facing display form for the default Hydra harness home. */
+const DEFAULT_HYDRA_HOME_DISPLAY = `~/${HYDRA_HOME_DIR_NAME}`;
+/** Environment variable that overrides the default Hydra harness home. */
+const HYDRA_HOME_ENV = "HYDRA_HOME";
+/**
+* Give a native filesystem watcher one canonical spelling of a path, even
+* when its final components do not exist yet. The deepest existing ancestor
+* is resolved through {@link realpath}; when a suffix is missing, that
+* ancestor is also proved to be an enumerable directory before the suffix is
+* restored. This prevents Windows from treating a regular-file ancestor as
+* ordinary absence, and prevents short-name aliases from being mixed with
+* long paths emitted by the native watcher backend.
+* @param path - Watch target or root, resolved against the current directory.
+* @returns the target with its existing ancestor canonicalized.
+* @throws when ancestor traversal encounters an error other than absence, or
+* the existing ancestor of a missing suffix is not an enumerable directory.
+*/
+async function canonicalizeWatchPath(path) {
+	let current = resolve(path);
+	const missing = [];
+	while (true) try {
+		const canonical = await realpath(current);
+		if (missing.length > 0) await (await opendir(canonical)).close();
+		return join(canonical, ...missing.reverse());
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		const parent = dirname(current);
+		/* v8 ignore next -- a filesystem root exists, so traversal resolves before this guard */
+		if (parent === current) throw error;
+		missing.push(basename(current));
+		current = parent;
+	}
+}
+/**
+* Resolve the default Hydra harness home using Node's platform path rules.
+* @returns the absolute default harness home path.
+*/
+function defaultHydraHome() {
+	return join(homedir(), HYDRA_HOME_DIR_NAME);
+}
+/**
+* Expand supported tilde prefixes against the operating-system home.
+* @param path - configured path that may begin with `~`, `~/`, or `~\`.
+* @returns the expanded path, or the original value when no supported prefix is present.
+*/
+function expandHomePath(path) {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
+	return path;
+}
+/**
+* Resolve the single-root Hydra harness home.
+*
+* Precedence, highest first: an explicit configured path, `$HYDRA_HOME`, then
+* `~/.hydra`. The harness keeps all user data under one root. An empty or
+* whitespace-only `$HYDRA_HOME` is treated as unset, so a blank override never
+* resolves the home to the current working directory.
+* @param configured - explicit harness-home override, which has highest precedence.
+* @param env - environment mapping used to read `HYDRA_HOME`.
+* @returns the normalized absolute harness home path.
+*/
+function resolveHydraHome(configured, env = process.env) {
+	const fromEnv = env[HYDRA_HOME_ENV];
+	return resolve(expandHomePath(configured ?? (fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : defaultHydraHome())));
+}
+/**
+* Join path segments onto the resolved Hydra harness home.
+* @param segments - path segments appended to the Harness home; an empty list returns the home itself.
+* @returns the normalized absolute joined path.
+*/
+function hydraHomePath(...segments) {
+	return join(resolveHydraHome(), ...segments);
+}
+/**
+* Describe a resolved harness home symbolically for user-facing display.
+*
+* It never returns an absolute machine path: the default home is labelled
+* `~/.hydra`, and any configured home is labelled `$HYDRA_HOME`.
+* @param resolvedHome - the absolute path returned by {@link resolveHydraHome}.
+* @returns `~/.hydra` for the default home, otherwise `$HYDRA_HOME`.
+*/
+function hydraHomeDisplay(resolvedHome) {
+	return resolvedHome === resolve(defaultHydraHome()) ? DEFAULT_HYDRA_HOME_DISPLAY : `$${HYDRA_HOME_ENV}`;
+}
+//#endregion
+export { DEFAULT_HYDRA_HOME_DISPLAY, HYDRA_HOME_DIR_NAME, HYDRA_HOME_ENV, canonicalizeWatchPath, defaultHydraHome, expandHomePath, hydraHomeDisplay, hydraHomePath, resolveHydraHome };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-home-paths`.
+* @module @hydraharness/harness-home-paths/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-home-paths";
+/** Cordis companion plugin name. */
+const name = "home-paths-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this pure utility owns no event stream or mutable runtime data; its value
+* algebra is enforced by unit tests.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared filesystem path helpers for Hydra harness user data.
+ *
+ * @module @hydraharness/harness-home-paths
+ */
+/** Directory name for the default Hydra harness home under the OS home. */
+export declare const HYDRA_HOME_DIR_NAME = ".hydra";
+/** Stable user-facing display form for the default Hydra harness home. */
+export declare const DEFAULT_HYDRA_HOME_DISPLAY = "~/.hydra";
+/** Environment variable that overrides the default Hydra harness home. */
+export declare const HYDRA_HOME_ENV = "HYDRA_HOME";
+/**
+ * Give a native filesystem watcher one canonical spelling of a path, even
+ * when its final components do not exist yet. The deepest existing ancestor
+ * is resolved through {@link realpath}; when a suffix is missing, that
+ * ancestor is also proved to be an enumerable directory before the suffix is
+ * restored. This prevents Windows from treating a regular-file ancestor as
+ * ordinary absence, and prevents short-name aliases from being mixed with
+ * long paths emitted by the native watcher backend.
+ * @param path - Watch target or root, resolved against the current directory.
+ * @returns the target with its existing ancestor canonicalized.
+ * @throws when ancestor traversal encounters an error other than absence, or
+ * the existing ancestor of a missing suffix is not an enumerable directory.
+ */
+export declare function canonicalizeWatchPath(path: string): Promise<string>;
+/**
+ * Resolve the default Hydra harness home using Node's platform path rules.
+ * @returns the absolute default harness home path.
+ */
+export declare function defaultHydraHome(): string;
+/**
+ * Expand supported tilde prefixes against the operating-system home.
+ * @param path - configured path that may begin with `~`, `~/`, or `~\`.
+ * @returns the expanded path, or the original value when no supported prefix is present.
+ */
+export declare function expandHomePath(path: string): string;
+/**
+ * Resolve the single-root Hydra harness home.
+ *
+ * Precedence, highest first: an explicit configured path, `$HYDRA_HOME`, then
+ * `~/.hydra`. The harness keeps all user data under one root. An empty or
+ * whitespace-only `$HYDRA_HOME` is treated as unset, so a blank override never
+ * resolves the home to the current working directory.
+ * @param configured - explicit harness-home override, which has highest precedence.
+ * @param env - environment mapping used to read `HYDRA_HOME`.
+ * @returns the normalized absolute harness home path.
+ */
+export declare function resolveHydraHome(configured?: string, env?: Record<string, string | undefined>): string;
+/**
+ * Join path segments onto the resolved Hydra harness home.
+ * @param segments - path segments appended to the Harness home; an empty list returns the home itself.
+ * @returns the normalized absolute joined path.
+ */
+export declare function hydraHomePath(...segments: string[]): string;
+/**
+ * Describe a resolved harness home symbolically for user-facing display.
+ *
+ * It never returns an absolute machine path: the default home is labelled
+ * `~/.hydra`, and any configured home is labelled `$HYDRA_HOME`.
+ * @param resolvedHome - the absolute path returned by {@link resolveHydraHome}.
+ * @returns `~/.hydra` for the default home, otherwise `$HYDRA_HOME`.
+ */
+export declare function hydraHomeDisplay(resolvedHome: string): string;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-home-paths`.
+ * @module @hydraharness/harness-home-paths/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "home-paths-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@hydraharness/harness-home-paths",
+  "description": "Shared filesystem path helpers for the Hydra harness",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/util/home-paths"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}