dsh-plugin-ui-toggle

Readme

# dsh-plugin-ui-toggle

[中文](./README.zh.md)

Turn any composed dsh plugin on or off from the web UI — **Settings → Plugins → Plugin switches**.

Every row is one entry in the Loader tree. Flip a switch and it:

- **takes effect immediately**, with no restart, and
- **survives a restart**, because the switch is stored as a `disabled:` row in the profile's own `cordis.patch.yml` — the very file dsh composes the plugin tree from at boot.

Zero runtime dependencies, no build step.

## Install

```sh
dsh plugin --profile web add github:Biobuilder-ai/dsh-plugin-ui-toggle
```

Then restart `dsh web`. `dsh plugin` adds the package to `dsh.profile.bundles` on its own, because this package declares `dsh.bundle` in its manifest.

## How it works

dsh already watches the profile's `cordis.patch.yml` through the HMR service (`watchUserPatches` in `@deepseek-ai/dsh-app-boot`) and re-applies the whole user patch layer whenever the file changes. So this plugin does exactly one thing: it writes `- id: <entry id>` / `disabled: true|false` rows into a **managed block** at the end of that file.

```yaml
# >>> dsh-plugin-ui-toggle:begin — managed block, edited from the web UI
- id: "web-ui-git-graph"
  disabled: true
# <<< dsh-plugin-ui-toggle:end
```

The write itself is what applies the change: the entry's fiber starts or unwinds from the patch re-apply. The plugin never calls `Entry.update()`, and therefore never writes back into the composed `cordis.yml`.

Nothing outside the two markers is touched — hand-written rows and comments above the block survive byte for byte. You can edit the block by hand, or delete it entirely to clear every override.

Because persistence and live application are the same mechanism, there is no second state store that can drift out of sync with the running tree.

## Entry ids

The `id` a switch writes is the **unqualified patch id** (`web-ui-pet`), not the Loader's qualified path (`include:web-ui-pet`) — `applyEntryPatches` matches the former. The qualified path rides along as a `path` field for display only.

## Rows that cannot be switched off

A few entries would take away the surface the switch panel itself lives on; turning one off would leave no way back except editing the patch file by hand. They are marked **Required** in the UI, and the host refuses the write with HTTP 409:

`dsh-plugin-ui-toggle`, `@deepseek-ai/dsh-host-webserver`, `@deepseek-ai/dsh-host-frontend-static`, `@deepseek-ai/dsh-web-frontend`, `@deepseek-ai/dsh-client-modules`, `@deepseek-ai/dsh-api-gateway`, `@deepseek-ai/dsh-client-ui-layout`, `@deepseek-ai/dsh-client-ui-settings`, `@deepseek-ai/dsh-client-ui-settings-plugins`.

Everything else is fair game, including host-side capability plugins. Switching off something you depend on makes that capability disappear; delete its row from the managed block to get it back.

## HTTP surface

Same-origin, consumed by the browser half:

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/ui-toggle/entries` | List patchable entries with their current state |
| `POST` | `/ui-toggle/set` | Body `{ id, enabled }`; writes the managed block |

## Composition

The package contributes one host row from the bundle patch it ships:

```yaml
- insert:
    - id: ui-toggle
      name: 'dsh-plugin-ui-toggle'
```

The browser half is loaded from the `dsh.client` manifest and registers a `settings.plugins.tab` slot. `webServer` is picked up through `ctx.inject` rather than declared as a required service, so the row still activates in a headless profile — there it simply contributes nothing.

## Requirements

- dsh with the web profile (`@deepseek-ai/dsh-web-app`)
- The `webServer` host service and the `settings.plugins.tab` client slot, both shipped in the stock web composition

## License

MIT