Publish a DeepSeek Harness plugin to npm: build traps

The core value of publishing a DeepSeek Harness plugin to npm is distributing prebuilt code: what users install from npm is already compiled, so installing triggers no build script and needs no allowBuilds permission. A git install pulls sources instead, and without a prepare script there is no lib/ — it breaks the moment it installs. The same constraints apply to every DSH plugin you ship.

First, the trap: a DSH plugin git install gets sources

A git install never runs your build script, so a TypeScript package arrives without its lib/ output. The official docs are blunt about it, and the fix has two halves (source):

1. Author side: ship a prepare script (pnpm runs it after a git install) that builds the published entry points from source, and make it self-contained — it must not assume dev-only context such as a sibling monorepo checkout.
2. User side: allow the build. pnpm ≥10 refuses to run a git dependency's prepare by default, so the first dsh plugin --profile demo add github:you/hello-plugin fails; dsh points out the fix, which is writing the package key pnpm printed into the profile's pnpm-workspace.yaml — after which the add should be expected to succeed:

allowBuilds:
  dsh-hello-plugin: true

Take that allowance seriously: it means "permission to execute this package's code on your machine at install time," outside any sandbox the agent runs under. Allow only packages whose source you trust, and pin a commit (github:you/hello-plugin#<sha>), or a later push could silently change what actually runs.

Why publishing a DSH plugin to npm is easier

Publishing to npm moves the build from the user's machine into your release process. The two distribution paths the official docs describe as needing no build permission at all are:

On the user side, dsh plugin add <package> is enough to get prebuilt code. That is the entire reason to prefer npm — not reputation, but one less install-time authorization and one less class of failure.

DSH plugin pre-publish checklist

Five items, none optional; missing one shows up as "installed but not in effect" rather than a clear error.

1. main (or exports) points at the built entry — not src/;
2. type: module;
3. files includes the entry and cordis.patch.yml — drop the patch file and the config layer never installs;
4. dsh.bundle.patch points at the patch file — drop it and the package installs as a plain dependency with no layer;
5. version is bumped — npm refuses to overwrite a published version.

Install it locally with dsh plugin add ./hello-plugin before publishing; the package layout and layer order are covered in packaging into a bundle.

The DSH plugin publish flow

The flow is short; the risk sits in the checklist above. A typical sequence:

1. Build the publish artifacts: pnpm run build, which you should expect to leave lib/ current.
2. Self-test through the install path: in a clean profile run dsh plugin --profile demo add ./, which you should expect to load the plugin and apply its behavior.
3. Publish: pnpm publish.

Two easily missed points: ① a scoped package (@your-scope/xxx) must declare itself public on first publish, or it defaults to private; ② tag the matching git commit afterwards, so "the version users installed" maps to "the commit in your repo" — that saves time when debugging in production.

Alternative: shipping a DSH plugin as a pnpm pack tarball

For internal distribution or a pilot, use a tarball instead of npm. The official route:

1. Author side: pnpm pack, which you should expect to produce dsh-hello-plugin-0.1.0.tgz.
2. User side: dsh plugin add ./hello-plugin-0.1.0.tgz, which you should expect to install the built artifacts.

A tarball is also built code, so it needs no build permission; the trade-off is no version index, so upgrades mean shipping a new file.

Verifying a published DSH plugin

Verify in a clean environment, or you are testing "dependencies already present locally" rather than "the package is complete."

1. Use a different profile (or a clean machine): dsh plugin --profile fresh add <package>;
2. Inspect the layer before booting: dsh --profile fresh --dump-config to confirm the bundle's layer appears;
3. Boot and watch the plugin's log lines;
4. To list it in the plugin directory, follow publishing to the plugin hub, then check the installed list in DSH Plugin Hub.

If install reports a missing entry, first check whether the file main points at is inside files — the most common npm-publishing failure. It works locally because src/ exists there, but the published package does not carry it. Environment-level issues (Node version, pnpm) are covered in environment setup.