@fonlan/dsh-quick-commands 0.1.7 → 0.1.9

package/lib/index.js

@@ -1,7 +1,141 @@
 import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import z from "@deepseek-ai/schemastery";
+//#region src/server/shell-path.ts
+/**
+* Login-shell PATH resolution for the local quick-command backend.
+*
+* `dsh web` started from a terminal inherits the user's full PATH, so a
+* configured command such as `npm run typecheck` or `docker compose up -d`
+* finds its toolchain. **DSH Desktop does not**: the Electron host is launched
+* by launchd and runs with the minimal system PATH
+* (`/usr/bin:/bin:/usr/sbin:/sbin`), which hides homebrew, `/usr/local/bin`,
+* nvm, corepack and Docker Desktop. Every command that leans on the user's
+* toolchain then fails with "command not found" in Desktop while the very same
+* profile keeps working in a browser-launched host.
+*
+* This module asks the user's interactive login shell for its PATH once
+* (cached for the process lifetime) and prepends it to the inherited PATH for
+* local runs. Resolution is best effort by design: a missing `$SHELL`, a
+* timeout, a non-zero exit or unparseable output all leave the inherited PATH
+* untouched, so a terminal-launched host behaves exactly as before.
+*/
+/** Delimiters wrapping the shell's own PATH in the probe's stdout. */
+const PATH_START = "__DSH_QC_PATH_START__";
+const PATH_END = "__DSH_QC_PATH_END__";
+const defaultRunner = (file, args, options) => new Promise((resolve, reject) => {
+	execFile(file, args, options, (error, stdout) => {
+		if (error) reject(error);
+		else resolve({ stdout });
+	});
+});
+/**
+* Extract the PATH a shell printed between the markers.
+*
+* Login profiles are free to print their own noise (nvm notices, version
+* managers, MOTDs), so only the marked span counts — never the whole stdout.
+* @param stdout - raw probe stdout.
+* @returns the marked PATH, or '' when the markers are missing.
+*/
+function extractShellPath(stdout) {
+	if (typeof stdout !== "string" && !(stdout instanceof Buffer)) return "";
+	const text = String(stdout);
+	const start = text.indexOf(PATH_START);
+	const end = text.lastIndexOf(PATH_END);
+	if (start < 0 || end < 0 || end < start) return "";
+	return text.slice(start + 21, end);
+}
+/**
+* Put the login-shell PATH in front of the inherited one.
+*
+* The login PATH wins (that is where the user's toolchain lives); entries from
+* the inherited PATH stay behind it as a fallback. Empty entries are dropped
+* and duplicates keep their first position.
+* @param loginPath - PATH reported by the login shell ('' when unavailable).
+* @param inheritedPath - the host process's own PATH.
+* @returns the merged PATH (the inherited value when there is no login one).
+*/
+function mergePaths(loginPath, inheritedPath) {
+	const seen = /* @__PURE__ */ new Set();
+	const entries = [];
+	for (const part of `${loginPath}:${inheritedPath ?? ""}`.split(":")) {
+		const entry = part.trim();
+		if (entry === "" || seen.has(entry)) continue;
+		seen.add(entry);
+		entries.push(entry);
+	}
+	return entries.join(":");
+}
+/** The shell program whose login PATH describes this user's environment. */
+function loginShell(env = process.env) {
+	const shell = env.SHELL?.trim();
+	return shell !== void 0 && shell !== "" ? shell : void 0;
+}
+/**
+* Ask `shell` (interactive login) for its PATH.
+*
+* Both flags matter: `-l` sources the profile files that own the system PATH
+* (on macOS `/etc/zprofile` → `path_helper`), `-i` additionally sources the
+* interactive config where nvm/fnm/volta and other version managers install
+* their shims (this user's node lives in `~/.zshrc`). A hung or noisy
+* interactive profile cannot block a run: the probe carries a deadline, and
+* only the marked span of stdout is read.
+* @param options.shell - shell program; defaults to `$SHELL`.
+* @param options.timeoutMs - probe deadline.
+* @param options.run - probe runner, injectable for tests.
+* @param options.env - environment the probe itself runs with.
+* @returns the login PATH, or '' when it cannot be determined.
+*/
+async function resolveLoginShellPath(options = {}) {
+	if (process.platform === "win32") return "";
+	const env = options.env ?? process.env;
+	const shell = options.shell ?? loginShell(env);
+	if (shell === void 0) return "";
+	const run = options.run ?? defaultRunner;
+	const command = `printf '%s' "${PATH_START}\${PATH}${PATH_END}"`;
+	try {
+		const { stdout } = await run(shell, [
+			"-i",
+			"-l",
+			"-c",
+			command
+		], {
+			timeout: options.timeoutMs ?? 3e3,
+			windowsHide: true,
+			env
+		});
+		const path = extractShellPath(stdout).trim();
+		return /[\s]/.test(path) ? "" : path;
+	} catch {
+		return "";
+	}
+}
+let cached;
+/** Cached, process-wide login-shell PATH (one probe per host lifetime). */
+function loginShellPath() {
+	cached ??= resolveLoginShellPath();
+	return cached;
+}
+/**
+* Environment for one local quick command.
+*
+* A copy of the host environment with the login-shell PATH merged in front, so
+* Desktop-launched hosts see the same toolchain a terminal-launched host does.
+* @param overrides - plugin-owned variables (DSH_WORKSPACE*) merged last.
+* @returns the spawn environment.
+*/
+async function localCommandEnv(overrides = {}) {
+	const env = { ...process.env };
+	const loginPath = await loginShellPath();
+	if (loginPath !== "") env.PATH = mergePaths(loginPath, process.env.PATH);
+	return {
+		...env,
+		...overrides
+	};
+}
+//#endregion
 //#region src/server/remote.ts
 /**
 * Remote (SSH) execution support: detect that a workspace path is a dsh-ssh
@@ -312,12 +446,11 @@ var QuickCommandRunner = class {
 				stdout: { maxBytes: TAIL_MAX_BYTES },
 				stderr: { maxBytes: TAIL_MAX_BYTES }
 			},
-			env: {
-				...process.env,
+			env: await localCommandEnv({
 				DSH_WORKSPACE: input.workspacePath,
 				DSH_WORKSPACE_ID: input.workspaceId,
 				DSH_WORKSPACE_TITLE: input.workspaceTitle
-			}
+			})
 		});
 		const live = {
 			runId,
@@ -555,6 +688,28 @@ const WorkspaceCommandsSchema = z.object({
 	workspaceId: z.string().min(1),
 	commands: z.array(CommandSchema).max(200)
 });
+/**
+* Entry config schema, and the schema dsh derives the plugin's settings page
+* from. The `z<...>` annotation names the RESOLVED (live-handle) shape on
+* purpose:
+*
+*  - schemastery >= 3.18.3 carries a third `Mode` type parameter, so a
+*    `.volatile()` field's OUTPUT type is `Volatile<T>` (a live `{ get() }`
+*    cell), never `T` — the old `z<QuickCommandsSettings>` annotation stopped
+*    compiling;
+*  - dropping the annotation and letting the type be inferred does not build
+*    either: declaration emit then cannot portably name the inferred type
+*    (TS2742), because `z.array(...)` leaks `@deepseek-ai/cosmokit`'s `Dict`
+*    into the schema type while the program holds two schemastery copies
+*    (this plugin's 3.18.3, and the one `@deepseek-ai/dsh-host-webserver`
+*    resolves — see pnpm-workspace.yaml's minimumReleaseAgeExclude, which pins
+*    the former), and cosmokit itself is not nameable from this package.
+*
+* The annotation is type-only. At runtime all three fields are still declared
+* `volatile()` — that is what makes them writable by the settings plane (its
+* `write()` refuses an entry whose form has no volatile field) and what keeps
+* the auto-generated page working.
+*/
 const QuickCommandsSettingsSchema = z.object({
 	workspaces: z.array(WorkspaceCommandsSchema).max(500).volatile(),
 	popupAnchor: z.union([z.const("corner"), z.const("button")]).default("corner").volatile(),
@@ -564,25 +719,30 @@ const QuickCommandsSettingsSchema = z.object({
 	}).volatile()
 });
 /**
-* Read one config field. A volatile field arrives as a handle (dsh >= 0.1.7)
-* and is read through `.get()` on EVERY access, so edits made through the
-* settings plane are visible immediately; hosts that hand the plain value keep
-* working unchanged.
+* Read a config node that may be a plain value or a live (`.volatile()`) node.
+*
+* A plugin whose Config declares volatile fields receives a reactive config
+* whose fields expose `get()`, while hand-written config objects and tests pass
+* plain values. Both shapes are supported here so the same code path serves the
+* settings page, `cordis.patch.yml`, and the unit tests.
 */
-function readField(field, fallback) {
-	if (field === void 0 || field === null) return fallback;
-	const handle = field;
-	const value = typeof handle.get === "function" ? handle.get() : field;
-	return value === void 0 || value === null ? fallback : value;
+function liveValue(node, fallback) {
+	if (node === void 0 || node === null) return fallback;
+	const getter = node.get;
+	if (typeof getter === "function") {
+		const value = getter.call(node);
+		return value === void 0 ? fallback : value;
+	}
+	return node;
 }
 function registerSettings(ctx, config) {
 	const readWorkspaces = () => {
-		const value = readField(config?.workspaces, []);
+		const value = liveValue(config?.workspaces, []);
 		return Array.isArray(value) ? value : [];
 	};
-	const readAnchor = () => readField(config?.popupAnchor, "corner") === "button" ? "button" : "corner";
+	const readAnchor = () => liveValue(config?.popupAnchor, "corner") === "button" ? "button" : "corner";
 	const readPopupSize = () => {
-		const value = readField(config?.popupSize, void 0);
+		const value = liveValue(config?.popupSize, void 0);
 		if (typeof value !== "object" || value === null) return void 0;
 		const { width, height } = value;
 		if (typeof width !== "number" || typeof height !== "number") return void 0;
@@ -861,10 +1021,8 @@ function registerApiRoutes(ctx, runner, settings) {
 			};
 		}
 	}
-	const webServer = ctx.get("webServer");
-	if (webServer === void 0) return () => void 0;
 	return ctx.effect(() => {
-		return webServer.register({
+		return ctx.webServer.register({
 			kind: "prefix",
 			path: API_PREFIX,
 			handler: async (req, res) => {
@@ -899,30 +1057,28 @@ const Config = QuickCommandsSettingsSchema;
 /** Configuration rides the entry config; edits persist through the settings service. */
 function apply(ctx, config) {
 	const settings = registerSettings(ctx, config);
-	const subprocess = ctx.get("subprocess");
-	if (subprocess === void 0) {
-		ctx.logger?.warn?.("@fonlan/dsh-quick-commands: subprocess service unavailable; commands cannot run");
-		return;
-	}
-	const resolveRemote = () => {
-		const sshPool = ctx.get("sshPool");
-		if (sshPool === void 0 || typeof sshPool.acquire !== "function" || typeof sshPool.release !== "function") return;
-		return {
-			pool: sshPool,
-			resolveHost: (hostId) => readHostConfig((ns) => {
-				try {
-					return ctx.get("settings")?.get(ns);
-				} catch {
-					return;
-				}
-			}, hostId)
+	ctx.inject(["subprocess", "webServer"], (sctx) => {
+		const subprocess = sctx.get("subprocess");
+		const resolveRemote = () => {
+			const sshPool = sctx.get("sshPool");
+			if (sshPool === void 0 || typeof sshPool.acquire !== "function" || typeof sshPool.release !== "function") return;
+			return {
+				pool: sshPool,
+				resolveHost: (hostId) => readHostConfig((ns) => {
+					try {
+						return sctx.get("settings")?.get(ns);
+					} catch {
+						return;
+					}
+				}, hostId)
+			};
 		};
-	};
-	const runner = new QuickCommandRunner(subprocess, () => resolveRemote());
-	ctx.effect(() => registerApiRoutes(ctx, runner, settings), "quick-commands: api routes");
-	ctx.effect(() => () => {
-		for (const id of runner.listAll()) runner.kill(id);
-	}, "quick-commands: process cleanup");
+		const runner = new QuickCommandRunner(subprocess, () => resolveRemote());
+		sctx.effect(() => registerApiRoutes(sctx, runner, settings), "quick-commands: api routes");
+		sctx.effect(() => () => {
+			for (const id of runner.listAll()) runner.kill(id);
+		}, "quick-commands: process cleanup");
+	});
 }
 //#endregion
 export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -13,9 +13,9 @@
  * absence of dsh-ssh degrades cleanly to local-only behaviour.
  */
 import type { Context } from '@deepseek-ai/cordis';
-import type { QuickCommandsSettings } from './shared/contract.js';
+import { type QuickCommandsConfig } from './server/settings.js';
 export declare const name = "@fonlan/dsh-quick-commands";
 export declare const inject: string[];
-export declare const Config: import("@deepseek-ai/schemastery").default<QuickCommandsSettings>;
+export declare const Config: import("@deepseek-ai/schemastery").default<import("./shared/contract.js").QuickCommandsSettings, import("./server/settings.js").QuickCommandsLiveSettings>;
 /** Configuration rides the entry config; edits persist through the settings service. */
-export declare function apply(ctx: Context, config: QuickCommandsSettings): void;
+export declare function apply(ctx: Context, config: QuickCommandsConfig): void;

package/lib/types/server/settings.d.ts

@@ -10,7 +10,7 @@
  * field therefore yields the handle object, which silently destroys the whole
  * document: `Array.isArray(handle)` is false, JSON renders `{}`, and a
  * `.default('corner')` union arrives as the handle rather than a literal.
- * Every read goes through {@link readField} instead, which unwraps handles and
+ * Every read goes through {@link liveValue} instead, which unwraps handles and
  * still accepts plain values (hosts that resolve the config without the
  * volatile wrapper).
  */
@@ -18,7 +18,49 @@ import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { QuickCommandsSettings, QuickCommandEntry, QuickPopupSize } from '../shared/contract.js';
 export declare const QUICK_COMMANDS_NS = "quick-commands";
-export declare const QuickCommandsSettingsSchema: z<QuickCommandsSettings>;
+/** Live handle schemastery wraps around one `volatile()` config field. */
+interface VolatileField {
+    get(): unknown;
+}
+/**
+ * The entry config in its RESOLVED form: schemastery hands every `.volatile()`
+ * field to the loader (and so to `apply()`) as a live handle instead of the
+ * plain value. This is the schema's real output type.
+ */
+export interface QuickCommandsLiveSettings {
+    workspaces: VolatileField;
+    popupAnchor: VolatileField;
+    popupSize: VolatileField;
+}
+/**
+ * The entry config as `apply()` receives it: the resolved (live) document, or
+ * the plain document in hand-built contexts and hosts that resolve the config
+ * without the volatile wrapper. Both load through the same `apply`.
+ */
+export type QuickCommandsConfig = QuickCommandsSettings | QuickCommandsLiveSettings;
+/**
+ * Entry config schema, and the schema dsh derives the plugin's settings page
+ * from. The `z<...>` annotation names the RESOLVED (live-handle) shape on
+ * purpose:
+ *
+ *  - schemastery >= 3.18.3 carries a third `Mode` type parameter, so a
+ *    `.volatile()` field's OUTPUT type is `Volatile<T>` (a live `{ get() }`
+ *    cell), never `T` — the old `z<QuickCommandsSettings>` annotation stopped
+ *    compiling;
+ *  - dropping the annotation and letting the type be inferred does not build
+ *    either: declaration emit then cannot portably name the inferred type
+ *    (TS2742), because `z.array(...)` leaks `@deepseek-ai/cosmokit`'s `Dict`
+ *    into the schema type while the program holds two schemastery copies
+ *    (this plugin's 3.18.3, and the one `@deepseek-ai/dsh-host-webserver`
+ *    resolves — see pnpm-workspace.yaml's minimumReleaseAgeExclude, which pins
+ *    the former), and cosmokit itself is not nameable from this package.
+ *
+ * The annotation is type-only. At runtime all three fields are still declared
+ * `volatile()` — that is what makes them writable by the settings plane (its
+ * `write()` refuses an entry whose form has no volatile field) and what keeps
+ * the auto-generated page working.
+ */
+export declare const QuickCommandsSettingsSchema: z<QuickCommandsSettings, QuickCommandsLiveSettings>;
 /** Settings service face for the quick-commands engine. */
 export interface QuickCommandsSettingsFace {
     get(): QuickCommandsSettings;
@@ -31,4 +73,5 @@ export interface QuickCommandsSettingsFace {
     /** Persist the output popup size (drag-resize). */
     setPopupSize(size: QuickPopupSize): Promise<void>;
 }
-export declare function registerSettings(ctx: Context, config: QuickCommandsSettings): QuickCommandsSettingsFace;
+export declare function registerSettings(ctx: Context, config: QuickCommandsConfig): QuickCommandsSettingsFace;
+export {};

package/lib/types/server/shell-path.d.ts

@@ -0,0 +1,69 @@
+/** Delimiters wrapping the shell's own PATH in the probe's stdout. */
+export declare const PATH_START = "__DSH_QC_PATH_START__";
+export declare const PATH_END = "__DSH_QC_PATH_END__";
+/** Default deadline for the login-shell probe (ms). */
+export declare const PROBE_TIMEOUT_MS = 3000;
+/** Minimal probe runner shape: `child_process.execFile`, or a test double. */
+export type ProbeRunner = (file: string, args: string[], options: {
+    timeout: number;
+    windowsHide: boolean;
+    env: NodeJS.ProcessEnv;
+}) => Promise<{
+    stdout?: string | Buffer;
+}>;
+/**
+ * Extract the PATH a shell printed between the markers.
+ *
+ * Login profiles are free to print their own noise (nvm notices, version
+ * managers, MOTDs), so only the marked span counts — never the whole stdout.
+ * @param stdout - raw probe stdout.
+ * @returns the marked PATH, or '' when the markers are missing.
+ */
+export declare function extractShellPath(stdout: unknown): string;
+/**
+ * Put the login-shell PATH in front of the inherited one.
+ *
+ * The login PATH wins (that is where the user's toolchain lives); entries from
+ * the inherited PATH stay behind it as a fallback. Empty entries are dropped
+ * and duplicates keep their first position.
+ * @param loginPath - PATH reported by the login shell ('' when unavailable).
+ * @param inheritedPath - the host process's own PATH.
+ * @returns the merged PATH (the inherited value when there is no login one).
+ */
+export declare function mergePaths(loginPath: string, inheritedPath: string | undefined): string;
+/** The shell program whose login PATH describes this user's environment. */
+export declare function loginShell(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Ask `shell` (interactive login) for its PATH.
+ *
+ * Both flags matter: `-l` sources the profile files that own the system PATH
+ * (on macOS `/etc/zprofile` → `path_helper`), `-i` additionally sources the
+ * interactive config where nvm/fnm/volta and other version managers install
+ * their shims (this user's node lives in `~/.zshrc`). A hung or noisy
+ * interactive profile cannot block a run: the probe carries a deadline, and
+ * only the marked span of stdout is read.
+ * @param options.shell - shell program; defaults to `$SHELL`.
+ * @param options.timeoutMs - probe deadline.
+ * @param options.run - probe runner, injectable for tests.
+ * @param options.env - environment the probe itself runs with.
+ * @returns the login PATH, or '' when it cannot be determined.
+ */
+export declare function resolveLoginShellPath(options?: {
+    shell?: string | undefined;
+    timeoutMs?: number;
+    run?: ProbeRunner;
+    env?: NodeJS.ProcessEnv;
+}): Promise<string>;
+/** Cached, process-wide login-shell PATH (one probe per host lifetime). */
+export declare function loginShellPath(): Promise<string>;
+/** Drop the cache (tests, and settings reloads that may have changed `$SHELL`). */
+export declare function resetLoginShellPathCache(): void;
+/**
+ * Environment for one local quick command.
+ *
+ * A copy of the host environment with the login-shell PATH merged in front, so
+ * Desktop-launched hosts see the same toolchain a terminal-launched host does.
+ * @param overrides - plugin-owned variables (DSH_WORKSPACE*) merged last.
+ * @returns the spawn environment.
+ */
+export declare function localCommandEnv(overrides?: Record<string, string>): Promise<NodeJS.ProcessEnv>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonlan/dsh-quick-commands",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "DSH web plugin: per-workspace quick commands. Configure named shell commands per DSH workspace, run one from the session header with live stdout/stderr in a floating popup.",
   "license": "MIT",
   "repository": {
@@ -63,27 +63,27 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.2 || ^0.2.0-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-settings": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-subprocess": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-workspace": "0.2.0-rc.1",
     "@deepseek-ai/schemastery": "^3.18.3",
     "@types/node": "^22.0.0",
     "@types/react": "~18.3.1",
@@ -95,7 +95,7 @@
     "build": "rm -rf lib && tsc -p tsconfig.build.json && tsdown",
     "build:client": "tsdown",
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
-    "test": "node --experimental-transform-types --test test/remote.test.ts test/settings-config.test.ts && node test/header-icons.test.mjs",
+    "test": "node --experimental-transform-types --test test/remote.test.ts test/settings-config.test.ts test/host-apply.test.ts test/shell-path.test.ts && node test/header-icons.test.mjs",
     "bundle": "tsdown",
     "watch": "tsdown --watch",
     "release:patch": "npm version patch && git push && git push --tags",

package/src/index.ts

@@ -15,9 +15,8 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { QuickCommandRunner, type RemoteBackend } from './server/runner.js'
 import { readHostConfig } from './server/remote.js'
-import { QuickCommandsSettingsSchema, registerSettings } from './server/settings.js'
+import { QuickCommandsSettingsSchema, registerSettings, type QuickCommandsConfig } from './server/settings.js'
 import { registerApiRoutes } from './server/rpc.js'
-import type { QuickCommandsSettings } from './shared/contract.js'
 
 export const name = '@fonlan/dsh-quick-commands'
 
@@ -30,39 +29,47 @@ export const inject = ['settings']
 export const Config = QuickCommandsSettingsSchema
 
 /** Configuration rides the entry config; edits persist through the settings service. */
-export function apply(ctx: Context, config: QuickCommandsSettings): void {
+export function apply(ctx: Context, config: QuickCommandsConfig): void {
   const settings = registerSettings(ctx, config)
-  const subprocess = ctx.get('subprocess')
-  if (subprocess === undefined) {
-    ctx.logger?.warn?.('@fonlan/dsh-quick-commands: subprocess service unavailable; commands cannot run')
-    return
-  }
-  // Remote backend (duck-typed over @dsh-ssh/dsh-ssh): resolved lazily so the
-  // sshPool service is picked up whenever the SSH plugin loads.
-  const resolveRemote = (): RemoteBackend | undefined => {
-    const sshPool = ctx.get('sshPool') as
-      | { acquire(cfg: { id: string; [key: string]: unknown }): Promise<unknown>; release(): void }
-      | undefined
-    if (sshPool === undefined || typeof sshPool.acquire !== 'function' || typeof sshPool.release !== 'function') {
-      return undefined
+  // dsh >= 0.1.7 activates entries asynchronously: a fiber is only readable as a
+  // service once its own init settled, and the webserver's init waits for its
+  // listen. Resolving services with a one-shot `ctx.get()` during apply could
+  // therefore observe undefined with nothing to retry — the header menu's
+  // "HTTP 405": `subprocess` (and/or the route helper's own `webServer` guard)
+  // came back missing, the API prefix route was never registered, and every
+  // client POST fell through to the /plugins client-modules bundle route, which
+  // answers any non-GET with 405.
+  // ctx.inject is the retrying form: the body runs once both services are live,
+  // so the pairing also covers whichever one arrives after this entry.
+  ctx.inject(['subprocess', 'webServer'], (sctx) => {
+    const subprocess = sctx.get('subprocess')
+    // Remote backend (duck-typed over @dsh-ssh/dsh-ssh): resolved lazily so the
+    // sshPool service is picked up whenever the SSH plugin loads.
+    const resolveRemote = (): RemoteBackend | undefined => {
+      const sshPool = sctx.get('sshPool') as
+        | { acquire(cfg: { id: string; [key: string]: unknown }): Promise<unknown>; release(): void }
+        | undefined
+      if (sshPool === undefined || typeof sshPool.acquire !== 'function' || typeof sshPool.release !== 'function') {
+        return undefined
+      }
+      return {
+        pool: sshPool as never,
+        resolveHost: (hostId) => readHostConfig((ns) => {
+          try {
+            return (sctx.get('settings') as { get(ns: string): unknown } | undefined)?.get(ns)
+          } catch {
+            return undefined
+          }
+        }, hostId),
+      }
     }
-    return {
-      pool: sshPool as never,
-      resolveHost: (hostId) => readHostConfig((ns) => {
-        try {
-          return (ctx.get('settings') as { get(ns: string): unknown } | undefined)?.get(ns)
-        } catch {
-          return undefined
-        }
-      }, hostId),
-    }
-  }
-  const runner = new QuickCommandRunner(subprocess as never, () => resolveRemote())
-  ctx.effect(() => registerApiRoutes(ctx, runner, settings), 'quick-commands: api routes')
-  ctx.effect(() => () => {
-    // Terminate every live process when the plugin fiber stops.
-    for (const id of runner.listAll()) {
-      runner.kill(id)
-    }
-  }, 'quick-commands: process cleanup')
+    const runner = new QuickCommandRunner(subprocess as never, () => resolveRemote())
+    sctx.effect(() => registerApiRoutes(sctx, runner, settings), 'quick-commands: api routes')
+    sctx.effect(() => () => {
+      // Terminate every live process when the plugin fiber stops.
+      for (const id of runner.listAll()) {
+        runner.kill(id)
+      }
+    }, 'quick-commands: process cleanup')
+  })
 }

package/src/server/rpc.ts

@@ -255,10 +255,15 @@ export function registerApiRoutes(ctx: Context, runner: QuickRunner, settings: Q
     }
   }
 
-  const webServer = ctx.get('webServer')
-  if (webServer === undefined) return () => undefined
+  // The caller reaches this function through ctx.inject(['webServer']), so the
+  // service is active by construction. A one-shot `ctx.get('webServer')` guard
+  // here used to return an empty disposer whenever the webserver fiber had not
+  // finished activating yet (dsh >= 0.1.7 activates entries asynchronously and
+  // makes a service readable only once its own init settled — for the webserver
+  // that means listening): no route was ever registered and every client POST
+  // fell through to the /plugins bundle route, which answers non-GET with 405.
   return ctx.effect(() => {
-    return webServer.register({
+    return ctx.webServer.register({
       kind: 'prefix',
       path: API_PREFIX,
       handler: async (req: IncomingMessage, res: ServerResponse): Promise<void> => {

package/src/server/runner.ts

@@ -17,6 +17,7 @@
 import { randomUUID } from 'node:crypto'
 import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess'
 import type { QuickCommandsSettings } from '../shared/contract.js'
+import { localCommandEnv } from './shell-path.js'
 import {
   localPathToRemoteRef,
   resolveRemoteCwd,
@@ -203,12 +204,15 @@ export class QuickCommandRunner implements QuickRunner {
         stdout: { maxBytes: TAIL_MAX_BYTES },
         stderr: { maxBytes: TAIL_MAX_BYTES },
       },
-      env: {
-        ...process.env,
+      // The login-shell PATH rides in front of the host's own: DSH Desktop runs
+      // the host with launchd's minimal PATH, so `npm run typecheck` and
+      // `docker compose up -d` only resolve once the user's toolchain is
+      // visible. See ./shell-path.ts.
+      env: await localCommandEnv({
         DSH_WORKSPACE: input.workspacePath,
         DSH_WORKSPACE_ID: input.workspaceId,
         DSH_WORKSPACE_TITLE: input.workspaceTitle,
-      },
+      }),
     })
 
     const live: LiveRun = {

package/src/server/settings.ts

@@ -10,7 +10,7 @@
  * field therefore yields the handle object, which silently destroys the whole
  * document: `Array.isArray(handle)` is false, JSON renders `{}`, and a
  * `.default('corner')` union arrives as the handle rather than a literal.
- * Every read goes through {@link readField} instead, which unwraps handles and
+ * Every read goes through {@link liveValue} instead, which unwraps handles and
  * still accepts plain values (hosts that resolve the config without the
  * volatile wrapper).
  */
@@ -36,7 +36,52 @@ const WorkspaceCommandsSchema = z.object({
   commands: z.array(CommandSchema).max(200),
 })
 
-export const QuickCommandsSettingsSchema: z<QuickCommandsSettings> = z.object({
+/** Live handle schemastery wraps around one `volatile()` config field. */
+interface VolatileField {
+  get(): unknown
+}
+
+/**
+ * The entry config in its RESOLVED form: schemastery hands every `.volatile()`
+ * field to the loader (and so to `apply()`) as a live handle instead of the
+ * plain value. This is the schema's real output type.
+ */
+export interface QuickCommandsLiveSettings {
+  workspaces: VolatileField
+  popupAnchor: VolatileField
+  popupSize: VolatileField
+}
+
+/**
+ * The entry config as `apply()` receives it: the resolved (live) document, or
+ * the plain document in hand-built contexts and hosts that resolve the config
+ * without the volatile wrapper. Both load through the same `apply`.
+ */
+export type QuickCommandsConfig = QuickCommandsSettings | QuickCommandsLiveSettings
+
+/**
+ * Entry config schema, and the schema dsh derives the plugin's settings page
+ * from. The `z<...>` annotation names the RESOLVED (live-handle) shape on
+ * purpose:
+ *
+ *  - schemastery >= 3.18.3 carries a third `Mode` type parameter, so a
+ *    `.volatile()` field's OUTPUT type is `Volatile<T>` (a live `{ get() }`
+ *    cell), never `T` — the old `z<QuickCommandsSettings>` annotation stopped
+ *    compiling;
+ *  - dropping the annotation and letting the type be inferred does not build
+ *    either: declaration emit then cannot portably name the inferred type
+ *    (TS2742), because `z.array(...)` leaks `@deepseek-ai/cosmokit`'s `Dict`
+ *    into the schema type while the program holds two schemastery copies
+ *    (this plugin's 3.18.3, and the one `@deepseek-ai/dsh-host-webserver`
+ *    resolves — see pnpm-workspace.yaml's minimumReleaseAgeExclude, which pins
+ *    the former), and cosmokit itself is not nameable from this package.
+ *
+ * The annotation is type-only. At runtime all three fields are still declared
+ * `volatile()` — that is what makes them writable by the settings plane (its
+ * `write()` refuses an entry whose form has no volatile field) and what keeps
+ * the auto-generated page working.
+ */
+export const QuickCommandsSettingsSchema: z<QuickCommandsSettings, QuickCommandsLiveSettings> = z.object({
   // Values are addressed by index (array edits), so the whole array is the
   // volatile handle the settings plane swaps in place.
   workspaces: z.array(WorkspaceCommandsSchema).max(500).volatile(),
@@ -51,22 +96,22 @@ export const QuickCommandsSettingsSchema: z<QuickCommandsSettings> = z.object({
   }).volatile(),
 })
 
-/** Live handle schemastery wraps around one `volatile()` config field. */
-interface VolatileField<T> {
-  get(): T
-}
-
 /**
- * Read one config field. A volatile field arrives as a handle (dsh >= 0.1.7)
- * and is read through `.get()` on EVERY access, so edits made through the
- * settings plane are visible immediately; hosts that hand the plain value keep
- * working unchanged.
+ * Read a config node that may be a plain value or a live (`.volatile()`) node.
+ *
+ * A plugin whose Config declares volatile fields receives a reactive config
+ * whose fields expose `get()`, while hand-written config objects and tests pass
+ * plain values. Both shapes are supported here so the same code path serves the
+ * settings page, `cordis.patch.yml`, and the unit tests.
  */
-function readField<T>(field: unknown, fallback: T): T {
-  if (field === undefined || field === null) return fallback
-  const handle = field as Partial<VolatileField<T>>
-  const value = typeof handle.get === 'function' ? handle.get() : (field as T)
-  return value === undefined || value === null ? fallback : value
+function liveValue<T>(node: unknown, fallback: T): T {
+  if (node === undefined || node === null) return fallback
+  const getter = (node as { get?: unknown }).get
+  if (typeof getter === 'function') {
+    const value = (getter as () => unknown).call(node)
+    return value === undefined ? fallback : (value as T)
+  }
+  return node as T
 }
 
 /** Structural settings-service subset used for persistence. */
@@ -87,15 +132,15 @@ export interface QuickCommandsSettingsFace {
   setPopupSize(size: QuickPopupSize): Promise<void>
 }
 
-export function registerSettings(ctx: Context, config: QuickCommandsSettings): QuickCommandsSettingsFace {
+export function registerSettings(ctx: Context, config: QuickCommandsConfig): QuickCommandsSettingsFace {
   const readWorkspaces = (): WorkspaceCommands[] => {
-    const value = readField<unknown>(config?.workspaces, [])
+    const value = liveValue<unknown>(config?.workspaces, [])
     return Array.isArray(value) ? value as WorkspaceCommands[] : []
   }
   const readAnchor = (): QuickCommandsSettings['popupAnchor'] =>
-    (readField<unknown>(config?.popupAnchor, 'corner') === 'button' ? 'button' : 'corner')
+    (liveValue<unknown>(config?.popupAnchor, 'corner') === 'button' ? 'button' : 'corner')
   const readPopupSize = (): QuickPopupSize | undefined => {
-    const value = readField<unknown>(config?.popupSize, undefined)
+    const value = liveValue<unknown>(config?.popupSize, undefined)
     if (typeof value !== 'object' || value === null) return undefined
     const { width, height } = value as { width?: unknown; height?: unknown }
     // `{}` (never resized) and any partially written size read as absent.

package/src/server/shell-path.ts

@@ -0,0 +1,160 @@
+/**
+ * Login-shell PATH resolution for the local quick-command backend.
+ *
+ * `dsh web` started from a terminal inherits the user's full PATH, so a
+ * configured command such as `npm run typecheck` or `docker compose up -d`
+ * finds its toolchain. **DSH Desktop does not**: the Electron host is launched
+ * by launchd and runs with the minimal system PATH
+ * (`/usr/bin:/bin:/usr/sbin:/sbin`), which hides homebrew, `/usr/local/bin`,
+ * nvm, corepack and Docker Desktop. Every command that leans on the user's
+ * toolchain then fails with "command not found" in Desktop while the very same
+ * profile keeps working in a browser-launched host.
+ *
+ * This module asks the user's interactive login shell for its PATH once
+ * (cached for the process lifetime) and prepends it to the inherited PATH for
+ * local runs. Resolution is best effort by design: a missing `$SHELL`, a
+ * timeout, a non-zero exit or unparseable output all leave the inherited PATH
+ * untouched, so a terminal-launched host behaves exactly as before.
+ */
+import { execFile } from 'node:child_process'
+
+/** Delimiters wrapping the shell's own PATH in the probe's stdout. */
+export const PATH_START = '__DSH_QC_PATH_START__'
+export const PATH_END = '__DSH_QC_PATH_END__'
+
+/** Default deadline for the login-shell probe (ms). */
+export const PROBE_TIMEOUT_MS = 3000
+
+/** Minimal probe runner shape: `child_process.execFile`, or a test double. */
+export type ProbeRunner = (
+  file: string,
+  args: string[],
+  options: { timeout: number; windowsHide: boolean; env: NodeJS.ProcessEnv },
+) => Promise<{ stdout?: string | Buffer }>
+
+const defaultRunner: ProbeRunner = (file, args, options) =>
+  new Promise((resolve, reject) => {
+    execFile(file, args, options, (error, stdout) => {
+      if (error) reject(error)
+      else resolve({ stdout })
+    })
+  })
+
+/**
+ * Extract the PATH a shell printed between the markers.
+ *
+ * Login profiles are free to print their own noise (nvm notices, version
+ * managers, MOTDs), so only the marked span counts — never the whole stdout.
+ * @param stdout - raw probe stdout.
+ * @returns the marked PATH, or '' when the markers are missing.
+ */
+export function extractShellPath(stdout: unknown): string {
+  if (typeof stdout !== 'string' && !(stdout instanceof Buffer)) return ''
+  const text = String(stdout)
+  const start = text.indexOf(PATH_START)
+  const end = text.lastIndexOf(PATH_END)
+  if (start < 0 || end < 0 || end < start) return ''
+  return text.slice(start + PATH_START.length, end)
+}
+
+/**
+ * Put the login-shell PATH in front of the inherited one.
+ *
+ * The login PATH wins (that is where the user's toolchain lives); entries from
+ * the inherited PATH stay behind it as a fallback. Empty entries are dropped
+ * and duplicates keep their first position.
+ * @param loginPath - PATH reported by the login shell ('' when unavailable).
+ * @param inheritedPath - the host process's own PATH.
+ * @returns the merged PATH (the inherited value when there is no login one).
+ */
+export function mergePaths(loginPath: string, inheritedPath: string | undefined): string {
+  const seen = new Set<string>()
+  const entries: string[] = []
+  for (const part of `${loginPath}:${inheritedPath ?? ''}`.split(':')) {
+    const entry = part.trim()
+    if (entry === '' || seen.has(entry)) continue
+    seen.add(entry)
+    entries.push(entry)
+  }
+  return entries.join(':')
+}
+
+/** The shell program whose login PATH describes this user's environment. */
+export function loginShell(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  const shell = env.SHELL?.trim()
+  return shell !== undefined && shell !== '' ? shell : undefined
+}
+
+/**
+ * Ask `shell` (interactive login) for its PATH.
+ *
+ * Both flags matter: `-l` sources the profile files that own the system PATH
+ * (on macOS `/etc/zprofile` → `path_helper`), `-i` additionally sources the
+ * interactive config where nvm/fnm/volta and other version managers install
+ * their shims (this user's node lives in `~/.zshrc`). A hung or noisy
+ * interactive profile cannot block a run: the probe carries a deadline, and
+ * only the marked span of stdout is read.
+ * @param options.shell - shell program; defaults to `$SHELL`.
+ * @param options.timeoutMs - probe deadline.
+ * @param options.run - probe runner, injectable for tests.
+ * @param options.env - environment the probe itself runs with.
+ * @returns the login PATH, or '' when it cannot be determined.
+ */
+export async function resolveLoginShellPath(options: {
+  shell?: string | undefined
+  timeoutMs?: number
+  run?: ProbeRunner
+  env?: NodeJS.ProcessEnv
+} = {}): Promise<string> {
+  if (process.platform === 'win32') return ''
+  const env = options.env ?? process.env
+  const shell = options.shell ?? loginShell(env)
+  if (shell === undefined) return ''
+  const run = options.run ?? defaultRunner
+  // `${PATH}` must stay braced: an unbraced `$PATH__DSH...` is read as one
+  // identifier by POSIX shells and silently expands to nothing.
+  const command = `printf '%s' "${PATH_START}\${PATH}${PATH_END}"`
+  try {
+    const { stdout } = await run(shell, ['-i', '-l', '-c', command], {
+      timeout: options.timeoutMs ?? PROBE_TIMEOUT_MS,
+      windowsHide: true,
+      env,
+    })
+    const path = extractShellPath(stdout).trim()
+    // A list-valued shell (fish) renders "$PATH" as space-separated entries:
+    // merging that would inject a single bogus entry, so keep the host PATH.
+    return /[\s]/.test(path) ? '' : path
+  } catch {
+    // Any failure (missing shell, timeout, killed profile) keeps the inherited
+    // PATH: a quick command must never be worse than the host's own shell.
+    return ''
+  }
+}
+
+let cached: Promise<string> | undefined
+
+/** Cached, process-wide login-shell PATH (one probe per host lifetime). */
+export function loginShellPath(): Promise<string> {
+  cached ??= resolveLoginShellPath()
+  return cached
+}
+
+/** Drop the cache (tests, and settings reloads that may have changed `$SHELL`). */
+export function resetLoginShellPathCache(): void {
+  cached = undefined
+}
+
+/**
+ * Environment for one local quick command.
+ *
+ * A copy of the host environment with the login-shell PATH merged in front, so
+ * Desktop-launched hosts see the same toolchain a terminal-launched host does.
+ * @param overrides - plugin-owned variables (DSH_WORKSPACE*) merged last.
+ * @returns the spawn environment.
+ */
+export async function localCommandEnv(overrides: Record<string, string> = {}): Promise<NodeJS.ProcessEnv> {
+  const env: NodeJS.ProcessEnv = { ...process.env }
+  const loginPath = await loginShellPath()
+  if (loginPath !== '') env.PATH = mergePaths(loginPath, process.env.PATH)
+  return { ...env, ...overrides }
+}