Skip to content

Prepare 2.1.0 for npm, and stop the Stop hook from running npx - #3

Merged
chorta merged 1 commit into
mainfrom
claude/npm-package-prep-3d34b1
Sep 16, 2026
Merged

chorta merged 1 commit into
mainfrom
claude/npm-package-prep-3d34b1

Conversation

@chorta

@chorta chorta commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

Gets the kit ready for its first npm publish as ucsd-decorator-kit@2.1.0. It also fixes three bugs in how projects run the kit, which publishing would otherwise make worse.

The name has never been on npm, yet the README's first command, init, and the Claude Code Stop hook all fetch the kit from there.

Packaging

  • License: MIT, copyright The Regents of the University of California. It was the ISC default, with no license file.
  • Tarball contents: files now ships CHANGELOG.md and LICENSE. It leaves out compile-rules.mjs, check-library.mjs and sync-library.mjs, which only work from a checkout. The bin path is normalized, which silences an npm publish warning claiming the bin "was invalid and removed".
  • test/package.test.mjs: packs the kit, installs the tarball into an empty project, and runs from the installed copy: add, check, verify, npm run decorator:*, and both Stop hook commands through sh -c. Every other test runs from the checkout, where every file exists, so a path missing from files couldn't fail them. Dropping contracts from files fails this test.
  • Publishing: .github/workflows/publish.yml publishes when a GitHub release is published, using npm trusted publishing: no token, and provenance is attached. It refuses a tag that doesn't match package.json. prepublishOnly runs npm test.
  • RELEASING.md: covers cutting a release and the one-time manual first publish from the chorta account (the same owner as ucsd-decorator-v5). npm only offers trusted publishing once the package exists.
  • Schema link: decorator-kit.json's $schema pointed at a GitHub URL that returns 404. It now points at that kit version's schema on jsDelivr.
  • Plugin version: .claude-plugin/plugin.json was still 1.0.0. It now matches package.json, and the tests fail if the two differ.

Fixes

The Stop hook reported a regression after every turn.

  • The hook ran npx ucsd-decorator-kit verify || exit 2.
  • In a project without the kit in node_modules, npx got a 404 and the command exited 2. The agent was then told the chrome gate had found a regression, though nothing had been checked. That covers every project set up so far: init's install of the kit 404s, and add never installed it.
  • Once the package is published, the same command would instead download the newest release after every turn.
  • The hook now runs node_modules/.bin/ucsd-decorator-kit and never npx. When the kit is missing, the gate skips and a second hook tells the user, not the agent. add --with-hook replaces the old command and leaves the project's own hooks alone.

add's flags wrote things that couldn't run.

  • --with-ci wrote a workflow calling npm run decorator:check. Only --with-decorator added that script, and no flag installed the binary it calls.
  • All three flags now add the kit as a devDependency, at the version being run, plus the decorator:* scripts. A project that already lists the kit keeps its version.
  • init now pins the version the same way.

Re-running add on an init project dropped AGENTS.md from manages, so sync stopped refreshing it. add now keeps it.

The CLI tests run npm offline against an empty cache, so they never reach the registry. The three fixes above were each broken on purpose to confirm the tests fail.

After merging

  1. Run npm publish from a clean main as chorta (see RELEASING.md).
  2. On npmjs.com, add the trusted publisher (UCSD / decorator-kit / publish.yml), then require 2FA and disallow tokens.
  3. Create the v2.1.0 GitHub release. The workflow will fail for this one, since 2.1.0 is already on npm. From the next version on, the release publishes.

Existing projects follow the upgrade note in CHANGELOG.md: install the kit, re-run add --with-hook, then sync.

Not verified

The hook's missing-kit notice relies on Claude Code's documented handling of a Stop hook that exits 1 (shown to the user, not fed to the agent). The commands were tested in a shell, not in a live Claude Code session.

🤖 Generated with Claude Code

The kit has never been on npm, though the README's first command, `init`,
and the Claude Code Stop hook all fetch it from there.

Packaging:
- MIT license (The Regents of the University of California), replacing
  the ISC default with no license file.
- `files` ships CHANGELOG.md and leaves out the three scripts that only
  work from a checkout. The bin path is normalized, which silences an npm
  publish warning that wrongly said the bin was removed.
- test/package.test.mjs packs the kit, installs the tarball into an empty
  project, and runs add, check, verify, the decorator:* scripts, and both
  Stop hook commands from the installed copy. Every other test runs from
  the checkout, where a file missing from `files` can't be noticed.
- A GitHub release publishes through npm trusted publishing, with
  provenance. prepublishOnly runs the tests. RELEASING.md covers the
  one-time manual first publish from the chorta account.
- decorator-kit.json's $schema pointed at a GitHub URL that 404s; it now
  points at that kit version's schema on jsDelivr.
- .claude-plugin/plugin.json was still 1.0.0; it now tracks package.json,
  and the tests fail if they differ.

The Stop hook ran `npx ucsd-decorator-kit verify || exit 2`. In a project
without the kit in node_modules — every project set up so far, since
`init`'s install of the kit 404s and `add` never installed it — npx
failed, the command exited 2, and the agent was told the chrome gate had
found a regression after every turn. Once published, the same command
would download the newest release after every turn instead. The hook now
runs node_modules/.bin/ucsd-decorator-kit and never npx; when the kit is
missing the gate skips and a second hook tells the user, not the agent.
`add --with-hook` replaces the old command.

`add --with-ci` wrote a workflow calling `npm run decorator:check`, a
script only `--with-decorator` added, for a binary no flag installed.
All three flags now add the kit as a devDependency at the running version
plus the decorator:* scripts; `init` pins the version the same way.

Re-running `add` on a project `init` set up also dropped AGENTS.md from
`manages`, so `sync` stopped refreshing it. `add` now keeps it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@chorta
chorta merged commit 52a2597 into main Sep 16, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant