dsh-publish-plugin

dsh-publish-plugin

English | 简体中文

Publish a DeepSeek Harness plugin bundle to npm + GitHub (always both platforms) in one flow — the /publish-dsh-plugin command (human-driven in the Web GUI / TUI) and the publish_plugin tool (model-driven). Both share one publish domain and are fail-closed: nothing executes without explicit confirmation.

Installation

# from npm (recommended — the published package)
dsh plugin --profile web add dsh-publish-plugin
# or from git
dsh plugin --profile web add github:liulei237136/dsh-publish-plugin

After installation both /publish-dsh-plugin and publish_plugin are available (the command registers only when a command registry is composed; the tool only when a tool registry is).

Command usage

① /publish-dsh-plugin                  → discover candidates in the session directory (and ancestors / direct subdirectories)
② /publish-dsh-plugin <plugin>         → validate manifest + conflict checks + action summary
③ /publish-dsh-plugin <plugin> yes     → execute (npm publish + GitHub repo creation/push + tag + topic)

• Without yes it only summarizes, never executes (fail-closed);
• A taken version (already published) errors with a bump-the-version prompt; an existing package name / repo is a normal upgrade (new version, existing repo);
• Conflicts are re-checked right before execution.

Tool usage

Just ask the model to "publish this plugin". The model calls publish_plugin (plugin_path optional; defaults to the session directory), the tool validates, shows the action summary, and routes the final confirmation through ctx.approval — only allowed-once proceeds. The result returns to the model, which can verify the install, write a CHANGELOG, or handle failures.

Prerequisites

• Node.js + npm on the publishing machine
• gh CLI installed and logged in (gh auth login; if gh was installed after the host started, restart the host — PATH is snapshotted at startup)
• npm publishing auth — npm now requires 2FA or a bypass token (exact commands in Troubleshooting below):
  • either enable 2FA on the npm account (auth-only mode is enough), or
  • create a Granular Access Token with Bypass 2FA enabled and set it as the auth token

Troubleshooting

Symptom	Cause & fix
npm error 403 Forbidden - PUT ... - Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages	npm requires 2FA to publish. Enable 2FA on the account (npm profile enable-2fa auth-only — publishing then needs no OTP) or create a Granular Access Token with Bypass 2FA on https://www.npmjs.com/settings//tokens and run npm config set //registry.npmjs.org/:_authToken=<token>
npm error ENEEDAUTH: need auth ... You need to authorize this machine using npm adduser	Not logged in: run npm login, or set NPM_TOKEN (env var; a new env var requires restarting the host)
GitHub 仓库：gh 未登录 (check failed)	Run gh auth login; if gh was installed after the host started, restart the host (PATH is snapshotted at startup)
Command/tool not visible, or changes have no effect	Bundle layers are not hot-reloaded (only the user cordis.patch.yml is). Restart the web profile after installing or changing a bundle
pnpm blocks prepare on git installs	pnpm ≥10 requires allowlisting build scripts in the profile's pnpm-workspace.yaml (pnpm prints the key; dsh plugin hints too)

Notes

• Publishing waits synchronously on subprocesses (npm publish / gh can be slow); the UI waits, and cancellation interrupts. On Windows, cancellation terminates only the cmd wrapper of npm/gh — child processes may linger; clean up manually if needed;
• Partial failures report exactly which steps completed; finish the rest manually (e.g. npm published but GitHub failed);
• Git preflight (dirty worktree / mismatched remote) rejects before any side effect — the plugin never rewrites a remote and never auto-commits;
• The tool face refuses to execute without a composed ctx.approval (fail-closed);
• The install command shown after publishing uses --profile web because dsh plugin requires a profile; substitute your own (e.g. tui).

---

For maintainers: local development, the test suite and the self-hosted release flow live in CONTRIBUTING.md; fixed decisions and implementation notes in docs/design.md.