dsh-lockstep

Readme

# dsh-lockstep

Pin-aware updater for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

The stock command `dsh plugin --profile web update` is **pnpm update**. It floats.
The community updaters (dsh-update-checker, dsh-safe-updater, dsh-market, …) also
float a live profile to whatever is newer.

**lockstep does not float.** It compares a reviewed lockfile to npm and GitHub,
proposes pin bumps, and stops. You commit the lockfile. Every machine re-runs
the installer.

```text
check  →  plan  →  review  →  apply --write  →  commit  →  install.sh on each host
```

## Install

CLI, no dsh required:

```bash
npx -y github:da-beda/dsh-lockstep#v0.1.1 check --lock plugins.lock.json
```

As a dsh plugin (registers `lockstep_check` / `lockstep_plan` tools):

```bash
dsh plugin --profile tui add github:da-beda/dsh-lockstep#v0.1.1
dsh plugin --profile web add github:da-beda/dsh-lockstep#v0.1.1
```

## Lockfile

Same shape as [da-beda/dsh-fleet](https://github.com/da-beda/dsh-fleet) (private kit):

```json
{
  "runtime": { "package": "@deepseek-ai/dsh", "version": "0.1.1-rc.2", "spec": "@deepseek-ai/dsh@0.1.1-rc.2" },
  "plugins": [
    { "id": "modlens", "spec": "@liustack/modlens@3.24.1" },
    { "id": "open-in-vscode", "spec": "github:omdsh-dev/dsh-open-in-vscode#<sha>" }
  ]
}
```

`github:owner/repo` with no `#ref` is **unpinned**. `plan` proposes a HEAD SHA.
A tag (`#v0.1.1`) stays a tag. A SHA pin is current until HEAD moves.

## Commands

```text
dsh-lockstep check [--lock plugins.lock.json] [--json]
dsh-lockstep plan  [--lock plugins.lock.json]
dsh-lockstep apply [--lock plugins.lock.json] --write
```

`apply` refuses to write without `--write`. It never runs `dsh plugin update`.

Exit codes: `0` all current, `2` drift (`behind` or `unpinned`) or missing `--write`.

Set `GITHUB_TOKEN` (or `GH_TOKEN`) if you hit GitHub API rate limits.

## Why this exists

People already built updaters. They solve a different problem: “make this
machine latest.” That is the wrong default while `@deepseek-ai/dsh` is an RC
and plugins run with process privileges.

lockstep solves: “keep N machines on the same reviewed pins, and notice when
the world moved.”

## Security

See `SECURITY.md`. Short version: this tool talks to the npm registry and
GitHub. It does not execute package install scripts. Writing a lockfile is
not installing code.