# Publishing `@open-hax/uxx`

This repository is a pnpm workspace. The root package intentionally uses
`workspace:*` dependencies during development, so publishing must go through
pnpm's pack/publish pipeline.

## Rule

Use `pnpm pack` / `pnpm publish` for releases. Do not use `npm pack` or
`npm publish` from this package while `package.json` contains `workspace:*`.

Why: pnpm rewrites workspace protocol dependencies in the packed manifest:

```json
"@open-hax/uxx-tokens-internal": "workspace:*"
```

becomes:

```json
"@open-hax/uxx-tokens-internal": "0.1.0"
```

The npm CLI does not do that rewrite and will publish the literal
`workspace:*` specifier, which breaks clean downstream installs.

## Pre-publish check

Run the release gate before publishing:

```bash
pnpm run release:check
```

This runs:

1. TypeScript typecheck.
2. Theme-pack Vitest coverage.
3. `pnpm pack` through `scripts/check-pack-manifest.mjs`.
4. A packed manifest scan that fails if any `workspace:` protocol remains.

For a narrow pack-only verification:

```bash
pnpm run pack:check
```

## Publish

Use the environment-authenticated npm config (`NPM_TOKEN` or existing npm login)
and publish with pnpm:

```bash
pnpm publish --access public
```

or:

```bash
pnpm run publish:public
```

After publish, verify npm metadata before updating consumers:

```bash
npm view @open-hax/uxx@<version> dependencies --json
npm view @open-hax/uxx@<version> exports --json
```

The dependency output must not contain `workspace:*`.

## Downstream consumers

Only update downstream repos after the npm version exists and its metadata is
clean. A clean install in a temp directory is the strongest quick smoke test:

```bash
tmp="$(mktemp -d)"
cd "$tmp"
npm init -y
npm install @open-hax/uxx@<version>
node --input-type=module -e "import '@open-hax/uxx/tokens'; import '@open-hax/uxx/eta-mu'; console.log('ok')"
```