dsh-publish-plugin

Readme

# dsh-publish-plugin

**English** | [简体中文](README.zh.md)

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

```sh
# 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/<you>/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](https://github.com/liulei237136/dsh-publish-plugin/blob/main/CONTRIBUTING.md); fixed decisions and implementation notes in [docs/design.md](https://github.com/liulei237136/dsh-publish-plugin/blob/main/docs/design.md).