5.5 KiB
description, kind
| description | kind |
|---|---|
| Shared resolution of the DeepSeek Harness home and user-data paths for packages that need one consistent root, tilde expansion, and stable watch paths. | package-library |
@deepseek-ai/dsh-home-paths
English | 中文
Summary
dsh-home-paths resolves the single DeepSeek Harness home that all user data lives under, and joins child paths onto it, so every product package agrees on where its files go. Precedence is explicit: a configured path wins, then $DSH_HOME, then ~/.dsh, and an empty or whitespace-only $DSH_HOME counts as unset. The package also expands ~, ~/..., and ~\... prefixes against the operating-system home, and canonicalizes a watch target so a native filesystem watcher gets one stable path spelling even when the final components do not exist yet. It is a zero-dependency library that product packages import directly; a cordis.yml cannot load it.
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 |
Home resolution, path joining, display, tilde expansion, and watch-path canonicalization |
src/invariant.ts |
Invariant companion (no runtime invariant; the resolution rules are exercised 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.
Dev Note
Working context for maintainers — click to expand
None.