# dsh-hotplug-engine

[中文](./README.md)

A service plugin for managing DSH plugins. Marketplaces, agents, and other plugins can call it for the full chain: install, uninstall, enable, disable, rollback, audit.

## What it does

DSH manages plugins through `cordis.patch.yml` and the loader. This plugin wraps those operations into a service: edit the patch, run pnpm, confirm health after install, roll back on failure, audit everything. It only touches files and commands, never the core.

## What it doesn't do

- **Not a marketplace**: no catalog, search, rankings, or curation. The caller supplies `spec` (what to install, from where); the engine doesn't guess.
- **Doesn't rewrite official mechanisms**: HMR, loader, and patch semantics are official; the engine only consumes them.
- **Holds no state of its own**: the official config tree is the single source of truth; the engine only projects and diffs.
- **No install UI**: the UI is a minimal management panel (view, toggle, roll back, audit) — no spec input.

## Entry points

| Scenario | Entry |
|---|---|
| Marketplace / plugin-manager UI | inject `hotplugEngine`, or call REST |
| Agent sessions | `hotplug_*` tools |
| Host plugins | inject `hotplugEngine` |

## Install

```bash
pnpm --dir <profile-dir> add dsh-hotplug-engine
# or dsh plugin add dsh-hotplug-engine
```

Bundle package: restart the profile after install/uninstall; refresh the page for a new client panel.

## Enable / disable

- The engine edits the profile's `cordis.patch.yml`; once the loader reflects it, it takes effect (`mode:'hot'`). If not reflected, a restart is suggested.
- Patch rows — user-written or engine-written — can be toggled, in flow or block YAML.
- Rows default-disabled by DSH (in the bundle layer, with no engine-editable patch row) can't be modified: the UI shows 🔒 "default-disabled" and only flashes a hint on click; the API returns `HOTPLUG.PATCH.DEFAULT_DISABLED`.

## DSH versions

- Target `0.1.1-rc.2` (current), with a version support matrix (`supportReport()`).
- `dshPath` must be set explicitly to use the official `dsh plugin` CLI; otherwise pnpm.
- `0.1.0-rc.6` is legacy, no longer an acceptance target.

## Quick start

- **Host inject**: `inject: ['hotplugEngine']`, then call `install` / `rollback` / `enable` on `ctx.hotplugEngine`. The promise resolves when the operation is done.
- **REST**: prefix `/api/dsh-hotplug`, same-origin. Writes: `install` / `uninstall` / `enable` / `disable` / `rollback`. Reads: `snapshot` / `status` / `audit` / `operations` / `events` (SSE).
- **Tools**: `hotplug_status` / `hotplug_install` / `hotplug_uninstall` / `hotplug_toggle` / `hotplug_rollback` / `hotplug_audit`; write tools go through approval.

Full contract: [docs/01-contract.md](docs/01-contract.md).

## Changelog

**0.2.0**
- Added DSH `0.1.1-rc.2` support.
- `DshProfileAdapter`: only uses the official `dsh plugin` CLI when `dshPath` is set; otherwise pnpm.
- Structured patch write-layer; flow and block rows can be toggled; REST mounts once webServer is ready.
- DSH default-disabled gate: 🔒 badge + inline hint in the UI, `HOTPLUG.PATCH.DEFAULT_DISABLED` from the API.
- Card-based client panel (compact + collapsible), light/dark adaptive.

## License

MIT