English

日本語

English

日本語

Appearance

Blog ·

Upgrade every debuff package in one command ​

From 0.21, npx debuff upgrade moves a project to the latest debuff in one step. It sets every @debuffjp/* package in package.json to the new release together, installs with the project's own package manager, then runs the new version's doctor --fix, which also rewrites the project's agent skills for that version. --dry-run shows the plan first:

text
●  @debuffjp/audio ^0.19.0 → ^0.20.0
●  @debuffjp/core ^0.19.0 → ^0.20.0
●  @debuffjp/input ^0.19.0 → ^0.20.0
●  @debuffjp/juice ^0.19.0 → ^0.20.0
●  @debuffjp/cli ^0.19.0 → ^0.20.0
●  @debuffjp/dev ^0.19.0 → ^0.20.0

[debuff] would move to 0.20.0
         what changed: https://github.com/debuffjp/debuff/blob/main/tooling/cli/CHANGELOG.md

Why the packages move together ​

debuff's packages are released as one set, all at the same version, and they expect each other's exact behaviour. A project with @debuffjp/core 0.20 and @debuffjp/dev 0.19 can fail in ways that look like bugs in your game, so debuff doctor treats mismatched versions as a problem to fix. Upgrading one package by hand, then the next, passes through exactly that state. upgrade changes them all in one write.

What it changes, and what it leaves alone ​

  • Every package in debuff's set: the @debuffjp/* packages and create-debuff, in dependencies and devDependencies. Other packages, including @debuffjp/tenten, which ships on its own schedule, are left as they are.
  • The range style you chose: ^0.19.0 becomes ^0.20.0, an exact 0.19.0 becomes 0.20.0, and ~ stays ~.
  • Never a downgrade: if a package already declares something newer than the latest release (a prerelease you're trying), it stays. --to <version> picks a version on purpose, including an older one.
  • Workspace and file links: workspace: and file: entries are left alone, so it's safe to run inside a monorepo.

The new version finishes the job ​

The command runs from the CLI you have, which is the old one. So after the install, it hands over to the newly installed CLI and runs its doctor --fix. That's the version that knows the new release's checks and has its agent skills, so the project's .claude/skills/ and .agents/skills/ end up describing the debuff it now runs. If any required check still fails afterwards, upgrade exits 2 and says to run doctor for the fixes.

For agents, npx debuff upgrade --json returns the plan, the install command it ran and the doctor result as one JSON document. The project's own agent guide tells agents to ask before upgrading, since a new release can change behaviour.

Knowing when there's something to upgrade to ​

npx debuff doctor now says when a newer debuff is out, as advice that doesn't fail the check. And once a day, at the end of a command, the CLI prints one line on stderr when there's a newer release:

text
debuff 0.21.0 is out (you have 0.20.0): npx debuff upgrade

It's quiet in all the places a line like that gets in the way: never with --json, never in CI, and never after dev, create, doctor or upgrade, which already cover it. DEBUFF_UPDATE_CHECK=0 turns it off. The check asks the npm registry for the latest version with a short timeout, and when the registry can't be reached it says nothing.

Try it on a project:

bash
npx debuff upgrade --dry-run