@morlay/dsh-desktop-shell 0.2.4 → 0.2.6

package/src/inline-packages.ts

@@ -0,0 +1,18 @@
+/**
+ * 壳产物里要**内联**的包（而不是留在产物外）。
+ *
+ * 壳跑在 `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 const SHELL_INLINE_PACKAGES: readonly string[] = [
+  "@morlay/dsh-desktop-host",
+  "@deepseek-ai/dsh-client-shortcuts",
+  "@deepseek-ai/dsh-atomic-write",
+  "@deepseek-ai/dsh-util-values",
+  "@deepseek-ai/dsh-util-crypto",
+];

package/src/ipc.ts

@@ -0,0 +1,58 @@
+import type { IpcMainInvokeEvent } from "electron";
+
+/** 壳把宿主回环的 ws 端口经 preload 递进页面（`additionalArguments`，与 scheme 同一手法）。 */
+export const DESKTOP_WS_PORT_ARGUMENT = "--dsh-desktop-ws-port";
+
+export const DESKTOP_IPC = {
+  directoryPick: "dsh-desktop:directory-pick",
+  nativeThemeSet: "dsh-desktop:native-theme-set",
+  // 桌面流载体：页面把 Gateway 的流请求交给主进程，主进程用标准 Request 喂宿主。
+  streamOpen: "dsh-desktop:stream-open",
+  streamCancel: "dsh-desktop:stream-cancel",
+  // 逻辑流的上行项（客户端 → 宿主），主进程把它们写成宿主请求体的后续行。
+  streamUplink: "dsh-desktop:stream-uplink",
+  // 上行结束：主进程据此结束宿主请求体。
+  streamUplinkEnd: "dsh-desktop:stream-uplink-end",
+  streamChunk: "dsh-desktop:stream-chunk",
+  streamEnd: "dsh-desktop:stream-end",
+  streamError: "dsh-desktop:stream-error",
+  // 桌面快捷键：设备偏好的读写 / 录制状态（渲染进程 → 主进程）。
+  shortcutsGet: "dsh-desktop:shortcuts-get",
+  shortcutsEdit: "dsh-desktop:shortcuts-edit",
+  shortcutsRecording: "dsh-desktop:shortcuts-recording",
+  shortcutsCloseWindow: "dsh-desktop:shortcuts-close-window",
+  // 命中的原生按键手势（主进程 → 渲染进程）；渲染侧的 native keyboard 适配器消费。
+  shortcutsInput: "dsh-desktop:shortcuts-input",
+  // 配置快照变化（主进程 → 渲染进程）。
+  shortcutsChanged: "dsh-desktop:shortcuts-changed",
+} as const;
+
+// preload 从渲染进程 argv 里读回 scheme 的参数名（主进程与 preload 共用一份）。
+export const DESKTOP_SCHEME_ARGUMENT = "--dsh-desktop-scheme";
+
+// 应用页面的自定义协议：取 app 工作区 package.json 的 name 派生，避免与官方桌面应用
+// 共用同一个 scheme。去 scope 前缀、转小写、非法字符换成 `-`；派生不出合法 scheme 就报错。
+export function desktopScheme(name: string): string {
+  const bare = name
+    .slice(name.lastIndexOf("/") + 1)
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9+.-]/gu, "-");
+  if (!/^[a-z][a-z0-9+.-]*$/u.test(bare))
+    throw new Error(
+      `dsh desktop: application name "${name}" does not yield a usable URL scheme (${bare})`,
+    );
+  return bare;
+}
+
+export function assertDesktopSender(
+  event: IpcMainInvokeEvent,
+  scheme: string,
+  hostnames: readonly string[],
+): void {
+  const senderFrame = event.senderFrame;
+  if (senderFrame === null) throw new Error("dsh desktop: rejected IPC without a sender frame");
+  const url = new URL(senderFrame.url);
+  if (url.protocol !== `${scheme}:` || !hostnames.includes(url.hostname)) {
+    throw new Error("dsh desktop: rejected IPC from an unowned renderer");
+  }
+}

package/src/keybindings.ts

@@ -0,0 +1,35 @@
+// 设备本地的快捷键偏好（Electron userData 下）：原子替换、单写者协调。
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
+import { ShortcutPersistence } from "@deepseek-ai/dsh-client-shortcuts/protocol";
+import type {
+  ShortcutConfigSnapshot,
+  ShortcutPlatform,
+} from "@deepseek-ai/dsh-client-shortcuts/protocol";
+
+// 打开设备配置（原子替换），返回单写者事务协调器；`userData` 不接受渲染进程给的路径。
+export function desktopKeybindings(
+  userData: string,
+  platform: ShortcutPlatform,
+  publish: (snapshot: ShortcutConfigSnapshot) => void,
+): ShortcutPersistence {
+  const path = join(userData, "keybindings.json");
+  return new ShortcutPersistence(
+    {
+      read: async () => {
+        try {
+          return await readFile(path, "utf8");
+        } catch (error: unknown) {
+          if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+          throw error;
+        }
+      },
+      write: (raw) => writeFileAtomic(path, raw, { mode: 0o600, dirMode: 0o700 }),
+    },
+    "desktop",
+    platform,
+    false,
+    publish,
+  );
+}

package/src/official.ts

@@ -0,0 +1,8 @@
+// 工具自带的桌面 host 变体包（不是上游 private 应用）：部署里按这个名字落位。
+export const DESKTOP_HOST_PACKAGE = "@morlay/dsh-desktop-host";
+
+// 官方那两个 bundle：`dsh.profile.bundles` 里属于"官方侧"的名单（app 自己声明的 bundle 按它分家）。
+export const OFFICIAL_PROFILE_BUNDLES: readonly string[] = [
+  "@deepseek-ai/dsh-base",
+  "@deepseek-ai/dsh-web-app",
+];

package/src/preload-app.ts

@@ -0,0 +1,147 @@
+import { contextBridge, ipcRenderer, webFrame } from "electron";
+import { markDocumentPlatform, markWindowsTitlebar, syncNativeTheme } from "./document-marks.ts";
+import { DESKTOP_IPC, DESKTOP_SCHEME_ARGUMENT, DESKTOP_WS_PORT_ARGUMENT } from "./ipc.ts";
+import { createStreamUplink } from "./stream-uplink.ts";
+
+interface StreamChunk {
+  readonly id: number;
+  readonly status?: number;
+  readonly data?: string;
+  readonly message?: string;
+}
+
+// scheme 取自 app 名，只有主进程知道；sandboxed preload 里只能从 argv 读回。
+const scheme = process.argv
+  .find((argument) => argument.startsWith(`${DESKTOP_SCHEME_ARGUMENT}=`))
+  ?.slice(DESKTOP_SCHEME_ARGUMENT.length + 1);
+
+// 宿主进程内回环的 ws 端口：页面把 `ws://app/…` 重写到它，就能用原生 WebSocket（垫片见
+// `@morlay/dsh-client-modules` 的 `app-boot/desktop-ws-shim.ts`）。
+const wsPort = process.argv
+  .find((argument) => argument.startsWith(`${DESKTOP_WS_PORT_ARGUMENT}=`))
+  ?.slice(DESKTOP_WS_PORT_ARGUMENT.length + 1);
+
+// preload 只在壳里跑（`scheme` 由壳经 argv 传来），所以"是不是桌面形态"看它就够——**不再**要求
+// "页面在 `dsh-custom-next:` 协议下、hostname 是 `app`"：窗口现在从宿主真 webServer 的 origin
+// （`http://127.0.0.1:<port>`）载入，那个条件永远不成立，会让下面这些桌面专用注入整块失效。
+if (scheme !== undefined && scheme !== "") {
+  // preload 脚本**跑在页面里**（浏览器没有 cordis 树，也没有壳的日志出口）：这里的 console 是页面日志。
+  console.log(
+    `[dsh-shell] preload: scheme=${String(scheme)} wsPort=${String(wsPort)} webFrame=${typeof webFrame}`,
+  );
+  contextBridge.exposeInMainWorld("__DSH_DIRECTORY_PICKER__", {
+    pick: () => ipcRenderer.invoke(DESKTOP_IPC.directoryPick) as Promise<string | null>,
+  });
+  // 页面 fetch 到自定义协议时请求体不可靠（POST 场景会挂住），桌面流改走主进程；
+  // 返回的 send / end 是逻辑流的上行（页面侧 uplink）：主进程把它们写成宿主请求体的后续行。
+  contextBridge.exposeInMainWorld("__DSH_DESKTOP_STREAM__", {
+    open(
+      endpoint: string,
+      payload: unknown,
+      handlers: {
+        chunk(text: string): void;
+        end(): void;
+        fail(message: string): void;
+      },
+    ): {
+      cancel(): void;
+      send(item: unknown): void;
+      end(): void;
+    } {
+      let id: number | undefined;
+      let cancelled = false;
+      const uplink = createStreamUplink(
+        (streamId, item) => {
+          ipcRenderer.send(DESKTOP_IPC.streamUplink, streamId, item);
+        },
+        (streamId) => {
+          ipcRenderer.send(DESKTOP_IPC.streamUplinkEnd, streamId);
+        },
+      );
+      const onChunk = (_event: unknown, value: StreamChunk): void => {
+        if (value.id !== id || value.data === undefined) return;
+        handlers.chunk(value.data);
+      };
+      const onEnd = (_event: unknown, value: StreamChunk): void => {
+        if (value.id === id) handlers.end();
+      };
+      const onError = (_event: unknown, value: StreamChunk): void => {
+        if (value.id === id) handlers.fail(value.message ?? "desktop stream failed");
+      };
+      ipcRenderer.on(DESKTOP_IPC.streamChunk, onChunk);
+      ipcRenderer.on(DESKTOP_IPC.streamEnd, onEnd);
+      ipcRenderer.on(DESKTOP_IPC.streamError, onError);
+      void ipcRenderer
+        .invoke(DESKTOP_IPC.streamOpen, endpoint, payload)
+        .then((opened: unknown) => {
+          id = opened as number;
+          if (cancelled) {
+            ipcRenderer.send(DESKTOP_IPC.streamCancel, id);
+            return;
+          }
+          uplink.bind(id);
+        })
+        .catch((error: unknown) => {
+          handlers.fail(error instanceof Error ? error.message : String(error));
+        });
+      return {
+        cancel() {
+          if (cancelled) return;
+          cancelled = true;
+          ipcRenderer.off(DESKTOP_IPC.streamChunk, onChunk);
+          ipcRenderer.off(DESKTOP_IPC.streamEnd, onEnd);
+          ipcRenderer.off(DESKTOP_IPC.streamError, onError);
+          if (id !== undefined) ipcRenderer.send(DESKTOP_IPC.streamCancel, id);
+        },
+        send(item) {
+          if (!cancelled) uplink.push(item);
+        },
+        end() {
+          if (!cancelled) uplink.close();
+        },
+      };
+    },
+  });
+}
+
+markDocumentPlatform(process.platform, document);
+markWindowsTitlebar(process.platform, document);
+
+// 上游 client 半按 `data-platform` 判定 desktop 运行时，并在那时**要求**这份桥存在
+// （`@deepseek-ai/dsh-client-shortcuts` 的 client 半缺它就直接构造失败）。
+contextBridge.exposeInMainWorld("dshDesktop", {
+  protocolVersion: 1,
+  keyboard: {
+    subscribe(listener: (input: unknown) => void): () => void {
+      const handle = (_event: unknown, input: unknown): void => {
+        listener(input);
+      };
+      ipcRenderer.on(DESKTOP_IPC.shortcutsInput, handle);
+      return () => {
+        ipcRenderer.off(DESKTOP_IPC.shortcutsInput, handle);
+      };
+    },
+    closeWindow: (revision: string) =>
+      ipcRenderer.invoke(DESKTOP_IPC.shortcutsCloseWindow, revision) as Promise<void>,
+  },
+  shortcuts: {
+    get: (definitions: unknown) => ipcRenderer.invoke(DESKTOP_IPC.shortcutsGet, definitions),
+    edit: (edit: unknown, revision: string) =>
+      ipcRenderer.invoke(DESKTOP_IPC.shortcutsEdit, edit, revision),
+    subscribe(listener: (snapshot: unknown) => void): () => void {
+      const handle = (_event: unknown, snapshot: unknown): void => {
+        listener(snapshot);
+      };
+      ipcRenderer.on(DESKTOP_IPC.shortcutsChanged, handle);
+      return () => {
+        ipcRenderer.off(DESKTOP_IPC.shortcutsChanged, handle);
+      };
+    },
+    recording: (active: boolean) =>
+      ipcRenderer.invoke(DESKTOP_IPC.shortcutsRecording, active) as Promise<void>,
+  },
+});
+
+syncNativeTheme(process.platform, document, (source) => {
+  ipcRenderer.send(DESKTOP_IPC.nativeThemeSet, source);
+});

package/src/profile-project.ts

@@ -0,0 +1,138 @@
+// Desktop profile project: the files the seed ships and the package operations the launcher runs.
+//
+// 种子里只带 app 自己的 bundle（`file:` 指向随包 `vendor/` 副本）；官方包与 dsh 来自不可变 runtime，
+// profile 对它们的依赖经 `overrides` 用 `link:` 指回 runtime——安装因此不需要 registry。
+
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// Profile pnpm settings file the launcher appends run-time `overrides` to.
+export const PROFILE_WORKSPACE_NAME = "pnpm-workspace.yaml";
+
+// Seed-written report naming the runtime packages the profile resolves through `overrides`.
+export const PROFILE_RUNTIME_REPORT_NAME = "desktop-runtime-packages.json";
+
+// Profile directory holding the `file:` sources of the profile's own bundles.
+export const PROFILE_VENDOR_DIR_NAME = "vendor";
+
+// One package the profile dependency graph links to the installed runtime.
+export interface RuntimeOverride {
+  // Package name as it appears in the profile's dependency graph.
+  readonly name: string;
+  // Absolute directory inside the installed runtime holding that package.
+  readonly target: string;
+}
+
+const TOP_LEVEL_KEY = /^([A-Za-z_][A-Za-z0-9_-]*):(?:[ \t]|$)/u;
+
+// Read the seed's runtime package report and point each entry at the installed runtime: one `link:`
+// override per reported package, in report order. Throws when the report is missing, malformed, or
+// holds an invalid entry.
+export async function runtimeOverrides(
+  profileDir: string,
+  runtimeDir: string,
+): Promise<RuntimeOverride[]> {
+  const report = JSON.parse(
+    await readFile(join(profileDir, PROFILE_RUNTIME_REPORT_NAME), "utf8"),
+  ) as { runtimePackages?: unknown };
+  const entries = report.runtimePackages;
+  if (!Array.isArray(entries) || !entries.every(isRuntimePackage)) {
+    throw new Error(
+      `dsh desktop: ${PROFILE_RUNTIME_REPORT_NAME} has an invalid runtimePackages list`,
+    );
+  }
+  return entries.map((entry) => ({
+    name: entry.name,
+    target: join(runtimeDir, ...entry.path.split("/")),
+  }));
+}
+
+// One reported runtime package: its dependency name and its runtime-relative directory.
+function isRuntimePackage(
+  value: unknown,
+): value is { readonly name: string; readonly path: string } {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as { name?: unknown; path?: unknown };
+  return (
+    typeof candidate.name === "string" &&
+    candidate.name !== "" &&
+    typeof candidate.path === "string" &&
+    candidate.path !== ""
+  );
+}
+
+// Write the runtime overrides into profile pnpm settings, replacing an earlier generation; an empty
+// override list leaves the file untouched. Returns the settings text to write.
+export function workspaceWithOverrides(
+  text: string,
+  overrides: readonly RuntimeOverride[],
+): string {
+  if (overrides.length === 0) return text;
+  const kept: string[] = [];
+  let skipping = false;
+  for (const line of text.replaceAll("\r\n", "\n").split("\n")) {
+    const key = TOP_LEVEL_KEY.exec(line)?.[1];
+    if (key !== undefined) skipping = key === "overrides";
+    if (!skipping) kept.push(line);
+  }
+  while (kept.length > 0 && (kept[kept.length - 1] ?? "").trim() === "") kept.pop();
+  const block = [
+    "overrides:",
+    ...overrides.map(
+      (entry) => `  ${JSON.stringify(entry.name)}: ${JSON.stringify(`link:${entry.target}`)}`,
+    ),
+  ];
+  return `${[...kept, ...block].join("\n")}\n`;
+}
+
+// Injection point for the profile installation process.
+export type ProfileInstallSpawn = typeof spawn;
+
+// Inputs for one offline profile installation.
+export interface ProfileInstallOptions {
+  // Bundled Node.js executable running pnpm.
+  readonly node: string;
+  // Bundled pnpm entry (`.mjs`) inside the runtime.
+  readonly pnpmEntry: string;
+  // Profile directory whose dependencies are installed.
+  readonly profileDir: string;
+  // Process launcher, injectable for tests.
+  readonly spawn?: ProfileInstallSpawn;
+}
+
+// Install the profile's own bundles offline from the seed's `file:` sources. Throws when pnpm cannot
+// start or exits non-zero, with its diagnostics tail.
+export function installProfile(options: ProfileInstallOptions): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const spawnChild = options.spawn ?? spawn;
+    const child = spawnChild(
+      options.node,
+      [options.pnpmEntry, "install", "--prod", "--ignore-scripts", "--offline"],
+      { cwd: options.profileDir, stdio: ["ignore", "pipe", "pipe"] },
+    );
+    let stderr = "";
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk: string) => {
+      stderr = (stderr + chunk).slice(-4096);
+    });
+    // 消费 stdout，避免管道回压把 pnpm 卡在写日志上。
+    child.stdout?.on("data", () => undefined);
+    child.once("error", (error) => {
+      reject(error);
+    });
+    child.once("close", (code) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const diagnostic = stderr.trim();
+      reject(
+        new Error(
+          `dsh desktop: profile install exited with ${String(code)}` +
+            `${diagnostic === "" ? "" : `: ${diagnostic}`}`,
+        ),
+      );
+    });
+  });
+}

package/src/seed.ts

@@ -0,0 +1,183 @@
+import { spawn } from "node:child_process";
+import type { Stats } from "node:fs";
+import {
+  access,
+  chmod,
+  copyFile,
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  readlink,
+  rm,
+  symlink,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { PROFILE_NAME, PROFILE_PATCH_NAME } from "./appconfig.ts";
+
+export const SEED_DIR_NAME = "dsh-home";
+
+export const SEED_HASH_NAME = ".seed-hash";
+
+// Seed-relative directory holding the immutable runtime: the host's dsh installation and the Web frontend.
+export const SEED_RUNTIME_DIR_NAME = "runtime";
+
+const SEED_SKIP_DIRS = new Set([".nub-store", ".store", ".nub"]);
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readSeedHash(path: string): Promise<string> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await lstat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** 解压随包的依赖归档：实体文件、闭包完整（替代逐包 `link:` 那种写法）。 */
+async function extractProfileModules(archive: string, profileDir: string): Promise<void> {
+  await new Promise<void>((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(new Error(`tar -xzf ${archive} exited with ${String(code)}`)),
+    );
+  });
+}
+
+export const PROFILE_MODULES_ARCHIVE_NAME = "profile-node-modules.tar";
+
+/** 一次"种 profile"的结果：调用方据此记录、并在打包形态把 `no-seed` 当致命。 */
+export type SeedOutcome = "seeded" | "up-to-date" | "no-seed";
+
+/** 依赖面是否真的在：`node_modules` 存在且非空。 */
+async function hasDependencies(profileDir: string): Promise<boolean> {
+  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 归档解压失败、或解压后没有依赖面时。
+ */
+export async function ensureSeedProfile(seedDir: string, home: string): Promise<SeedOutcome> {
+  const seedProfile = join(seedDir, "profiles", PROFILE_NAME);
+  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 {
+      const stat = await lstat(profileDir);
+      if (
+        !stat.isSymbolicLink() &&
+        (await readSeedHash(join(profileDir, SEED_HASH_NAME))) === seedHash &&
+        (!hasArchive || (await hasDependencies(profileDir)))
+      ) {
+        return "up-to-date";
+      }
+    } catch {}
+  }
+  // profile 的 patch 文档是用户数据（settings 面板写在那里）：重种换的是装配面，
+  // 这一份先读出来、种完再放回去，升级不会把用户的设置带走。
+  const patchPath = join(profileDir, PROFILE_PATCH_NAME);
+  const userPatch = await readFile(patchPath, "utf8").catch(() => undefined);
+
+  try {
+    const stat = await lstat(profileDir);
+    if (stat.isSymbolicLink()) await unlink(profileDir);
+    else if (stat.isDirectory()) await rm(profileDir, { recursive: true });
+    else await unlink(profileDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  await copySeed(seedProfile, profileDir);
+
+  // **profile 的依赖面**：随包那份归档解压进来（实体文件、闭包完整）。历史做法是壳按载荷清单逐包
+  // `link:`——`link` 不带传递依赖（上千个包会丢），路径还指向构建机（`.pnpm/<pkg>@file++++Users+…`）。
+  if (hasArchive) {
+    await rm(join(profileDir, "node_modules"), { recursive: true, force: true });
+    await extractProfileModules(archive, profileDir);
+    // **解压之后自检**：tar 退出码 0 不等于"闭包真的落地了"；种出来的东西不完整就该当场报，
+    // 而不是让宿主带着残缺 profile 起一次（那只能表现为"组件不完整"）。
+    if (!(await hasDependencies(profileDir))) {
+      throw new Error(
+        `dsh desktop: ${archive} did not yield a dependency closure at ${join(profileDir, "node_modules")}`,
+      );
+    }
+  }
+  if (userPatch !== undefined) {
+    await mkdir(dirname(patchPath), { recursive: true });
+    await writeFile(patchPath, userPatch);
+  }
+  return "seeded";
+}
+
+// Plant one profile subtree. The seed's runtime lives beside the profile and stays in the
+// application's read-only resources, so only `profiles/<name>` is copied into the home.
+async function copySeed(source: string, target: string): Promise<void> {
+  await mkdir(target, { recursive: true });
+  const visit = async (directory: string, prefix: string): Promise<void> => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      const relativePath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      const destination = join(target, ...relativePath.split("/"));
+      if (entry.isSymbolicLink()) {
+        if (await pathExists(destination)) continue;
+        await mkdir(dirname(destination), { recursive: true });
+        await symlink(
+          await readlink(path),
+          destination,
+          process.platform === "win32" ? "junction" : "dir",
+        );
+        continue;
+      }
+      let stat: Stats;
+      try {
+        stat = await lstat(path);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        if (SEED_SKIP_DIRS.has(entry.name)) continue;
+        await mkdir(destination, { recursive: true });
+        await visit(path, relativePath);
+        continue;
+      }
+      if (!stat.isFile() || (await pathExists(destination))) continue;
+      await mkdir(dirname(destination), { recursive: true });
+      await copyFile(path, destination);
+      await chmod(destination, stat.mode & 0o777);
+    }
+  };
+  await visit(source, "");
+}

package/src/shell-env.ts

@@ -0,0 +1,31 @@
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { basename } from "node:path";
+
+export function rcFileFor(shell: string): string {
+  switch (basename(shell)) {
+    case "bash":
+      return "~/.bashrc";
+    case "zsh":
+      return "~/.zshrc";
+    default:
+      return "";
+  }
+}
+
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+export function shellWrappedSpawn(
+  command: string,
+  args: readonly string[],
+  options: SpawnOptions,
+): ChildProcess {
+  const shell = process.env.SHELL;
+  const rc = shell === undefined || shell === "" ? "" : rcFileFor(shell);
+  if (rc !== "" && process.platform !== "win32" && shell !== undefined) {
+    const commandLine = `source ${rc} >/dev/null 2>&1; exec ${shellQuote(command)} ${args.map(shellQuote).join(" ")}`;
+    return spawn(shell, ["-c", commandLine], { ...options, detached: true });
+  }
+  return spawn(command, [...args], { ...options, detached: process.platform !== "win32" });
+}