dsh-native-command runs host executables without a shell and opens Host filesystem paths through the desktop. The command runner captures utf8 output, propagates cancellation, and hides transient Windows consoles. The path opener supports default-application and text-editor intents, browser-renderable documents, WSL translation, and desktop availability checks. It is a library, not a plugin: no ctx, no state, no events.

Use this package
Understand the implementation
Further Exploration
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

Use this runner when a host-side integration must execute one native command and needs its output, its failure, or both — and must never involve a shell.

Running a command

import { runNativeCommand } from '@deepseek-ai/dsh-native-command'

declare const script: string
declare const signal: AbortSignal
const { stdout, stderr } = await runNativeCommand('osascript', ['-e', script], signal)

On exit 0 the call resolves with captured stdout and stderr. On any failure it rejects with the exit code and both captured streams attached, so a caller can tell a missing tool (ENOENT), a cancellation (ABORT_ERR), and a real command failure apart without re-running the command.

Injecting the command boundary

The NativeCommandRunner type is the injectable command boundary for host integrations: pass the function (or a wrapper) where the integration needs a testable seam, so tests can substitute a fake runner.

Opening a Host path

openNativePath(path, signal) hands a path to the default application and prefers the named default browser for HTML and SVG where the platform can identify one. openNativeTextFile(path, signal) selects text-editor intent; on macOS it uses open -t. WSL paths are translated with wslpath -w before the Windows desktop receives them. canOpenNativePath() reports whether the current Host plausibly has a desktop target.

Understand the implementation

Implementation internals — click to expand

The command runner is a thin wrapper over Node's execFile. The path opener selects one shell-free command from platform and environment facts, while callers retain authority over which path may be opened.

Source map

File	Role
`src/index.ts`	Public command-runner and path-opener exports
`src/runner.ts`	Shell-free `execFile` adapter
`src/path-opener.ts`	Desktop detection, open intents, browser preference, and WSL translation
`src/invariant.ts`	Invariant companion (no runtime invariant; each run is one stateless child-process round trip)

What execFile gives the runner

execFile spawns the executable directly with an argv array — no shell string, no shell interpretation of the arguments. The signal option terminates the child when the caller's abort fires; windowsHide suppresses the transient console window on Windows. On a non-zero exit or spawn error, the callback attaches code, stdout, and stderr to the rejected error and keeps the original error as cause.

Further Exploration

Read these pages when you need the consumers or the general subprocess capability this utility deliberately is not.

Native directory picker — the OS chooser commands this runner executes.
Session Controller — resolves Session-relative workspace paths before opening them.
Settings Controller — selects settings documents and agent-preset directories.
Subprocess capability — the general subprocess seam, of which this package is not a part.

Model Experience

None, as the host-side utilities register nothing model-facing.

KV Cache effect

Nothing here enters a request prefix; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

These limits define when this runner is not the right tool. They are current package constraints, not a task backlog.

No output bounding — both streams buffer unbounded in memory; every current caller invokes small native tools whose output is a path or an error line. Adopt dsh-output-retention bounding before pointing this at commands with meaningful output volume.

Dev Note

Working context for maintainers — click to expand

None.

README.md

@deepseek-ai/dsh-native-command

Summary

Table of Contents