@fonlan/dsh-quick-commands 0.1.6 → 0.1.8

package/src/client/icons.tsx

@@ -0,0 +1,106 @@
+/**
+ * Icon compatibility layer over `@deepseek-ai/dsh-client-ui-primitives`.
+ *
+ * DSH renamed this package's icon exports in 0.1.7: the size-suffixed names
+ * (`IconPlayOutline16`) became weight-suffixed ones (`IconPlayOutlineRegular` /
+ * `IconPlayOutlineMedium`, matching what the official header plugins use).
+ *
+ * A client bundle that statically imports a name the host no longer exports
+ * receives `undefined`; rendering that element throws, the slot's per-entry
+ * error boundary swallows the whole entry, and the surface silently vanishes —
+ * exactly how the header ▶ button disappeared on 0.1.7.
+ *
+ * Resolving by name at runtime (new scheme → legacy scheme → bundled artwork)
+ * keeps every surface rendering across DSH alphas. The bundled artwork is only
+ * a last resort, so a future rename can never blank a control again.
+ */
+import type { ReactElement, ReactNode } from 'react'
+import * as primitives from '@deepseek-ai/dsh-client-ui-primitives'
+
+/** Props both naming schemes accept (the legacy exports ignore extra fields). */
+export interface IconProps {
+  /** Rendered square size in CSS pixels. */
+  size?: number
+  className?: string
+}
+
+type IconComponent = (props: IconProps) => ReactElement
+
+const ICON_EXPORTS = primitives as unknown as Record<string, IconComponent | undefined>
+
+/** First export name that exists on the running host, else the bundled artwork. */
+function pickIcon(exportNames: readonly string[], fallback: IconComponent): IconComponent {
+  for (const name of exportNames) {
+    const candidate = ICON_EXPORTS[name]
+    if (typeof candidate === 'function') return candidate
+  }
+  return fallback
+}
+
+/** Wrap one locally drawn 16×16 artwork as an icon component. */
+function localIcon(children: ReactNode): IconComponent {
+  return function LocalIcon({ size = 16, className }: IconProps): ReactElement {
+    return (
+      <svg
+        width={size}
+        height={size}
+        viewBox="0 0 16 16"
+        fill="none"
+        className={className}
+        aria-hidden="true"
+      >
+        {children}
+      </svg>
+    )
+  }
+}
+
+/** Run/play glyph for the header quick-run button. */
+export const PlayIcon = pickIcon(
+  ['IconPlayOutlineRegular', 'IconPlayOutlineMedium', 'IconPlayOutline16'],
+  localIcon(
+    <>
+      <circle cx="8" cy="8" r="6.5" stroke="currentColor" />
+      <path d="M6.6 5.9 10.4 8l-3.8 2.1Z" fill="currentColor" />
+    </>,
+  ),
+)
+
+/** Dismiss glyph (menu header and popup close). */
+export const CloseIcon = pickIcon(
+  ['IconCloseOutlineRegular', 'IconCloseOutlineMedium', 'IconCloseOutline16'],
+  localIcon(
+    <path d="M4.2 4.2 11.8 11.8M11.8 4.2 4.2 11.8" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" />,
+  ),
+)
+
+/** Stop/kill glyph for a running command. */
+export const StopIcon = pickIcon(
+  ['IconStopFillRegular', 'IconStopFillMedium', 'IconStopFill16'],
+  localIcon(<rect x="4.6" y="4.6" width="6.8" height="6.8" rx="1.6" fill="currentColor" />),
+)
+
+/** Add-row glyph in the settings page. */
+export const PlusIcon = pickIcon(
+  ['IconPlusOutlineRegular', 'IconPlusOutlineMedium', 'IconPlusOutline16'],
+  localIcon(
+    <path d="M8 3.4v9.2M3.4 8h9.2" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" />,
+  ),
+)
+
+/** Remove-command glyph in the settings page. */
+export const TrashIcon = pickIcon(
+  ['IconTrashOutlineRegular', 'IconTrashOutlineMedium', 'IconTrashOutline16'],
+  localIcon(
+    <>
+      <path d="M3.4 4.4h9.2" stroke="currentColor" strokeWidth="1.2" strokeLinecap="round" />
+      <path
+        d="M6.4 4.4V3.1h3.2v1.3M4.9 4.4l.6 8.5h5l.6-8.5"
+        stroke="currentColor"
+        strokeWidth="1.2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </>,
+  ),
+)

package/src/client/settings-section.tsx

@@ -9,12 +9,9 @@
  * persist while the user types.
  */
 import { useEffect, useRef, useState } from 'react'
-import {
-  IconPlusOutline16,
-  IconTrashOutline16,
-} from '@deepseek-ai/dsh-client-ui-primitives'
+import { PlusIcon, TrashIcon } from './icons'
 import { quickApi } from './api'
-import type { QuickRosterEntry, QuickCommandsSettings } from '../shared/contract'
+import { anchorOf, type QuickRosterEntry, type QuickCommandsSettings } from '../shared/contract'
 import './settings-section.css'
 
 interface Props {
@@ -38,7 +35,7 @@ export function QuickCommandsSettingsSection({ t }: Props): JSX.Element {
   const load = async (): Promise<void> => {
     try {
       const [entries, settings] = await Promise.all([quickApi.workspacesList(), quickApi.settingsGet()])
-      setState({ loaded: true, entries, anchor: settings.popupAnchor })
+      setState({ loaded: true, entries, anchor: anchorOf(settings.popupAnchor) })
       setError(null)
     } catch (e) {
       setState((s) => ({ ...s, loaded: true }))
@@ -100,7 +97,7 @@ export function QuickCommandsSettingsSection({ t }: Props): JSX.Element {
     setState((s) => ({ ...s, anchor }))
     try {
       const next = await quickApi.settingsSetAnchor(anchor)
-      setState((s) => ({ ...s, anchor: next.popupAnchor }))
+      setState((s) => ({ ...s, anchor: anchorOf(next.popupAnchor) }))
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e))
       void load()
@@ -179,12 +176,12 @@ export function QuickCommandsSettingsSection({ t }: Props): JSX.Element {
                   title={t('cardRemove')}
                   onClick={() => removeCommand(entry.workspaceId, index)}
                 >
-                  <IconTrashOutline16 size={14} />
+                  <TrashIcon size={14} />
                 </button>
               </div>
             ))}
             <button type="button" className="qc-settings-add-btn" onClick={() => addCommand(entry.workspaceId)}>
-              <IconPlusOutline16 size={14} />
+              <PlusIcon size={14} />
               {t('cardAddCommand')}
             </button>
           </section>

package/src/index.ts

@@ -15,47 +15,62 @@
 import type { Context } from '@deepseek-ai/cordis'
 import { QuickCommandRunner, type RemoteBackend } from './server/runner.js'
 import { readHostConfig } from './server/remote.js'
-import { registerSettings } from './server/settings.js'
+import { QuickCommandsSettingsSchema, registerSettings } from './server/settings.js'
 import { registerApiRoutes } from './server/rpc.js'
+import type { QuickCommandsSettings } from './shared/contract.js'
 
 export const name = '@fonlan/dsh-quick-commands'
 
 export const inject = ['settings']
 
-/** No plugin-level config; all configuration lives in the settings namespace. */
-export function apply(ctx: Context): void {
-  const settings = registerSettings(ctx)
-  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
-    }
-    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)
+// The entry config IS this plugin's settings document (workspace command sets
+// + popup preferences). Its fields are declared volatile, so the settings
+// plane edits them without remounting the entry and `apply` receives live
+// handles rather than snapshots — see server/settings.ts for the reads.
+export const Config = QuickCommandsSettingsSchema
+
+/** Configuration rides the entry config; edits persist through the settings service. */
+export function apply(ctx: Context, config: QuickCommandsSettings): void {
+  const settings = registerSettings(ctx, config)
+  // 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),
+      }
     }
-  }, '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

@@ -1,13 +1,22 @@
 /**
  * User-facing plugin settings (per-workspace command sets + popup anchor),
- * persisted through the settings service namespace `quick-commands`.
- * The DSH settings service requires a lowercase kebab-case namespace
- * (/^[a-z][a-z0-9-]*$/), so the scoped package name cannot be used here.
+ * carried by this bundle's entry config: dsh >= 0.1.7 owns plugin settings as
+ * entry config (the plugin's `Config` schema) and persists edits through
+ * `settings.update`.
+ *
+ * All three fields are declared `volatile()` — that is what makes them
+ * writable by the settings plane — and schemastery hands a volatile field to
+ * `apply()` as a LIVE HANDLE (`{ get() }`), not as the value. Reading the raw
+ * 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
+ * still accepts plain values (hosts that resolve the config without the
+ * volatile wrapper).
  */
 import type { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import type { QuickCommandsSettings, QuickCommandEntry, QuickPopupSize, WorkspaceCommands } from '../shared/contract.js'
-import type {} from '@deepseek-ai/dsh-settings'
 
 export const QUICK_COMMANDS_NS = 'quick-commands'
 
@@ -28,27 +37,41 @@ const WorkspaceCommandsSchema = z.object({
 })
 
 export const QuickCommandsSettingsSchema: z<QuickCommandsSettings> = z.object({
-  workspaces: z.array(WorkspaceCommandsSchema).max(500),
-  popupAnchor: z.union([z.const('corner'), z.const('button')]).default('corner'),
+  // 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(),
+  popupAnchor: z.union([z.const('corner'), z.const('button')]).default('corner').volatile(),
   // No default on purpose: a missing popupSize stays ABSENT in the resolved
   // document, so the client can distinguish "never resized" (per-anchor
-  // default size) from a user-chosen size.
+  // default size) from a user-chosen size. Semantics match the runtime value:
+  // never resized resolves to `{}` (schemastery's implicit object default).
   popupSize: z.object({
     width: z.number().min(320).max(8192),
     height: z.number().min(200).max(8192),
-  }),
+  }).volatile(),
 })
 
-const DEFAULT_SETTINGS: QuickCommandsSettings = {
-  workspaces: [],
-  popupAnchor: 'corner',
+/** Live handle schemastery wraps around one `volatile()` config field. */
+interface VolatileField<T> {
+  get(): T
 }
 
-/** Structural settings-service subset; the real service resolves the schema. */
-interface SettingsServiceLike {
-  register(ns: unknown, schema: unknown): unknown
-  update(ns: unknown, patch: Record<string, unknown>, expectedRevision?: number): Promise<unknown>
-  mutate?(ns: unknown, ops: readonly unknown[], expectedRevision?: number): Promise<unknown>
+/**
+ * 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.
+ */
+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
+}
+
+/** Structural settings-service subset used for persistence. */
+interface SettingsUpdateFace {
+  update(ns: string, patch: Record<string, unknown>, expectedRevision?: number): Promise<unknown>
 }
 
 /** Settings service face for the quick-commands engine. */
@@ -64,35 +87,57 @@ export interface QuickCommandsSettingsFace {
   setPopupSize(size: QuickPopupSize): Promise<void>
 }
 
-export function registerSettings(ctx: Context): QuickCommandsSettingsFace {
-  let current: QuickCommandsSettings = { ...DEFAULT_SETTINGS, workspaces: [] }
-  let service: SettingsServiceLike | undefined
+export function registerSettings(ctx: Context, config: QuickCommandsSettings): QuickCommandsSettingsFace {
+  const readWorkspaces = (): WorkspaceCommands[] => {
+    const value = readField<unknown>(config?.workspaces, [])
+    return Array.isArray(value) ? value as WorkspaceCommands[] : []
+  }
+  const readAnchor = (): QuickCommandsSettings['popupAnchor'] =>
+    (readField<unknown>(config?.popupAnchor, 'corner') === 'button' ? 'button' : 'corner')
+  const readPopupSize = (): QuickPopupSize | undefined => {
+    const value = readField<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.
+    if (typeof width !== 'number' || typeof height !== 'number') return undefined
+    if (!Number.isFinite(width) || !Number.isFinite(height)) return undefined
+    return { width: Math.round(width), height: Math.round(height) }
+  }
+  /** Current document, rebuilt from the live config fields on every read. */
+  const readDocument = (): QuickCommandsSettings => {
+    const size = readPopupSize()
+    return {
+      workspaces: readWorkspaces(),
+      popupAnchor: readAnchor(),
+      ...(size === undefined ? {} : { popupSize: size }),
+    }
+  }
+  let service: SettingsUpdateFace | undefined
 
+  // Optional settings service: without one the commands still run from the
+  // entry config; they just cannot persist edits.
   ctx.inject(['settings'], (sctx) => {
-    service = sctx.settings as unknown as SettingsServiceLike
-    const scope = service.register(QUICK_COMMANDS_NS, QuickCommandsSettingsSchema) as {
-      get(): QuickCommandsSettings
-      watch(callback: (next: QuickCommandsSettings) => void): () => void
-    }
-    current = scope.get()
-    scope.watch((next) => { current = next })
+    service = (sctx as unknown as { settings?: SettingsUpdateFace }).settings
   })
 
   async function persist(patch: Record<string, unknown>): Promise<void> {
     if (service === undefined) {
       throw new Error('@fonlan/dsh-quick-commands: settings service is not available in this profile')
     }
+    // The write lands in this entry's config: the settings plane either swaps
+    // the volatile handles in place or re-applies the entry — both paths are
+    // picked up by the next read, which is why no local mirror is kept here.
     await service.update(QUICK_COMMANDS_NS, patch)
   }
 
   return {
-    get: () => current,
+    get: readDocument,
     commandsOf: (workspaceId) => {
-      const set = current.workspaces.find((w) => w.workspaceId === workspaceId)
+      const set = readWorkspaces().find((w) => w.workspaceId === workspaceId)
       return set === undefined ? [] : set.commands
     },
     setCommands: async (workspaceId, commands) => {
-      const next: WorkspaceCommands[] = current.workspaces.filter((w) => w.workspaceId !== workspaceId)
+      const next = readWorkspaces().filter((w) => w.workspaceId !== workspaceId)
       if (commands.length > 0) next.push({ workspaceId, commands })
       await persist({ workspaces: next })
     },

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 }
+}

package/src/shared/contract.ts

@@ -38,6 +38,16 @@ export interface QuickCommandsSettings {
   popupSize?: QuickPopupSize
 }
 
+/**
+ * The document's anchor as a usable literal. Wire data is defensive by
+ * contract: an older host can still answer with schemastery's empty-object
+ * resolution (`{}`) for this field, which must never reach a CSS class name or
+ * a radio `checked` comparison.
+ */
+export function anchorOf(value: unknown): 'corner' | 'button' {
+  return value === 'button' ? 'button' : 'corner'
+}
+
 /** Placeholder substitution values resolved for one execution. */
 export interface QuickRunPlaceholders {
   /** Workspace root path (also the execution cwd). */