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}`
  and `apps/*`. Dep flow: `ui-agent → react-devkit → react-adapter → ui-foundation`.
  - ⚠️ **The three dependent UI packages pin their siblings with `^X` ranges**:
    `react-adapter` → `ui-foundation`; `react-devkit` → `react-adapter`, `ui-foundation`;
    `ui-agent` → `react-adapter`, `react-devkit`, `ui-foundation`. 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).
  - The four packages are published to npm, so they are `private: false`. Keep them that
    way: the npm publish step skips private packages without an error.
  - Regenerate the whole workspace with **one** command: `cd ui && npm install --package-lock-only …`.
- **`backend/core/*`**: `agent, app-runtime, client, gateway, identity, kernel, mcp, mdk,
  mdk-worker, rbac` 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 (for example `gateway` → `app-runtime`, `identity`,
  `rbac`). Bump those ranges with the versions, or npm stops resolving the workspace
  member and falls through to the registry. The pin check below lists every one.
- **`packages/cli`** and **`packages/mdk-skill`**: root workspace members too. `cli` pins
  most of the backend packages with `^X`, and the scaffold templates under
  `packages/cli/templates/` pin `^X` as well. A scaffolded project installs those from
  the registry, so a stale template pin installs an old release.
- **`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. The `mdk-app.yaml` versions listed
in the topology are on the release line too.

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)
```

Then the **pin check**. The npm publish step accepts an internal pin only when it is
exactly `^<release>`: at release `0.12.2`, a leftover `^0.12.1` stops the publish even
though npm itself would resolve it, and `*` is rejected too. `*` is fine only in
`private: true` packages. Before the bump this lists every pin; after it, it should print

From tetherto/mdk, Apache-2.0.

More from tetherto/mdk