@worldapptechnologies/nulu-home-paths 0.0.0-stage → 1.6.4

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

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+---
+description: "Shared resolution of the Nulu Harness home and user-data paths for packages that need one consistent root, tilde expansion, and stable watch paths."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @worldapptechnologies/nulu-home-paths
+
+
+## Summary
+
+`@worldapptechnologies/nulu-home-paths` lets package authors resolve one Nulu Harness data root and derive child paths from it. An explicit path wins over `$NULU_HOME`, which wins over `~/.nulu`; blank environment values are ignored. Its public helpers can render the root without revealing an absolute machine path, expand only bare or current-user tilde forms, and canonicalize watch targets whose final components do not yet exist. Use it as a direct library dependency, not through `cordis.yml`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use these helpers wherever a package must agree with the rest of the harness about where user data lives: resolve the home once, then derive every child path from it.
+
+### Resolving the home
+
+```ts
+import { resolveNuluHome, nuluHomePath, nuluCachePath } from '@worldapptechnologies/nulu-home-paths'
+
+const home = resolveNuluHome()                // configured path, else $NULU_HOME, else ~/.nulu
+const settings = nuluHomePath('settings')     // join one child onto the resolved home
+const cache = nuluCachePath('models')         // $NULU_HOME/cache/models, default ~/.nulu/cache/models
+```
+
+An explicit configured path has the highest precedence, then `$NULU_HOME`, then the default `~/.nulu`. An empty or whitespace-only `$NULU_HOME` is treated as unset, so a blank override never resolves the home to the current working directory.
+
+`nuluCachePath(...segments)` derives paths from the resolved home's `cache` directory. With no segments it returns the cache directory itself. Pass an initial options object, `nuluCachePath({ nuluHome: home }, ...segments)`, to use an explicit configured home with the same precedence and tilde expansion. It returns an absolute path without creating directories.
+
+### Displaying a home
+
+For user-facing paths, render the root symbolically rather than as a machine path: the default home displays as `~/.nulu` and any configured home displays as `$NULU_HOME`. The display form never leaks an absolute machine path.
+
+### Expanding user paths
+
+`expandHomePath` expands a leading `~`, `~/`, or `~\` against the operating-system home and leaves everything else untouched — non-tilde paths and named-user forms such as `~alice/...` pass through unchanged.
+
+### Canonicalizing watch paths
+
+`canonicalizeWatchPath` gives a native filesystem watcher one canonical spelling of its target: the deepest existing ancestor is resolved through `realpath` and any missing suffix is restored, so a file or directory can be watched before it is created. This prevents Windows from treating a regular-file ancestor as ordinary absence, and prevents 8.3 short-name aliases from mixing with the long paths the native watcher backend emits.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The package is built on one principle: all harness user data lives under one root, and every other helper derives from that decision.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Home resolution, path joining, display, tilde expansion, and watch-path canonicalization |
+| — | No runtime invariant companion is published; this pure utility owns no event stream or mutable runtime data; its resolution rules and value algebra are enforced by unit tests. |
+
+### Resolution rules
+
+`resolveNuluHome` reads the explicit override, then `$NULU_HOME`, then falls back to the operating-system home joined with `.nulu`. The chosen value is tilde-expanded and normalized to an absolute path; `nuluHomePath` joins child segments with Node's platform path rules. `nuluHomeDisplay` compares the resolved path against the default root and returns the symbolic label, so a configured home never leaks its absolute path.
+
+### Canonicalization mechanics
+
+`canonicalizeWatchPath` walks up from the target until it finds an existing ancestor, resolves it with `realpath`, proves it is an enumerable directory, and restores the missing suffix. Errors other than absence propagate, and a missing-suffix ancestor that is not a directory is rejected.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when you need the launcher or the consumers that depend on a single home root.
+
+- [Boot package](../../boot/app-boot/README.md) — the launcher that resolves the home before any plugin mounts.
+- [Shell environment](../../shell/shell-env/README.md) — how `NULU_HOME` reaches model shell calls.
+- [Anonymous user id](../../identity/anonymous-user-id/README.md) — a stored identity file under the resolved home.
+
+-----
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the helpers are not the right tool. They are current package constraints, not a task backlog.
+
+- **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.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/lib/index.js

@@ -0,0 +1,107 @@
+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 Nulu Harness user data.
+*
+* @module @worldapptechnologies/nulu-home-paths
+*/
+/** Directory name for the default Nulu Harness home under the OS home. */
+const NULU_HOME_DIR_NAME = ".nulu";
+/** Stable user-facing display form for the default Nulu Harness home. */
+const DEFAULT_NULU_HOME_DISPLAY = `~/${NULU_HOME_DIR_NAME}`;
+/** Environment variable that overrides the default Nulu Harness home. */
+const NULU_HOME_ENV = "NULU_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 Nulu Harness home using Node's platform path rules.
+* @returns the absolute default harness home path.
+*/
+function defaultNuluHome() {
+	return join(homedir(), NULU_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 Nulu Harness home.
+*
+* Precedence, highest first: an explicit configured path, `$NULU_HOME`, then
+* `~/.nulu`. The harness keeps all user data under one root. An empty or
+* whitespace-only `$NULU_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 `NULU_HOME`.
+* @returns the normalized absolute harness home path.
+*/
+function resolveNuluHome(configured, env = process.env) {
+	const fromEnv = env[NULU_HOME_ENV];
+	return resolve(expandHomePath(configured ?? (fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : defaultNuluHome())));
+}
+/**
+* Join path segments onto the resolved Nulu 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 nuluHomePath(...segments) {
+	return join(resolveNuluHome(), ...segments);
+}
+/**
+* Join path segments onto the resolved Harness home's `cache` directory without creating it; no arguments returns the directory itself.
+* @param optionsOrSegment - explicit home override, or the first path segment; omission uses the default home resolution.
+* @param segments - additional path segments after the first child, if any.
+* @returns the normalized absolute cache path.
+*/
+function nuluCachePath(optionsOrSegment = {}, ...segments) {
+	if (typeof optionsOrSegment === "string") return nuluHomePath("cache", optionsOrSegment, ...segments);
+	return join(resolveNuluHome(optionsOrSegment.nuluHome), "cache", ...segments);
+}
+/**
+* Describe a resolved harness home symbolically for user-facing display.
+*
+* It never returns an absolute machine path: the default home is labelled
+* `~/.nulu`, and any configured home is labelled `$NULU_HOME`.
+* @param resolvedHome - the absolute path returned by {@link resolveNuluHome}.
+* @returns `~/.nulu` for the default home, otherwise `$NULU_HOME`.
+*/
+function nuluHomeDisplay(resolvedHome) {
+	return resolvedHome === resolve(defaultNuluHome()) ? DEFAULT_NULU_HOME_DISPLAY : `$${NULU_HOME_ENV}`;
+}
+//#endregion
+export { DEFAULT_NULU_HOME_DISPLAY, NULU_HOME_DIR_NAME, NULU_HOME_ENV, canonicalizeWatchPath, defaultNuluHome, expandHomePath, nuluCachePath, nuluHomeDisplay, nuluHomePath, resolveNuluHome };

package/lib/types/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared filesystem path helpers for Nulu Harness user data.
+ *
+ * @module @worldapptechnologies/nulu-home-paths
+ */
+/** Directory name for the default Nulu Harness home under the OS home. */
+export declare const NULU_HOME_DIR_NAME = ".nulu";
+/** Stable user-facing display form for the default Nulu Harness home. */
+export declare const DEFAULT_NULU_HOME_DISPLAY = "~/.nulu";
+/** Environment variable that overrides the default Nulu Harness home. */
+export declare const NULU_HOME_ENV = "NULU_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 Nulu Harness home using Node's platform path rules.
+ * @returns the absolute default harness home path.
+ */
+export declare function defaultNuluHome(): 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 Nulu Harness home.
+ *
+ * Precedence, highest first: an explicit configured path, `$NULU_HOME`, then
+ * `~/.nulu`. The harness keeps all user data under one root. An empty or
+ * whitespace-only `$NULU_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 `NULU_HOME`.
+ * @returns the normalized absolute harness home path.
+ */
+export declare function resolveNuluHome(configured?: string, env?: Record<string, string | undefined>): string;
+/**
+ * Join path segments onto the resolved Nulu 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 nuluHomePath(...segments: string[]): string;
+/**
+ * Join path segments onto the resolved Harness home's `cache` directory without creating it; no arguments returns the directory itself.
+ * @param optionsOrSegment - explicit home override, or the first path segment; omission uses the default home resolution.
+ * @param segments - additional path segments after the first child, if any.
+ * @returns the normalized absolute cache path.
+ */
+export declare function nuluCachePath(optionsOrSegment?: {
+    nuluHome?: string;
+} | string, ...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
+ * `~/.nulu`, and any configured home is labelled `$NULU_HOME`.
+ * @param resolvedHome - the absolute path returned by {@link resolveNuluHome}.
+ * @returns `~/.nulu` for the default home, otherwise `$NULU_HOME`.
+ */
+export declare function nuluHomeDisplay(resolvedHome: string): string;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@worldapptechnologies/nulu-home-paths",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Shared filesystem path helpers for the Nulu Harness",
+  "version": "1.6.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/worldapptechnologies/nulu-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"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@worldapptechnologies/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@worldapptechnologies/cordis": "^4.0.2"
+  }
 }