Merge master into worktree-windows-runtime

packages/util/paths/README.md

@@ -4,6 +4,10 @@ Shared filesystem path helpers for DeepSeek Harness user data.
 
 ## DSH home
 
+`resolveDshHome()` resolves the single-root DeepSeek Harness home. Precedence, highest first: an explicit configured path, `$DSH_HOME`, then `~/.dsh`. The harness keeps all user data under one root.
+
+`dshHomeDisplay()` names an active root symbolically for user-facing paths: `~/.dsh` for the default home, `$DSH_HOME` for any configured home. It never leaks an absolute machine path.
+
 `DSH_HOME_DIR_NAME` owns the default user-data directory name: `.dsh`.
 
 `defaultDshHome()` returns the default DeepSeek Harness home by joining the operating-system home directory with `.dsh`, using Node's platform path rules.

packages/util/paths/package.json

@@ -11,20 +11,27 @@
       "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",
     "lib/types/**/*.d.ts.map",
     "src"
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }

packages/util/paths/src/index.ts

@@ -36,12 +36,30 @@ export function expandHomePath(path: string): string {
 }
 
 /**
- * Resolve an explicitly configured, environment-selected, or default DSH home.
+ * Resolve the single-root DeepSeek Harness home.
+ *
+ * Precedence, highest first: an explicit configured path, `$DSH_HOME`, then
+ * `~/.dsh`. The harness keeps all user data under one root. An empty or
+ * whitespace-only `$DSH_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 `DSH_HOME`.
  * @returns the normalized absolute harness home path.
  */
 export function resolveDshHome(configured?: string, env: Record<string, string | undefined> = process.env): string {
-  const selected = configured ?? env[DSH_HOME_ENV] ?? defaultDshHome()
+  const fromEnv = env[DSH_HOME_ENV]
+  const selected = configured ?? (fromEnv !== undefined && fromEnv.trim().length > 0 ? fromEnv : defaultDshHome())
   return resolve(expandHomePath(selected))
 }
+
+/**
+ * Describe a resolved harness home symbolically for user-facing display.
+ *
+ * It never returns an absolute machine path: the default home is labelled
+ * `~/.dsh`, and any configured home is labelled `$DSH_HOME`.
+ * @param resolvedHome - the absolute path returned by {@link resolveDshHome}.
+ * @returns `~/.dsh` for the default home, otherwise `$DSH_HOME`.
+ */
+export function dshHomeDisplay(resolvedHome: string): string {
+  return resolvedHome === resolve(defaultDshHome()) ? DEFAULT_DSH_HOME_DISPLAY : `$${DSH_HOME_ENV}`
+}

packages/util/paths/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-paths`.
+ * @module @deepseek-ai/dsh-paths/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-paths'
+
+/** Cordis companion plugin name. */
+export const name = 'paths-invariant'
+/** Service required before the companion can reserve package ownership. */
+export 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: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */

packages/util/paths/tests/paths.spec.ts

@@ -5,6 +5,7 @@ import {
   DEFAULT_DSH_HOME_DISPLAY,
   DSH_HOME_DIR_NAME,
   defaultDshHome,
+  dshHomeDisplay,
   expandHomePath,
   resolveDshHome,
 } from '@deepseek-ai/dsh-paths'
@@ -24,11 +25,21 @@ describe('dsh path helpers', () => {
     expect(expandHomePath('~other/.dsh')).toBe('~other/.dsh')
   })
 
-  it('resolves explicit DSH home before environment and default locations', () => {
+  it('resolves explicit path before DSH_HOME and the default', () => {
     const envHome = join(homedir(), 'env-dsh')
 
-    expect(resolveDshHome(undefined, { DSH_HOME: '~/env-dsh' })).toBe(envHome)
     expect(resolveDshHome('/tmp/explicit-dsh', { DSH_HOME: '~/env-dsh' })).toBe(resolve('/tmp/explicit-dsh'))
+    expect(resolveDshHome(undefined, { DSH_HOME: '~/env-dsh' })).toBe(envHome)
     expect(resolveDshHome(undefined, {})).toBe(defaultDshHome())
   })
+
+  it('treats an empty or whitespace-only DSH_HOME as unset', () => {
+    expect(resolveDshHome(undefined, { DSH_HOME: '' })).toBe(defaultDshHome())
+    expect(resolveDshHome(undefined, { DSH_HOME: '   ' })).toBe(defaultDshHome())
+  })
+
+  it('labels a resolved home by whether it is the default root', () => {
+    expect(dshHomeDisplay(resolve(defaultDshHome()))).toBe('~/.dsh')
+    expect(dshHomeDisplay('/some/other/root')).toBe('$DSH_HOME')
+  })
 })

packages/util/paths/tsconfig.json

@@ -7,5 +7,9 @@
   "include": [
     "src"
   ],
-  "references": []
+  "references": [
+    {
+      "path": "../../support/invariants"
+    }
+  ]
 }