README.md 5.3 KB
description: "Shared resolution of the DeepSeek Harness home and user-data paths for packages that need one consistent root, tilde expansion, and stable watch paths."
kind: "package-library"
@deepseek-ai/dsh-home-paths
English | 中文
Summary
@deepseek-ai/dsh-home-paths lets package authors resolve one DeepSeek Harness data root and derive child paths from it. An explicit path wins over $DSH_HOME, which wins over ~/.dsh; 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
- Understand the implementation
- Further Exploration
- Known Limitations and Deferred Work
- Dev Note
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
import { resolveDshHome, dshHomePath } from '@deepseek-ai/dsh-home-paths'
const home = resolveDshHome() // configured path, else $DSH_HOME, else ~/.dsh
const settings = dshHomePath('settings') // join one child onto the resolved home
An explicit configured path has the highest precedence, then $DSH_HOME, then the default ~/.dsh. An empty or whitespace-only $DSH_HOME is treated as unset, so a blank override never resolves the home to the current working directory.
Displaying a home
For user-facing paths, render the root symbolically rather than as a machine path: the default home displays as ~/.dsh and any configured home displays as $DSH_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.
Understand the implementation
Implementation internals — click to expand
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 value algebra is enforced by unit tests. | ### Resolution rules `resolveDshHome` reads the explicit override, then `$DSH_HOME`, then falls back to the operating-system home joined with `.dsh`. The chosen value is tilde-expanded and normalized to an absolute path; `dshHomePath` joins child segments with Node's platform path rules. `dshHomeDisplay` 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.Further Exploration
Read these pages when you need the launcher or the consumers that depend on a single home root.
- Boot package — the launcher that resolves the home before any plugin mounts.
- Shell environment — how
DSH_HOMEreaches model shell calls. - Anonymous user id — a stored identity file under the resolved home.
Known Limitations and Deferred Work
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 —
canonicalizeWatchPathperformsrealpathprobes and propagates errors other than absence; callers still own directory creation, permissions, and trust policy for the resulting path.