artemis-kit/AGENTS.md

# Repository guidance

Keep README.md focused on package usage and installation. Document development
checks, CI workflows, and release procedures in this file. This repository uses
Gitea at https://git.warky.dev; workflows belong in `.gitea/workflows/`.

## Development checks

`pnpm-workspace.yaml` explicitly allows esbuild install scripts through
`allowBuilds` for pnpm versions that require dependency build approval. Keep
approvals scoped to the dependencies that need them.

Run `pnpm test` for the test suite and `pnpm check:bundle` for a production build
with bundle checks. Builds fail on direct eval warnings. The bundle check measures
raw and gzip bytes for every emitted JavaScript file against
`scripts/bundle-budgets.json`; missing outputs and unbudgeted chunks also fail.
Review intentional size changes before updating budgets. Gitea Actions runs both commands on
pushes and pull requests via `.gitea/workflows/ci.yml`, using a runner with the
`ubuntu-latest` label. Action sources use explicit URLs so they do not depend on
the server’s default action host. No additional runtime dependencies are required by the
collection or sorting helpers.

## Publishing to Gitea Packages

`.gitea/workflows/publish.yml` publishes `@warkypublic/artemis-kit` when a `v*`
tag is pushed to Gitea or manually dispatched from the Actions UI. The
destination is
`https://git.warky.dev/api/packages/<owner>/npm/`, where `<owner>` is the Gitea
repository's user or organization (not necessarily the npm scope `warkypublic`).

1. The workflow uses the existing `PACKAGE_REGISTRY_TOKEN` Actions secret.
   It must have **Packages: Read & Write** access from a user allowed to publish
   under the repository owner. npm token authentication does not require the
   existing `PACKAGE_REGISTRY_USERNAME` secret. Do not put the token in the repository.
2. Run `pnpm exec changeset version` to apply pending changesets. Review and commit
   the updated version, changelog, and consumed changesets with the release changes.
3. Create and push a matching tag to the Gitea remote, for example `v1.1.0` for
   package version `1.1.0`. To publish manually, run the workflow from the Actions
   UI and set its required `release_tag` input to the matching tag. Checkout and
   validation use that tag; the workflow rejects tags that do not exactly match the
   package version. It then runs tests and bundle checks before publishing with
   pnpm, which applies the `publishConfig` entries for built JavaScript and
   declarations.

## Cutting a release with `make release`

`make release [BUMP=patch|minor|major]` (default `patch`) runs
`scripts/release.sh`, which:

1. Finds commits since the last changeset file (`.changeset/*.md`) and writes
   a new changeset from their subject lines, bumping `@warkypublic/artemis-kit`
   by `BUMP`.
2. Runs `pnpm changeset version` to consume the changeset and bump the
   package version/changelog.
3. Commits the result, tags it `v<new-version>`, and pushes the commit and
   tag to `origin` (GitHub) — this triggers `.github/workflows/publish_github.yml`.

It exits without changes if there are no commits since the last changeset, or
if the resulting tag already exists.

Stable versions receive the `latest` dist-tag; prereleases receive `next`.
Existing package versions cannot be overwritten; release a new version instead.
This workflow adds Gitea as a publishing destination without changing the default
registry for local publishing. After the first upload, link the package to this
repository in the package settings to show it in the repository's Packages tab.
See the [Gitea npm registry documentation](https://docs.gitea.com/usage/packages/npm/)
and [package access rules](https://docs.gitea.com/usage/packages/overview/).