The Operational Contract: Packaged Tools, Platforms, and Runtime Closure
When a plugin changes the DSH environment, DSH Desktop has to control more than a button click. It must run the right package tool, in the right profile, with the right runtime, and know when the operation has really ended. This chapter examines that operational contract. It shows what the public package service owns, what a plugin author still has to decide, and why a bundled desktop runtime is only dependable when its physical contents and platform release conditions are checked.
The earlier discussion established a boundary between public Desktop services and private Electron machinery. Here that boundary meets a real task: installing, removing, or building a plugin. The important distinction is between controlling execution and controlling meaning. Desktop can provide a predictable process environment and lifecycle. It cannot decide whether a package belongs in a profile, whether its behavior is trustworthy, or whether a completed command produced a valid DSH composition.
The package service owns execution, not meaning
desktopPnpm is a Host service tied to the active DSH generation. Its direct run() operation launches the packaged pnpm entry with the active profile as its working directory. A plugin can use this path for work such as building a local extension or running a package-manager command without relying on whatever pnpm or Node installation happens to be on the user’s machine.
That direct path is intentionally low-level. The caller supplies the argument vector, often called argv: a list of separate arguments rather than one shell string. The service validates that the list is non-empty and contains no NUL characters, then passes it to the packaged process without asking a command shell to reinterpret it. This avoids a class of quoting and lookup problems, especially on Windows, where a command such as pnpm may resolve through a .cmd shim with different rules from a direct executable launch. It also makes the operation legible in logs and tests: the caller asked for a set of arguments, not for an opaque sentence to be parsed by a shell.
The service offers a second shape when ordinary DSH plugin-management behavior matters. runPlugin() invokes the packaged DSH CLI with the active profile and a caller-owned working directory. That route preserves the upstream semantics that reconcile a profile’s plugin bundles and dependencies. The distinction is practical. Direct pnpm is appropriate when the caller owns the package operation and wants Desktop’s runtime. The DSH adapter is appropriate when the operation must remain an official DSH plugin-management action. Choosing between them is an ownership decision, not a matter of preferring one command name.
A narrow external-market adapter exists for a more constrained compatibility case. It accepts an add operation with one exact npm package target and uses the packaged DSH path rather than letting a market component construct an arbitrary process invocation. The constraint is meaningful because a compatibility adapter can reduce the amount of policy it has to interpret. It does not turn the market or the package into a trusted component; it limits the shape of the request crossing the boundary.
The service also owns the mechanics of an active process. It exposes separate stdout and stderr streams, returns a completion promise with an exit code and terminating signal, and provides cancellation. It permits only one package operation per generation. That gate prevents two mutations from competing for the same profile’s dependency and bundle state, but it is not a global package lock for every process on the machine. A caller still needs to handle the possibility that another tool changes the same data outside Desktop’s service.
Waiting for done is part of the contract.