bump-mdk

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bump MDK versions

Raise versions across the monorepo and regenerate **every** lockfile that
cascades from the change, so the lockfile-sync gate stays green.

Target version: **$ARGUMENTS** (e.g. `0.4.0`, optionally a scope). If empty, ask
what to bump to and confirm scope.

## Fast path: the release scripts

The whole release line moves to one fixed version, with the root `package.json` as the source of
truth. Two dependency-free scripts in `scripts/release/` do what the rest of this file describes by
hand:

```bash
node scripts/release/bump.mjs <version> [--dry-run] [--skip-registry] [--offline]
node scripts/release/check.mjs [<version>] [--offline]
```

`bump.mjs` sets every `version`, rewrites every internal `@tetherto/mdk-*` `^X` pin in all four
dependency fields (`devDependencies` included), moves the release-line `mdk-app.yaml` files, the
README release links and the link-check skip list, regenerates every lockfile and the UI registry,
then runs `check.mjs`. `check.mjs` is the version, pin, app, private-flag and lock-drift checks in
one command; it exits 1 on any problem. Neither command commits, tags or publishes.

Use the manual procedure below when the scripts cannot run, or to understand what they did. A
package that must stay off the line (the vendored `mdk-crypto-lib`) is listed, with a reason, in
`OFF_LINE` in `scripts/release/lib.mjs`. The npm publish plan is still a separate dry run.

## The gate this satisfies

CI runs, **per package**, from that package's directory:

```bash
npm install --package-lock-only --ignore-scripts --no-audit --no-fund
git diff --exit-code <that>/package-lock.json
```

If regenerating the lock produces *any* diff, the job fails with
`package-lock.json is out of sync with package.json`. So the rule is simple:
**after editing any `package.json`, regenerate the locks and commit a tree where
that command yields zero diff.**

⚠️ **The gate does NOT cover `examples/`.** The lockfile-consistency step runs
only for the ui, core and workers installs; the examples job warms the dependency
cache without checking anything. Example locks can therefore drift for entire
release cycles without turning CI red — one has been found carrying embedded ui
versions two releases stale. Always regenerate and inspect the `examples/*` locks
yourself; never infer they are clean from a green CI run.

## Repo version topology (why one bump cascades)

Packages are wired together with `file:` links, so bumping one package's version
changes the *embedded* version recorded in the lockfile of every package that
links it. The drift is often NOT in a lock's own `version` field — it's in the
embedded `file:`-dependency entries.

- **`ui/`** — a single npm workspace (Turborepo) with **one** root
  `ui/package-lock.json`. Members: `packages/{ui-foundation,react-adapter,react-devkit,ui-agent,cli,fonts}`
  and `apps/*`. Dep flow: `react-devkit → react-adapter → ui-foundation`.
  - ⚠️ **`packages/react-devkit/package.json` pins internal deps with ranges**
    (`@tetherto/mdk-react-adapter: ^X`, `@tetherto/mdk-ui-foundation: ^X`). When
    you bump those packages, bump these `^` ranges too, or `npm install` fails
    with `404 … @tetherto/mdk-* @^X not found` (it falls through to the registry
    because nothing local satisfies the range). `cli` similarly pins
    `@tetherto/mdk-react-devkit: ^X`.
  - Regenerate the whole workspace with **one** command: `cd ui && npm install --package-lock-only …`.
- **`backend/core/*`** — `agent, app-runtime, client, gateway, mdk, kernel, mcp,
  mdk-worker` are all root npm workspace members, sharing the single root
  `package-lock.json`. Regenerate the **root** lock (`npm install
  --package-lock-only …` at the repo root) when any of these change, not a
  per-package one.
  They pin each other with `^X` ranges (`gateway` → `app-runtime`, `mdk-worker`;
  `app-runtime` → `gateway`; `mdk`, `mcp` → `gateway`; `client`, `mdk-worker` → `kernel`).
  Bump those ranges with the versions, or npm stops resolving the workspace
  member and falls through to the registry.
- **`backend/apps/*`** — the apps MDK ships (`agent`, `demo`), also root workspace
  members sharing the root lock, and **on the release line**: a release bump
  moves their `package.json` version with everything else. Each also carries a
  `version` in its `mdk-app.yaml` that must equal its `package.json` version
  (`mdk validate app` and `mdk add app` reject a mismatch), so bump
  `backend/apps/*/mdk-app.yaml` in the same change. Their `@tetherto/*` deps are
  linked, never fetched, so pin them at `*` (or a `file:` path): a version range
  there resolves against nothing and rots unnoticed — the agent app sat at
  `^0.0.0` across several releases with nothing to catch it.
- **Other `mdk-app.yaml` files on the release line** — no `package.json` beside
  them, so no validator catches drift; bump their `version` by hand:
  `examples/mvp-site/backend/gateway-plugins/site/mdk-app.yaml` and
  `backend/tests/benchmark/plugin/fleet-summary/mdk-app.yaml`. Leave
  `packages/cli/templates/app/mdk-app.yaml` at `0.1.0`: `mdk create app` resets a
  scaffold's `package.json` to `0.1.0` to match it, even though the template's
  `package.json` tracks the release.
- **`backend/workers/*`** — independent worker packages, also root workspace
  members sharing the root lock.
- **`examples/*`** — `examples/mvp-site` (the backend half) is a root workspace member sharing the
  root lock. The UI shells
  (`examples/mvp-site/ui`,
  `examples/mdk-ui-shell-template`) are the ones left with their own
  independent locks; they `file:`-link the `ui/packages/*` packages, so a ui
  bump cascades into their locks. Because the CI gate skips `examples/`, these
  are the locks most likely to be stale.

As of the 0.6.0 cycle versioning is **uniform across the release line**: every
tracked package sits at the same version, `mdk-worker` no longer lags, and
`mdk-ui-shell-template` has moved off its scaffold default onto the shared
version — treat it as a normal package in future bumps. `backend/apps/*` are on
the release line too, together with the `mdk-app.yaml` versions listed in the topology.

Still **never blanket-set versions by find-and-replace.** Confirm the current spread
first by *parsing* each manifest, not grepping it (a bare `grep -m1 '"version"'` can
latch onto a nested field):

```bash
for f in $(git ls-files '*package.json'); do
  node -e 'const j=require("fs").readFileSync(process.argv[1],"utf8");const o=JSON.parse(j);console.log(`${o.version??"<none>"}\t${process.argv[1]}`)' "$f"
done | sort | grep -v '^<target>'   # lists everything not already at the target
git ls-files '*mdk-app.yaml' | xargs grep -H '^version:'   # app manifests (YAML, top-level key only)
```

From tetherto/mdk, Apache-2.0.

More from tetherto/mdk