Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"name": "ucsd-decorator",
"version": "1.0.0",
"version": "2.1.0",
"license": "MIT",
"description": "Build and edit UC San Diego web pages on the Decorator 5 design system without damaging the shared page chrome. Provides one writable canvas, a pinned source of truth for markup, and a CI-checkable chrome contract.",
"author": {
"name": "Cristian Horta, Web Technology Services, UC San Diego"
Expand Down
4 changes: 3 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# The kit's own gate. Three things must hold on every push:
# The kit's own gate. Four things must hold on every push:
#
# * the committed CLAUDE.md / AGENTS.md / .cursorrules /
# copilot-instructions.md are current with rules/ — they are generated, and a
Expand All @@ -7,6 +7,8 @@
# cannot reach the public page in a shape that makes the sync throw
# * `add` still refuses to write AGENTS.md, which is the property that keeps
# this kit safe to run inside a repository that has its own agent contract
# * the npm tarball still ships every file the CLI reads at runtime — tested
# by installing it, since the rest of the suite runs from this checkout
name: CI

on:
Expand Down
38 changes: 38 additions & 0 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Publishes ucsd-decorator-kit to npm when a GitHub release is published.
#
# Uses npm trusted publishing: npm exchanges this run's OIDC token for a
# short-lived publish credential, so there is no NPM_TOKEN secret to leak, and
# it attaches a provenance attestation tying the tarball to this commit and
# this workflow. The trusted publisher is configured on npmjs.com, not here —
# see RELEASING.md, including why the first publish is done by hand.
name: Publish

on:
release:
types: [published]

permissions:
contents: read
id-token: write

jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Trusted publishing needs npm 11.5.1 or later, which Node 22 does not
# bundle. No cache: npm advises against caching in release builds.
- uses: actions/setup-node@v4
with:
node-version: 24
registry-url: https://registry.npmjs.org
- name: Release tag matches package.json
run: |
expected="v$(node -p 'require("./package.json").version')"
if [ "$GITHUB_REF_NAME" != "$expected" ]; then
echo "::error::Release tag $GITHUB_REF_NAME does not match package.json ($expected). Bump the version in a pull request first."
exit 1
fi
# prepublishOnly runs `npm test`, including test/package.test.mjs against
# the tarball this step is about to upload.
- run: npm publish
50 changes: 49 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Changelog

## Unreleased
## 2.1.0

### Added

Expand Down Expand Up @@ -58,6 +58,42 @@

- Heading demotion in compiled rules no longer rewrites `# comment` lines inside
fenced code blocks.
- `decorator-kit.json`'s `$schema` pointed at a GitHub URL that returned 404.
It now points at the schema in the kit version that wrote the file, on
jsDelivr: `https://cdn.jsdelivr.net/npm/ucsd-decorator-kit@<version>/contracts/decorator-kit.schema.json`.
- **The Claude Code Stop hook reported a regression after every turn in
projects without the kit installed.** It ran `npx ucsd-decorator-kit verify
|| exit 2`. With the kit not on npm, npx failed, the command exited 2, and
the agent was told the chrome gate had found a regression when nothing had
been checked. Now on npm, the same command would download the newest release
after every turn. The hook now runs the kit from `node_modules` and never
calls npx. When the kit is not installed, the gate skips and a second hook
tells the person, not the agent.
- **`add --with-ci`, `--with-hook`, and `--with-decorator` now install the
kit.** The workflow `--with-ci` wrote runs `npm run decorator:check`, but
only `--with-decorator` added that script, and no flag installed the kit it
calls. Each of the three now adds `ucsd-decorator-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 installs the kit at the
version being run, too, rather than the newest.
- Re-running `add` on a project `init` set up dropped `AGENTS.md` from
`decorator-kit.json`, so `sync` stopped refreshing it. `add` now keeps it.

### Packaging

- First release published to npm. Later releases publish from a GitHub
release through trusted publishing, with a provenance attestation; see
`RELEASING.md`.
- Licensed under MIT. The package previously declared ISC and shipped no
license file.
- The tarball now includes `CHANGELOG.md`, and leaves out
`scripts/compile-rules.mjs`, `scripts/check-library.mjs`, and
`scripts/sync-library.mjs`, which only work from a checkout of this
repository.
- `npm test` installs the packed tarball into an empty project and runs `add`,
`check`, and `verify` from it, so a file missing from `files` fails CI.
- `.claude-plugin/plugin.json` carried version 1.0.0 through the 2.0.0
release. It now matches `package.json`, and `npm test` fails if they differ.

### Upgrading

Expand All @@ -67,6 +103,18 @@
an agent's.
- Run `sync` after upgrading so the managed rule files carry the new rule;
`check` fails until you do.
- **Projects set up before 2.1.0**, which most likely installed the kit
straight from GitHub, don't have it in `node_modules`. Install it, re-run
`add --with-hook` if the project uses the Claude Code hook, then sync:

```bash
npm install --save-dev ucsd-decorator-kit
npx ucsd-decorator-kit add --with-hook
npx ucsd-decorator-kit sync
```

`add --with-hook` replaces the old hook, merges into the rest of
`.claude/settings.json`, and skips rule files that already exist.

## 2.0.0

Expand Down
21 changes: 21 additions & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 The Regents of the University of California

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
19 changes: 16 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ on this page also works straight from the repository, which is what CI uses:
npx -y github:UCSD/decorator-kit init
```

That runs whatever is on `main` at the time, released or not, so use it to try
a change, not to set up a site.

That installs `ucsd-decorator-v5` — the Decorator itself — plus this kit, writes
the rules in the format each AI tool reads, installs the skill, wires
Dependabot and a CI workflow, and — for Claude Code — adds a `Stop` hook that
Expand Down Expand Up @@ -50,6 +53,11 @@ for the Claude Code Stop hook. The last one merges into an existing
`.claude/settings.json` rather than overwriting it, so a project's own hooks
and permissions survive.

Each of those three flags also adds `ucsd-decorator-kit` as a devDependency,
at the version you ran, along with the `decorator:*` npm scripts. The workflow
and the hook run the kit from `node_modules`, and without it installed they
have nothing to run. A project that already lists the kit keeps its version.

### Staying current

| Command | Does |
Expand All @@ -61,7 +69,10 @@ and permissions survive.

Both `ucsd-decorator-v5` and `ucsd-decorator-kit` are devDependencies, so
Dependabot opens a pull request when either moves: the Decorator and the rules
update through one mechanism. `check` fails the build if a kit upgrade landed
update through one mechanism. With the kit installed, `npx ucsd-decorator-kit`
runs that installed copy. Without it, npx downloads the newest release on
every run, so the kit version changes whenever a release ships, not when you
upgrade. `check` fails the build if a kit upgrade landed
without a `sync`, so a project cannot quietly run last year's rules.

`drift` covers the gap Dependabot cannot see — a push to `UCSD/Decorator` or a
Expand Down Expand Up @@ -221,8 +232,10 @@ contracts/ portable chrome regions, selector rules, and
checks/ the chrome integrity gate: chrome-contract.mjs
(CLI) and lib/ (tiers 1-4) — runs standalone,
`bin/cli.mjs verify` is a thin wrapper around it
test/ including the AGENTS.md refusal and the replayed
chrome-regression incidents
test/ including the AGENTS.md refusal, the replayed
chrome-regression incidents, and an install of
the packed tarball
RELEASING.md how a version reaches npm
```

`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, and `.github/copilot-instructions.md`
Expand Down
50 changes: 50 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Releasing

`ucsd-decorator-kit` is published to npm from GitHub Actions, by
[`.github/workflows/publish.yml`](.github/workflows/publish.yml), when a GitHub
release is published. Nobody runs `npm publish` from a laptop after the first
release.

## Cutting a release

1. In a pull request:
- Set the new version in `package.json` and `.claude-plugin/plugin.json`.
`npm test` fails if the two differ.
- Move the `## Unreleased` entries in `CHANGELOG.md` under a heading for the
new version.
2. Merge it.
3. Create a GitHub release from `main` with the tag `v<version>` — for example
`v2.1.0`. Publishing the release starts the workflow.

The workflow refuses a tag that doesn't match `package.json`, and `npm publish`
runs `npm test` first (`prepublishOnly`). That includes
`test/package.test.mjs`, which packs the tarball, installs it into an empty
project, and runs `add`, `check`, and `verify` from the installed copy.

To see exactly what will ship:

```bash
npm pack --dry-run
```

## Ownership

The package belongs to the `chorta` npm account, the same owner as
[`ucsd-decorator-v5`](https://www.npmjs.com/package/ucsd-decorator-v5).

## First publish (one time)

npm trusted publishing is configured from the package's settings page on
npmjs.com, which exists only once the package does. So the first version goes
up by hand:

1. From a clean checkout of `main`, signed in to npm as `chorta` with
two-factor authentication on, run `npm publish`.
2. On npmjs.com, open the package's **Settings** and add a trusted publisher:
GitHub Actions, organization `UCSD`, repository `decorator-kit`, workflow
`publish.yml`.
3. On the same page, under publishing access, require two-factor
authentication and disallow tokens. Trusted publishing is unaffected, and no
long-lived token can publish the package.

Every release after that goes through the steps above.
Loading
Loading