pax-beehive/dsh-hub-cli

DSH Hub CLI – Share & Apply DeepSeek Harness (DSH) Plugin Presets

What it is – A Node‑based command‑line tool that lets you capture the exact state of a DeepSeek Harness (runtime version, ordered plugins, configuration patches, and required environment variables) and publish it as an immutable Preset Release on the public DSH Plugin Hub. Others can then fetch that preset and reproduce the same environment with a single command.

Why it matters

Problem	DSH Hub solution
Drift – teammates manually install plugins, versions change over time.	Presets lock runtime, plugin versions, load order, and source hashes.
Hidden configuration – secrets and patch files are scattered in docs or chat.	Only `${ENV_VAR}` placeholders are published; actual secret values stay local.
Unreliable onboarding – “works on my machine” stories.	`profile apply` stages, validates, and atomically swaps the whole profile, with a reversible revision history.
Manual upgrades – risky, error‑prone.	`profile diff` shows exact changes; `profile upgrade` applies them; `profile rollback` restores the previous revision.

Core concepts

Preset Release – a small, content‑addressed JSON/YAML document (sha256 hash) that records:
- The DSH runtime version (@deepseek-ai/dsh).
- An ordered list of bundles (plugins) with exact npm integrity hashes or pinned Git commit IDs.
- The author’s cordis.patch.yml configuration.
- Declared inputs (environment variables) needed at runtime.
Profile – a local directory (~/.dsh/profiles/<name>) that holds the currently installed plugins, lockfile, and patch.
Plan – a preview of a mutation (apply/upgrade) that includes a fingerprint of the current state and an expiry (30 min). The plan must be explicitly approved before any changes are made, making the CLI safe for AI agents.

Main commands (quick reference)

Command	Purpose
`dsh-hub profile share <slug> --version <v> --profile <name>`	Capture the local profile and publish an immutable preset.
`dsh-hub profile apply <slug> --version <v> --profile <name>`	Fetch a preset, stage it, validate, then atomically replace the local profile.
`dsh-hub profile diff …`	Show a line‑by‑line comparison between local state and a preset.
`dsh-hub profile upgrade …`	Upgrade to a newer preset version (with diff preview).
`dsh-hub profile rollback [revision]`	Restore a previous revision saved automatically on each apply.
`dsh-hub profile doctor`	Run health checks (missing inputs, version drift, lockfile integrity).
`dsh-hub search / info / install`	Browse the public plugin catalog and install individual plugins.
`dsh-hub login`	Authenticate to the Hub via a device‑code flow (or use a `DSH_HUB_TOKEN`).
`dsh-hub telemetry on	off`

How it works under the hood

Capture – The CLI reads ~/.dsh/profiles/<profile> (plugins, order, cordis.patch.yml, env‑var declarations) and builds a Release document with content‑addressed hashes for every artifact.
Publish – The Release is uploaded to the Hub API; the hash guarantees immutability.
Apply –
- --plan creates a JSON plan containing the Release hash, a pre‑condition hash of the current profile, and an expiry timestamp.
- The user (or a supervising human) approves the plan ID.
- The CLI stages the new plugins in a temporary directory, runs structural checks and dsh --dump-config to validate the patch.
- On success the staged directory atomically replaces the live profile; the previous version is kept as a revision for rollback.
Security checks –
- Release hash verification before any install.
- Only environment‑variable placeholders are allowed in published patches; actual secret values are rejected.
- Tokens are stored with 0600 permissions; telemetry is opt‑out.

Typical workflow

# 1️⃣ Install the CLI globally
npm i -g @dsh-plugin-hub/cli

# 2️⃣ Share your current workspace as a preset
dsh-hub profile share my‑workspace --version 1.0.0 --profile web --dry-run   # preview

dsh-hub login                                                          # once

dsh-hub profile share my‑workspace --version 1.0.0 --profile web        # publish

# 3️⃣ A teammate applies it
dsh-hub profile apply my‑workspace --version 1.0.0 --profile web

dsh-hub profile doctor   # verify everything is healthy

Integration with AI agents

The repository also ships a dsh‑plugin package that exposes the CLI as agent tools (e.g., dsh_hub_profile_diff). Agents can generate a plan, present it to a human, and only after explicit confirmation execute dsh-hub operation apply <plan-id>. This design enforces a “human‑in‑the‑loop” safety barrier.

Development & Extensibility

Monorepo with four packages (schemas, registry, cli, dsh-plugin) all versioned together.
Built with Node ≥22.13 and pnpm; type‑checked with TypeScript and tested via Node’s built‑in test runner.
Contributing guidelines, code of conduct, and a governance model are provided.
The CLI is open‑source under the MIT license.

Security & privacy highlights

Content‑addressed releases (sha256) prevent tampering.
All plugin sources are pinned (npm integrity hashes or full Git commit IDs).
Plans expire after 30 minutes and abort if the local profile changes.
Secrets never leave the local machine; only variable names are published.
Optional telemetry is fully anonymous and can be disabled.

License

MIT – free to use, modify, and distribute.

Bottom line – DSH Hub CLI gives teams a reproducible, auditable way to share complete DeepSeek Harness configurations, turning a fragile “install‑this‑list‑of‑plugins” process into a single‑command, version‑controlled operation that even AI agents can safely invoke.