dsh-superagent-console 0.1.0 → 0.1.2

package/README.md

@@ -33,9 +33,11 @@ vendor 补丁（seams）：`sync-client.mjs` 在每次 vendor 复制后，对 `c
 | L0 | 服务端 fetch `{target}/orchestrator/api/state`（带 `x-orchestrator-request: 1`） | 引擎可达 |
 | L1 | `~/.dsh/profiles/<profile>/package.json` 依赖含 `dsh-superagent` + checkout 有 `lib/` 产物 | 服务已部署 |
 | L2 | `scripts/dsh-superagent status`（exit 0 健康 / 1 停止 / 2 组件错误 / 3 等待 setup） | 健康细分 |
-| L3 | dsh ≥0.2.1、node ^22.19\|\|≥24、pnpm、git、tmux、python3 | 前置依赖 |
+| L3 | dsh ≥0.2.1、node ^22.19\|\|≥24、pnpm、git、tmux、python3（缺项附补齐提示命令） | 前置依赖 |
 
-状态 → 动作一一映射：`running` → 官方面板；`installed-stopped` → 启动按钮；`installed-unhealthy` → 重启按钮；`not-installed` → 在线安装；`prereq-missing` → 列出缺项（不提供安装按钮）。
+状态 → 动作一一映射：`running` → 官方面板；`installed-stopped` → 启动按钮；`installed-unhealthy` → 重启按钮；`not-installed` → 在线安装；`prereq-missing` → 列出缺项与补齐命令（不提供安装按钮）。
+
+探测 PATH 由 `spawnPath` 组装：运行中 node 的 bin 目录 + 配置的 `extraPath` + **桌面 App 自带的 dsh CLI 目录**（从运行中二进制相对推导 `<App>.app/Contents/Resources/runtime/cli/bin`，存在才追加）。因此桌面用户无需自行安装 dsh；`extraPath` 中显式安装的用户版本优先于内置 CLI。
 
 ## 在线安装流水线（8 段）
 

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Mount the console plugin itself (UI proxy only; the engine stays in its own profile).
+- insert:
+    - id: dsh-superagent-console
+      name: 'dsh-superagent-console'

package/lib/client.js

@@ -7852,7 +7852,12 @@ window.__ModuleLoader__.load({
 				children: props.label
 			});
 		}
-		function PrereqList({ prereqs, title }) {
+		function PrereqList({ prereqs, title, st }) {
+			const copy = (text) => {
+				const clip = navigator.clipboard;
+				if (!clip) return;
+				clip.writeText(text).catch(() => void 0);
+			};
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				style: { marginTop: 16 },
 				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
@@ -7865,13 +7870,45 @@ window.__ModuleLoader__.load({
 					},
 					children: prereqs.map((item) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("li", {
 						style: { color: item.ok ? "inherit" : "var(--dsh-danger, #d64545)" },
-						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", {
-							style: monoStyle,
-							children: item.name
-						}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
-							style: { opacity: .75 },
-							children: [" — ", item.detail]
-						})]
+						children: [
+							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", {
+								style: monoStyle,
+								children: item.name
+							}),
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+								style: { opacity: .75 },
+								children: [" — ", item.detail]
+							}),
+							!item.ok && item.hint && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+								style: {
+									display: "inline-flex",
+									alignItems: "center",
+									gap: 6,
+									marginLeft: 8
+								},
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("code", {
+									style: {
+										...monoStyle,
+										opacity: .85
+									},
+									children: item.hint
+								}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									onClick: () => {
+										copy(item.hint ?? "");
+									},
+									style: {
+										...buttonStyle,
+										padding: "1px 8px",
+										fontSize: 11,
+										borderRadius: 6,
+										color: "inherit",
+										borderColor: "var(--dsh-border, rgba(128,128,128,.4))"
+									},
+									children: st("copyCommand")
+								})]
+							})
+						]
 					}, item.name))
 				})]
 			});
@@ -8084,7 +8121,8 @@ window.__ModuleLoader__.load({
 					}),
 					(status.state === "not-installed" || status.state === "prereq-missing" || installing) && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PrereqList, {
 						prereqs: status.prereqs,
-						title: st("prereqsTitle")
+						title: st("prereqsTitle"),
+						st
 					}),
 					(installing || status.setup.current || STAGES.some((id) => status.setup.stages[id]?.status !== "pending")) && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(StageList, {
 						setup: status.setup,
@@ -8166,7 +8204,7 @@ window.__ModuleLoader__.load({
 			descStopped: "引擎服务处于停止状态，可以一键拉起（tmux 会话由生命周期脚本托管）。",
 			descUnhealthy: "引擎进程存在但管理 API 不可达或组件报错，可尝试重启。",
 			descNotInstalled: "引擎运行在独立的 DSH profile 中。点击安装后，控制台会在线拉取官方源码、自动构建并部署到独立 profile（npm 上无此包，源码构建是官方唯一安装路径）。",
-			descPrereq: "在线安装需要以下工具，请先补齐后再安装（凭据类操作仍需本人完成）。",
+			descPrereq: "在线安装需要以下工具，红项按提示命令补齐后点「重试」（凭据类操作仍需本人完成）。",
 			install: "在线安装引擎",
 			installResume: "继续安装",
 			installing: "正在安装…",
@@ -8176,6 +8214,7 @@ window.__ModuleLoader__.load({
 			starting: "正在启动…",
 			restarting: "正在重启…",
 			prereqsTitle: "前置依赖",
+			copyCommand: "复制",
 			stageTitle: "安装进度",
 			setupWait: "引擎已启动，正在等待首次配置（Source 设置需在引擎面板完成）。",
 			manuallyStopped: "引擎带有手动停止标记，已按需忽略。",
@@ -8196,7 +8235,7 @@ window.__ModuleLoader__.load({
 			descStopped: "The engine service is stopped. Start it with one click (the tmux session is managed by the lifecycle script).",
 			descUnhealthy: "The engine process exists but the management API is unreachable or a component reports an error. Try a restart.",
 			descNotInstalled: "The engine runs in its own dedicated DSH profile. Installing fetches the official source online, builds it, and deploys it into that profile (the package is not published to npm; source build + link is the only official path).",
-			descPrereq: "The online installer needs the tools below. Install them first (credential steps stay yours).",
+			descPrereq: "The online installer needs the tools below — fix failing entries with the suggested command, then Retry (credential steps stay yours).",
 			install: "Install engine online",
 			installResume: "Resume install",
 			installing: "Installing…",
@@ -8206,6 +8245,7 @@ window.__ModuleLoader__.load({
 			starting: "Starting…",
 			restarting: "Restarting…",
 			prereqsTitle: "Prerequisites",
+			copyCommand: "Copy",
 			stageTitle: "Install progress",
 			setupWait: "Engine is up and waiting for first-time setup (Source configuration happens in the engine panel).",
 			manuallyStopped: "The engine carries a manual-stop marker; honored on demand.",

package/lib/index.d.ts

@@ -28,6 +28,8 @@ interface Prereq {
   name: string;
   ok: boolean;
   detail: string;
+  /** Suggested remediation command for a failed check; absent when none applies. */
+  hint?: string;
 }
 interface EngineHealth {
   exit: number;

package/lib/index.js

@@ -37,13 +37,31 @@ const Config = z.object({
 * Every spawn goes through `execFile` with an argv array (never a shell
 * string), an explicit timeout, and an augmented PATH: the desktop app
 * process may run with a minimal GUI PATH, so the node installation bin
-* directory and the configured `extraPath` entries are prepended.
+* directory, the configured `extraPath` entries, and the app's bundled
+* dsh CLI directory are prepended (in that order; user entries win).
 */
 const MAX_BUFFER = 16777216;
-/** PATH prepended for every spawned tool: the running node's bin dir plus the configured extras. */
+/**
+* Directory of the dsh CLI shipped inside the desktop app bundle: the
+* Electron binary lives at `<App>.app/Contents/MacOS/<bin>`, so the bundled
+* CLI resolves to `../Resources/runtime/cli/bin`. Null outside an app
+* bundle (plain node runs, tests) or when the bundle carries no CLI.
+* Uncached on purpose: spawns are rare and the probe is one existsSync.
+*/
+function bundledCliDir(execPath = process.execPath) {
+	const candidate = path.join(path.dirname(execPath), "..", "Resources", "runtime", "cli", "bin");
+	return existsSync(path.join(candidate, "dsh")) ? candidate : null;
+}
+/**
+* PATH prepended for every spawned tool: the running node's bin dir, the
+* configured extras, the app's bundled CLI dir (fallback only, so an
+* explicit user install keeps winning), then the inherited PATH.
+*/
 function spawnPath(extraPath) {
 	const parts = [path.dirname(process.execPath)];
 	if (extraPath) parts.push(...extraPath.split(":").filter(Boolean));
+	const bundled = bundledCliDir();
+	if (bundled) parts.push(bundled);
 	const inherited = process.env.PATH ?? "";
 	return [...parts, inherited].filter(Boolean).join(":");
 }
@@ -220,7 +238,13 @@ async function engineHealth(engineDir, profileName, target, env = {}) {
 		};
 	}
 }
-/** L3: toolchain probe; never throws, missing tools surface as ok:false entries. */
+/** Locale-neutral remediation commands surfaced next to a failed check (darwin only). */
+function missingHint(name) {
+	if (process.platform !== "darwin") return void 0;
+	if (name === "tmux") return "brew install tmux";
+	if (name === "pnpm") return "npm install -g pnpm";
+}
+/** L3: toolchain probe; never throws, missing tools surface as ok:false entries (with a hint where one applies). */
 async function prereqCheck(env = {}) {
 	const checks = [nodeOk()];
 	for (const tool of TOOL_CHECKS) {
@@ -233,7 +257,8 @@ async function prereqCheck(env = {}) {
 			checks.push({
 				name: tool.name,
 				ok: false,
-				detail: result.code === -1 ? "not found on PATH" : tail(output, 200)
+				detail: result.code === -1 ? "not found on PATH" : tail(output, 200),
+				hint: missingHint(tool.name)
 			});
 			continue;
 		}
@@ -242,7 +267,8 @@ async function prereqCheck(env = {}) {
 		checks.push({
 			name: tool.name,
 			ok,
-			detail: ok ? version : `${version} (needs >= ${tool.min})`
+			detail: ok ? version : `${version} (needs >= ${tool.min})`,
+			hint: ok ? void 0 : missingHint(tool.name)
 		});
 	}
 	return checks;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-superagent-console",
   "description": "Desktop console for the Superagent engine: the official panel embedded over a same-origin proxy. Detects the engine's state, installs it online (source build into a dedicated profile) when missing, and starts/restarts it on demand; the engine stays resident across desktop restarts.",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "license": "MIT",
   "author": "Shuai-S",
   "type": "module",
@@ -16,7 +16,8 @@
   },
   "files": [
     "lib",
-    "locale/*.json"
+    "locale/*.json",
+    "cordis.patch.yml"
   ],
   "engines": {
     "node": "^22.19.0 || >=24.0.0"