@morlay/dsh-desktop-shell 0.2.5 → 0.2.7

package/dist/inline-packages.d.mts

@@ -0,0 +1,14 @@
+//#region src/inline-packages.d.ts
+/**
+ * 壳产物里要**内联**的包（而不是留在产物外）。
+ *
+ * 壳跑在 `app.asar` 里，它的解析面只有产物自身 + Electron 提供的东西：留在外面的裸引用会变成
+ * `ERR_MODULE_NOT_FOUND`。所以这几类必须内联——
+ * - `@morlay/dsh-desktop-host`：壳直接用它（wire 协议、paths、webServer 的替身）；
+ * - 快捷键桥的原生侧要用上游的「设备偏好单写者」与原子写，它们同样进不了 asar 的解析面。
+ *
+ * 这份名单是**一个事实**：壳自己的构建（[`tsdown.config.ts`](../../tsdown.config.ts)）与 `@local/dshdev` 的
+ * 装配（`prepareShell`）都用它——两边不一致的话，装配出来的产物就会缺依赖。
+ */
+export declare const SHELL_INLINE_PACKAGES: readonly string[];
+//#endregion

package/dist/inline-packages.mjs

@@ -0,0 +1,21 @@
+//#region src/inline-packages.ts
+/**
+* 壳产物里要**内联**的包（而不是留在产物外）。
+*
+* 壳跑在 `app.asar` 里，它的解析面只有产物自身 + Electron 提供的东西：留在外面的裸引用会变成
+* `ERR_MODULE_NOT_FOUND`。所以这几类必须内联——
+* - `@morlay/dsh-desktop-host`：壳直接用它（wire 协议、paths、webServer 的替身）；
+* - 快捷键桥的原生侧要用上游的「设备偏好单写者」与原子写，它们同样进不了 asar 的解析面。
+*
+* 这份名单是**一个事实**：壳自己的构建（[`tsdown.config.ts`](../../tsdown.config.ts)）与 `@local/dshdev` 的
+* 装配（`prepareShell`）都用它——两边不一致的话，装配出来的产物就会缺依赖。
+*/
+const SHELL_INLINE_PACKAGES = [
+	"@morlay/dsh-desktop-host",
+	"@deepseek-ai/dsh-client-shortcuts",
+	"@deepseek-ai/dsh-atomic-write",
+	"@deepseek-ai/dsh-util-values",
+	"@deepseek-ai/dsh-util-crypto"
+];
+//#endregion
+export { SHELL_INLINE_PACKAGES };

package/dist/official-BmgBsdhq.mjs

@@ -0,0 +1,5 @@
+//#region src/official.ts
+const DESKTOP_HOST_PACKAGE = "@morlay/dsh-desktop-host";
+const OFFICIAL_PROFILE_BUNDLES = ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app"];
+//#endregion
+export { OFFICIAL_PROFILE_BUNDLES as n, DESKTOP_HOST_PACKAGE as t };

package/dist/official.d.mts

@@ -0,0 +1,4 @@
+//#region src/official.d.ts
+export declare const DESKTOP_HOST_PACKAGE = "@morlay/dsh-desktop-host";
+export declare const OFFICIAL_PROFILE_BUNDLES: readonly string[];
+//#endregion

package/dist/official.mjs

@@ -1,2 +1 @@
-import { i as OFFICIAL_PROFILE_PACKAGES, n as OFFICIAL_PROFILE_BUNDLES, r as OFFICIAL_RUNTIME_PACKAGES, t as DESKTOP_HOST_PACKAGE } from "./official-Cz9Mry1n.mjs";
-export { DESKTOP_HOST_PACKAGE, OFFICIAL_PROFILE_BUNDLES, OFFICIAL_PROFILE_PACKAGES, OFFICIAL_RUNTIME_PACKAGES };
+export { t as DESKTOP_HOST_PACKAGE, n as OFFICIAL_PROFILE_BUNDLES } from "./official-BmgBsdhq.mjs";

package/dist/preload-app.cjs

@@ -34,6 +34,8 @@ function syncNativeTheme(platform, root, send) {
 }
 //#endregion
 //#region src/ipc.ts
+/** 壳把宿主回环的 ws 端口经 preload 递进页面（`additionalArguments`，与 scheme 同一手法）。 */
+const DESKTOP_WS_PORT_ARGUMENT = "--dsh-desktop-ws-port";
 const DESKTOP_IPC = {
 	directoryPick: "dsh-desktop:directory-pick",
 	nativeThemeSet: "dsh-desktop:native-theme-set",
@@ -81,7 +83,9 @@ function createStreamUplink(send, end) {
 //#endregion
 //#region src/preload-app.ts
 const scheme = process.argv.find((argument) => argument.startsWith(`${DESKTOP_SCHEME_ARGUMENT}=`))?.slice(21);
-if (scheme !== void 0 && scheme !== "" && location.protocol === `${scheme}:` && location.hostname === "app") {
+const wsPort = process.argv.find((argument) => argument.startsWith(`${DESKTOP_WS_PORT_ARGUMENT}=`))?.slice(22);
+if (scheme !== void 0 && scheme !== "") {
+	console.log(`[dsh-shell] preload: scheme=${String(scheme)} wsPort=${String(wsPort)} webFrame=${typeof electron.webFrame}`);
 	electron.contextBridge.exposeInMainWorld("__DSH_DIRECTORY_PICKER__", { pick: () => electron.ipcRenderer.invoke(DESKTOP_IPC.directoryPick) });
 	electron.contextBridge.exposeInMainWorld("__DSH_DESKTOP_STREAM__", { open(endpoint, payload, handlers) {
 		let id;

package/dist/profile-project.d.mts

@@ -0,0 +1,20 @@
+import { spawn } from "node:child_process";
+//#region src/profile-project.d.ts
+export declare const PROFILE_WORKSPACE_NAME = "pnpm-workspace.yaml";
+export declare const PROFILE_RUNTIME_REPORT_NAME = "desktop-runtime-packages.json";
+export declare const PROFILE_VENDOR_DIR_NAME = "vendor";
+export interface RuntimeOverride {
+  readonly name: string;
+  readonly target: string;
+}
+export declare function runtimeOverrides(profileDir: string, runtimeDir: string): Promise<RuntimeOverride[]>;
+export declare function workspaceWithOverrides(text: string, overrides: readonly RuntimeOverride[]): string;
+export type ProfileInstallSpawn = typeof spawn;
+export interface ProfileInstallOptions {
+  readonly node: string;
+  readonly pnpmEntry: string;
+  readonly profileDir: string;
+  readonly spawn?: ProfileInstallSpawn;
+}
+export declare function installProfile(options: ProfileInstallOptions): Promise<void>;
+//#endregion

package/dist/profile-project.mjs

@@ -1,2 +1 @@
-import { a as runtimeOverrides, i as installProfile, n as PROFILE_VENDOR_DIR_NAME, o as workspaceWithOverrides, r as PROFILE_WORKSPACE_NAME, t as PROFILE_RUNTIME_REPORT_NAME } from "./profile-project-BgQILDbu.mjs";
-export { PROFILE_RUNTIME_REPORT_NAME, PROFILE_VENDOR_DIR_NAME, PROFILE_WORKSPACE_NAME, installProfile, runtimeOverrides, workspaceWithOverrides };
+export { t as PROFILE_RUNTIME_REPORT_NAME, n as PROFILE_VENDOR_DIR_NAME, r as PROFILE_WORKSPACE_NAME, i as installProfile, a as runtimeOverrides, o as workspaceWithOverrides } from "./profile-project-BgQILDbu.mjs";

package/dist/{seed-BF71UAuI.mjs → seed-Bxr0BsCk.mjs}

@@ -1,6 +1,7 @@
-import { n as PROFILE_PATCH_NAME, t as PROFILE_NAME } from "./appconfig-BZ9wPROk.mjs";
+import { n as PROFILE_PATCH_NAME, t as PROFILE_NAME } from "./appconfig-CSZh3JG7.mjs";
 import { access, chmod, copyFile, lstat, mkdir, readFile, readdir, readlink, rm, symlink, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { spawn } from "node:child_process";
 //#region src/seed.ts
 const SEED_DIR_NAME = "dsh-home";
 const SEED_HASH_NAME = ".seed-hash";
@@ -32,13 +33,51 @@ async function isDirectory(path) {
 		return false;
 	}
 }
+/** 解压随包的依赖归档：实体文件、闭包完整（替代逐包 `link:` 那种写法）。 */
+async function extractProfileModules(archive, profileDir) {
+	await new Promise((done, fail) => {
+		const child = spawn("tar", [
+			"-xzf",
+			archive,
+			"-C",
+			profileDir
+		], { stdio: [
+			"ignore",
+			"ignore",
+			"inherit"
+		] });
+		child.on("error", fail);
+		child.on("close", (code) => code === 0 ? done() : fail(/* @__PURE__ */ new Error(`tar -xzf ${archive} exited with ${String(code)}`)));
+	});
+}
+const PROFILE_MODULES_ARCHIVE_NAME = "profile-node-modules.tar";
+/** 依赖面是否真的在：`node_modules` 存在且非空。 */
+async function hasDependencies(profileDir) {
+	const modules = join(profileDir, "node_modules");
+	if (!await isDirectory(modules)) return false;
+	return (await readdir(modules)).length > 0;
+}
+/**
+* 把随包的种子种成一份可用的 profile：清单 + 各 bundle 自己的 patch 从种子拷（用户那份 patch 除外），
+* **依赖面**由随包归档解压而来。种完才算数——调用方要等它返回才起宿主。
+*
+* 判"已是最新"要同时满足：指纹一致 **且** 依赖面真的在（归档在场时）。指纹只说明"清单与闭包是哪一份"，
+* 不说明"它被解压出来了"：少了后半句，一次解压失败（或谁清过 `node_modules`）就永远补不回来，宿主会一直
+* 带着残缺 profile 起来。
+* @param seedDir - 随包的种子根（`Resources/seed`）。
+* @param home - 数据面根（`$DSH_HOME`）；profile 落在 `<home>/profiles/<name>`。
+* @returns 种了（`seeded`）、已是最新（`up-to-date`）、或随包根本没有这份种（`no-seed`）。
+* @throws 归档解压失败、或解压后没有依赖面时。
+*/
 async function ensureSeedProfile(seedDir, home) {
 	const seedProfile = join(seedDir, "profiles", PROFILE_NAME);
-	if (!await isDirectory(seedProfile)) return false;
+	if (!await isDirectory(seedProfile)) return "no-seed";
 	const profileDir = join(home, "profiles", PROFILE_NAME);
+	const archive = join(seedDir, PROFILE_MODULES_ARCHIVE_NAME);
+	const hasArchive = await pathExists(archive);
 	const seedHash = await readSeedHash(join(seedProfile, SEED_HASH_NAME));
 	if (seedHash !== "") try {
-		if (!(await lstat(profileDir)).isSymbolicLink() && await readSeedHash(join(profileDir, ".seed-hash")) === seedHash) return false;
+		if (!(await lstat(profileDir)).isSymbolicLink() && await readSeedHash(join(profileDir, ".seed-hash")) === seedHash && (!hasArchive || await hasDependencies(profileDir))) return "up-to-date";
 	} catch {}
 	const patchPath = join(profileDir, PROFILE_PATCH_NAME);
 	const userPatch = await readFile(patchPath, "utf8").catch(() => void 0);
@@ -51,11 +90,19 @@ async function ensureSeedProfile(seedDir, home) {
 		if (error.code !== "ENOENT") throw error;
 	}
 	await copySeed(seedProfile, profileDir);
+	if (hasArchive) {
+		await rm(join(profileDir, "node_modules"), {
+			recursive: true,
+			force: true
+		});
+		await extractProfileModules(archive, profileDir);
+		if (!await hasDependencies(profileDir)) throw new Error(`dsh desktop: ${archive} did not yield a dependency closure at ${join(profileDir, "node_modules")}`);
+	}
 	if (userPatch !== void 0) {
 		await mkdir(dirname(patchPath), { recursive: true });
 		await writeFile(patchPath, userPatch);
 	}
-	return true;
+	return "seeded";
 }
 async function copySeed(source, target) {
 	await mkdir(target, { recursive: true });
@@ -91,4 +138,4 @@ async function copySeed(source, target) {
 	await visit(source, "");
 }
 //#endregion
-export { ensureSeedProfile as i, SEED_HASH_NAME as n, SEED_RUNTIME_DIR_NAME as r, SEED_DIR_NAME as t };
+export { ensureSeedProfile as a, SEED_RUNTIME_DIR_NAME as i, SEED_DIR_NAME as n, SEED_HASH_NAME as r, PROFILE_MODULES_ARCHIVE_NAME as t };

package/dist/seed.d.mts

@@ -0,0 +1,21 @@
+//#region src/seed.d.ts
+export declare const SEED_DIR_NAME = "dsh-home";
+export declare const SEED_HASH_NAME = ".seed-hash";
+export declare const SEED_RUNTIME_DIR_NAME = "runtime";
+export declare const PROFILE_MODULES_ARCHIVE_NAME = "profile-node-modules.tar";
+/** 一次"种 profile"的结果：调用方据此记录、并在打包形态把 `no-seed` 当致命。 */
+export type SeedOutcome = "seeded" | "up-to-date" | "no-seed";
+/**
+ * 把随包的种子种成一份可用的 profile：清单 + 各 bundle 自己的 patch 从种子拷（用户那份 patch 除外），
+ * **依赖面**由随包归档解压而来。种完才算数——调用方要等它返回才起宿主。
+ *
+ * 判"已是最新"要同时满足：指纹一致 **且** 依赖面真的在（归档在场时）。指纹只说明"清单与闭包是哪一份"，
+ * 不说明"它被解压出来了"：少了后半句，一次解压失败（或谁清过 `node_modules`）就永远补不回来，宿主会一直
+ * 带着残缺 profile 起来。
+ * @param seedDir - 随包的种子根（`Resources/seed`）。
+ * @param home - 数据面根（`$DSH_HOME`）；profile 落在 `<home>/profiles/<name>`。
+ * @returns 种了（`seeded`）、已是最新（`up-to-date`）、或随包根本没有这份种（`no-seed`）。
+ * @throws 归档解压失败、或解压后没有依赖面时。
+ */
+export declare function ensureSeedProfile(seedDir: string, home: string): Promise<SeedOutcome>;
+//#endregion

package/dist/seed.mjs

@@ -1,2 +1 @@
-import { i as ensureSeedProfile, n as SEED_HASH_NAME, r as SEED_RUNTIME_DIR_NAME, t as SEED_DIR_NAME } from "./seed-BF71UAuI.mjs";
-export { SEED_DIR_NAME, SEED_HASH_NAME, SEED_RUNTIME_DIR_NAME, ensureSeedProfile };
+export { t as PROFILE_MODULES_ARCHIVE_NAME, n as SEED_DIR_NAME, r as SEED_HASH_NAME, i as SEED_RUNTIME_DIR_NAME, a as ensureSeedProfile } from "./seed-Bxr0BsCk.mjs";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morlay/dsh-desktop-shell",
-  "version": "0.2.5",
-  "description": "Electron shell for dsh desktop apps: serves the app's own <name>:// scheme, boots the desktop profile through the @morlay/dsh-desktop-host child over byte pipes, and installs the profile seed on first launch. The CLI that packages a workspace around it is @morlay/dsh-desktopify.",
+  "version": "0.2.7",
+  "description": "Electron shell for dsh desktop apps: serves the app's own <name>:// scheme, boots the desktop profile through the @morlay/dsh-desktop-host child over byte pipes, and installs the profile seed on first launch. The CLI that packages a workspace around it is @local/dshdev.",
   "keywords": [
     "desktop",
     "dsh",
@@ -15,43 +15,65 @@
     "url": "https://github.com/morlay/dsh-plugin.git"
   },
   "files": [
+    "src",
     "locale/*.json",
     "dist"
   ],
   "type": "module",
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
+  "main": "./main.mjs",
   "exports": {
-    ".": "./dist/index.mjs",
-    "./appconfig": "./dist/appconfig.mjs",
-    "./dshhome": "./dist/dshhome.mjs",
-    "./official": "./dist/official.mjs",
-    "./profile-project": "./dist/profile-project.mjs",
-    "./seed": "./dist/seed.mjs",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./appconfig": {
+      "types": "./dist/appconfig.d.mts",
+      "default": "./dist/appconfig.mjs"
+    },
+    "./dshhome": {
+      "types": "./dist/dshhome.d.mts",
+      "default": "./dist/dshhome.mjs"
+    },
+    "./official": {
+      "types": "./dist/official.d.mts",
+      "default": "./dist/official.mjs"
+    },
+    "./profile-project": {
+      "types": "./dist/profile-project.d.mts",
+      "default": "./dist/profile-project.mjs"
+    },
+    "./seed": {
+      "types": "./dist/seed.d.mts",
+      "default": "./dist/seed.mjs"
+    },
+    "./inline-packages": {
+      "types": "./dist/inline-packages.d.mts",
+      "default": "./dist/inline-packages.mjs"
+    },
     "./package.json": "./package.json",
     "./locale/*.json": "./locale/*.json"
   },
   "dependencies": {
-    "electron": "^44.3.0"
+    "@deepseek-ai/dsh-util-crypto": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-util-values": "^0.2.1-rc.1",
+    "@morlay/dsh-desktop-host": "0.2.7"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-app-boot": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-atomic-write": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-shortcuts": "0.2.0-rc.2",
     "@local/devkit": "0.1.0",
-    "@morlay/dsh-desktop-host": "0.2.5",
-    "@types/node": "^26.5.0"
+    "@oxc-node/core": "^0.1.6",
+    "@types/node": "^26.5.0",
+    "electron": "44.7.0"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-atomic-write": "^0.2.0-rc.2",
-    "@deepseek-ai/dsh-client-shortcuts": "^0.2.0-rc.2"
+    "@deepseek-ai/dsh-app-boot": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-atomic-write": "^0.2.1-rc.1",
+    "@deepseek-ai/dsh-client-shortcuts": "^0.2.1-rc.1"
   },
   "engines": {
-    "node": ">=24.11.0"
+    "node": ">=24.11.0",
+    "dsh": ">= 0.2.1-rc.1 < 0.2.2"
   },
   "scripts": {
-    "build": "pnpm exec tsdown",
-    "gen:official-packages": "tsx scripts/gen-official-packages.ts"
+    "build": "pnpm exec tsdown"
   }
 }

package/src/__tests__/developer-endpoint.spec.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { nodeInspectorDevtoolsUrl } from "../developer-endpoint.ts";
+
+describe("后端调试前端地址", () => {
+  it("把 host 回报的端点拼成应用 origin 下的 DevTools 入口", () => {
+    expect(nodeInspectorDevtoolsUrl("dsh-custom-next", "ws://127.0.0.1:9229/7f0d-4a2b")).toBe(
+      "dsh-custom-next://app/node-devtools/devtools_app.html" +
+        "?ws=127.0.0.1:9229/7f0d-4a2b&panel=console&disableLocaleInfoBar=true",
+    );
+  });
+
+  it("非 WebSocket 端点与带查询分隔符的端点都拒绝", () => {
+    expect(() => nodeInspectorDevtoolsUrl("dsh-app", "http://127.0.0.1:9229/x")).toThrow();
+    expect(() => nodeInspectorDevtoolsUrl("dsh-app", "ws://127.0.0.1:9229/x?y=1&z=2")).toThrow();
+    expect(() => nodeInspectorDevtoolsUrl("dsh-app", "not a url")).toThrow();
+  });
+});

package/src/__tests__/document-marks.spec.ts

@@ -0,0 +1,42 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import {
+  WINDOWS_TITLEBAR_HEIGHT,
+  markDocumentPlatform,
+  markWindowsTitlebar,
+  syncNativeTheme,
+} from "../document-marks.ts";
+
+describe("桌面文档标记", () => {
+  it("macOS 打上 data-platform，客户端据此启用侧边栏顶部拖拽条与 logo 下沉", () => {
+    markDocumentPlatform("darwin", document);
+    expect(document.documentElement.dataset.platform).toBe("darwin");
+  });
+
+  it("Windows 打上 caption 标记与标题栏高度（其它平台不打）", () => {
+    markWindowsTitlebar("linux", document);
+    expect(document.documentElement.hasAttribute("data-windows-titlebar")).toBe(false);
+
+    markWindowsTitlebar("win32", document);
+    expect(document.documentElement.hasAttribute("data-windows-titlebar")).toBe(true);
+    expect(document.documentElement.style.getPropertyValue("--dsh-windows-titlebar-height")).toBe(
+      `${String(WINDOWS_TITLEBAR_HEIGHT)}px`,
+    );
+  });
+
+  it("只有 macOS 把主题来源转发给主进程，且只在值变化时发", async () => {
+    const sent: string[] = [];
+    syncNativeTheme("win32", document, (source) => sent.push(source));
+    document.documentElement.setAttribute("data-ds-theme-source", "dark");
+    expect(sent).toEqual([]);
+
+    syncNativeTheme("darwin", document, (source) => sent.push(source));
+    expect(sent).toEqual(["dark"]);
+    document.documentElement.setAttribute("data-ds-theme-source", "dark");
+    await Promise.resolve();
+    expect(sent).toEqual(["dark"]);
+    document.documentElement.setAttribute("data-ds-theme-source", "light");
+    await Promise.resolve();
+    expect(sent).toEqual(["dark", "light"]);
+  });
+});

package/src/__tests__/dshhome.spec.ts

@@ -0,0 +1,108 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join, normalize, resolve, sep } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { AppConfig } from "../appconfig.ts";
+import { resolveDshHome, xdgDataHome } from "../dshhome.ts";
+
+const ORIGINAL = {
+  override: process.env.DSH_APP_DSH_HOME,
+  xdg: process.env.XDG_DATA_HOME,
+};
+
+const roots: string[] = [];
+
+async function tempDir(): Promise<string> {
+  const root = await mkdtemp(resolve(tmpdir(), "dshdev-home-"));
+  roots.push(root);
+  return root;
+}
+
+function config(dataDir: string, name = "dsh-custom"): AppConfig {
+  return {
+    name,
+    displayName: name,
+    id: "ai.deepseek.dsh.custom",
+    version: "0.1.5",
+    profile: "desktop",
+    dataDir,
+    window: { width: 1280, height: 800, minWidth: 800, minHeight: 600 },
+  };
+}
+
+afterEach(async () => {
+  for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true });
+  if (ORIGINAL.override === undefined) delete process.env.DSH_APP_DSH_HOME;
+  else process.env.DSH_APP_DSH_HOME = ORIGINAL.override;
+  if (ORIGINAL.xdg === undefined) delete process.env.XDG_DATA_HOME;
+  else process.env.XDG_DATA_HOME = ORIGINAL.xdg;
+});
+
+describe("xdgDataHome", () => {
+  it.skipIf(process.platform !== "darwin")(
+    "uses the macOS application support directory and ignores XDG_DATA_HOME",
+    async () => {
+      process.env.XDG_DATA_HOME = await tempDir();
+
+      expect(xdgDataHome()).toBe(join(homedir(), "Library", "Application Support"));
+    },
+  );
+
+  it.skipIf(process.platform === "darwin")(
+    "honours XDG_DATA_HOME and otherwise falls back to ~/.local/share",
+    async () => {
+      const configured = await tempDir();
+      process.env.XDG_DATA_HOME = configured;
+      expect(xdgDataHome()).toBe(normalize(configured));
+
+      process.env.XDG_DATA_HOME = "   ";
+      expect(xdgDataHome()).toBe(join(homedir(), ".local", "share"));
+
+      delete process.env.XDG_DATA_HOME;
+      expect(xdgDataHome()).toBe(join(homedir(), ".local", "share"));
+    },
+  );
+});
+
+describe("resolveDshHome", () => {
+  it("appends the app name to the platform data home for xdg", () => {
+    delete process.env.DSH_APP_DSH_HOME;
+
+    expect(resolveDshHome(config("xdg"))).toBe(join(xdgDataHome(), "dsh-custom"));
+  });
+
+  it("reports no concrete home for env mode", () => {
+    delete process.env.DSH_APP_DSH_HOME;
+
+    expect(resolveDshHome(config("env"))).toBeUndefined();
+  });
+
+  it("takes an absolute path as-is", async () => {
+    delete process.env.DSH_APP_DSH_HOME;
+    const explicit = join(await tempDir(), "home");
+
+    expect(resolveDshHome(config(explicit))).toBe(explicit);
+  });
+
+  it("lets the environment override every configuration", async () => {
+    const override = await tempDir();
+    process.env.DSH_APP_DSH_HOME = override;
+    expect(resolveDshHome(config("xdg"))).toBe(override);
+    expect(resolveDshHome(config("env"))).toBe(override);
+
+    process.env.DSH_APP_DSH_HOME = "   ";
+    expect(resolveDshHome(config("env"))).toBeUndefined();
+    expect(resolveDshHome(config("xdg"))).toBe(join(xdgDataHome(), "dsh-custom"));
+  });
+
+  it("rejects a non-absolute path that is not a known mode", () => {
+    delete process.env.DSH_APP_DSH_HOME;
+
+    expect(() => resolveDshHome(config(`.${sep}data`))).toThrow(
+      /dataDir must be xdg, env, or an absolute path/u,
+    );
+    expect(() => resolveDshHome(config("~/data"))).toThrow(
+      /dataDir must be xdg, env, or an absolute path/u,
+    );
+  });
+});