dsh-safe-updater

Readme

# dsh-safe-updater

Guarded updates for [DeepSeek Harness](https://github.com/deepseek-ai/DeepSeek-Harness). It checks npm releases, clones the selected profile into an isolated `DSH_HOME`, installs its dependencies, validates the composed config, starts a temporary Web server, and only then allows a supervised switch. Failed candidate health checks roll back to the previous version.

The default mode is **notify**. Installing this package does not silently replace a running Harness.

## Install

```bash
dsh plugin --profile web add dsh-safe-updater
```

The bundle inserts the plugin with this safe default:

```yaml
- insert:
    - id: safe-updater
      name: dsh-safe-updater
      config:
        mode: notify
        channel: latest
        profile: web
        checkIntervalMs: 21600000
        checkOnStart: true
```

Available plugin tools:

- `dsh_update_status`: read current, available, staged, and rollback state.
- `dsh_update_check`: check now; behavior follows the configured mode.

## Modes

| Mode | Behavior |
| --- | --- |
| `notify` | Check and record a newer release. Never install or restart. |
| `stage` | Clone the profile and run install, config, and HTTP smoke checks. Never restart. |
| `apply` | Stage, then request a switch from the external supervisor. Refused outside supervisor mode. |

## Supervisor and rollback

Run the Web profile under the updater when you want automatic activation:

```bash
dsh-safe-updater supervise \
  --version 0.1.1-rc.1 \
  --profile web \
  --host 127.0.0.1 \
  --port 3080
```

Then change the plugin's `mode` override to `apply`. When a staged candidate is ready, the plugin writes a version request. The supervisor starts that exact version with argv-based process spawning, waits for HTTP health, commits it, or returns to `previousVersion`.

Manual commands:

```bash
dsh-safe-updater check --current-version 0.1.1-rc.1
dsh-safe-updater stage --version 0.1.1-rc.1 --profile web
dsh-safe-updater status
dsh-safe-updater rollback
```

## Trust and security model

- Registry version strings are parsed as semantic versions and never executed as shell text.
- Candidate commands use argument arrays with `shell: false`.
- `.credentials.yaml`, sessions, workspaces, and other runtime data are never copied into staging.
- State and locks are stored under `~/.dsh/safe-updater` with restricted permissions and atomic replacement.
- Smoke mode disables the updater timer to prevent recursive staging.
- Update errors are logged and recorded; they do not interrupt the agent loop.

The selected profile's npm dependencies are still executable supply-chain inputs. Review and pin third-party plugins. Staging deliberately runs normal install scripts so native plugins are tested faithfully.

## Publishing

GitHub Releases are the source and audit trail. npm is the installation channel. After configuring npm trusted publishing for this repository, set the GitHub Actions variable `NPM_PUBLISH_ENABLED=true`; tagged releases then publish with provenance via `.github/workflows/publish.yml`. Or publish locally after `npm adduser`:

```bash
npm publish --access public --provenance
```

## License

MIT