AGENTS.md · verdaccio/verdaccio

Sections

1. What this branch is
2. Repository structure
3. Setup, build, test, lint
4. Never ignore test failures
5. Testing conventions
6. Code style
7. Comments
8. Code reuse
9. Compatibility with package managers
10. Commits and pull requests
11. Changesets
12. Working with GitHub
13. Agent skills
14. Key configuration files

First lines (shown under the repo's MIT license)

# Agent Guide to the Verdaccio Repository

Context and rules for AI agents working on `verdaccio/verdaccio`. `CLAUDE.md` is a
symlink to this file. Humans are welcome to follow it too; where it repeats
[CONTRIBUTING.md](./CONTRIBUTING.md), CONTRIBUTING.md wins.

## What this branch is

`master` is the **9.x next** line: the monorepo that produces every
`@verdaccio/*` internal package, the `@verdaccio/ui-theme` web UI, and the
`verdaccio` binary in `packages/verdaccio`. It publishes under the npm tag
`next-9` and the Docker tag `nightly-master`. The support table, npm tags, and
Node.js policy for every release line live in [VERSIONS.md](./VERSIONS.md); the
security policy in [SECURITY.md](./SECURITY.md).

The other branches of this repository:

| Branch   | Role                                                                                                     |
| -------- | -------------------------------------------------------------------------------------------------------- |
| `master` | 9.x next. Source of truth for all `@verdaccio/*` packages and the UI theme. New features go here.        |
| `6.x`    | Current stable `verdaccio` (npm `latest`). Bug fixes only. Its `@verdaccio/*` internals come from `8.x`. |
| `7.x`    | Next major binary (npm `next-7`). Its `@verdaccio/*` internals come from `master`.                       |
| `8.x`    | Internal modules consumed by 6.x. Bug fixes only, no public `verdaccio` release.                         |

Rules that follow from this layout:

- **New features land on `master` only.** A feature that exists only on 9.x is
  not a parity gap.
- **A bug fix goes to every supported line that has the bug.** Fix it on
  `master` first, then port it to `6.x` (and to `8.x` when the bug lives in an
  internal module that 6.x consumes). One PR per branch. When the port is not in
  the same batch of work, say so in the PR description.
- **Each branch has its own toolchain.** Read the target branch's `package.json`
  (`engines.node`, `packageManager`) before running anything there; `6.x` uses
  yarn, the others use pnpm, and the Node.js floors differ.
- **Security reports never go through public issues or PR discussion.** Point
  reporters to SECURITY.md. On 9.x, security findings are handled as regular
  bugs, but the fix still avoids describing the exploit in public before a
  stable release carries it.

## Repository structure

Every package lives under `packages/` and is published as `@verdaccio/<name>`
unless noted. The request path is roughly `verdaccio` → `server` → `api`/`web`
→ `store` → `local-storage` plugin / `proxy` uplinks.

- `packages/verdaccio` — the `verdaccio` binary: `bin/verdaccio`, `src/start.ts`.
- `packages/cli` — CLI commands. `packages/node-api` — programmatic `runServer`
  / `startServer`.
- `packages/server/express` — the Express application (`@verdaccio/server`).
- `packages/api` — the npm registry HTTP API: publish, dist-tags, search,
  user/login/token, stage, whoami, ping.
- `packages/web` — web UI endpoints and middleware. `packages/plugins/ui-theme`
  and `packages/ui-components` — the React UI (`packages/ui-components` has
  Storybook; after bumping `msw`, regenerate its worker with `npx msw init public`
  and unregister the old one, see its README "Updating msw").
- `packages/store` — storage orchestration: local packages, uplink merge,
  filter pipeline, stage storage. `packages/plugins/local-storage` — the default
  filesystem storage plugin (`@verdaccio/local-storage`).
- `packages/proxy` — the uplink HTTP client.
- `packages/auth` — authentication, tokens, 2FA. `packages/plugins/htpasswd` and
  `packages/plugins/auth-memory` — bundled auth plugins.
- `packages/config` — configuration parsing, defaults, package access rules,
  uplinks, security settings.
- `packages/core/core` — shared utilities (`errorUtils`, `validationUtils`,
  `pkgUtils`, `searchUtils`, `streamUtils`, constants such as `HTTP_STATUS` and
  `API_ERROR`). `packages/core/types` — shared TypeScript types.
  `packages/core/tarball`, `packages/core/url`, `packages/core/file-locking` —
  focused helpers.
- `packages/middleware`, `packages/loaders` (plugin loading), `packages/logger`,
  `packages/hooks` (notifications), `packages/search`, `packages/signature`.
- `packages/plugins/audit`, `packages/plugins/memory`,
  `packages/plugins/package-filter` — bundled plugins (`verdaccio-audit`,
  `verdaccio-memory`, `@verdaccio/package-filter`).
- `packages/tools/helpers` — `@verdaccio/test-helper`: `initializeServer`,
  package metadata generators, publish helpers. The other `packages/tools/*`
  are private fixtures and release tooling.
- `e2e/` — end-to-end notes and Docker flows. The CLI battery comes from
  `@verdaccio/e2e-cli` (repository `verdaccio/e2e-tests`); the UI battery is
  Cypress under `cypress/`.
- `docs/` — migration guide and warning codes. `docker-examples/` — reverse
  proxy and deployment examples.

## Setup, build, test, lint

```bash
pnpm install                       # also installs the husky hooks
pnpm build                         # every package, required before tests
pnpm test                          # every package
pnpm --filter @verdaccio/store test                                # one package
pnpm --filter @verdaccio/store test test/versions.spec.ts          # one file
pnpm --filter @verdaccio/store test test/versions.spec.ts -t 'tag' # one case
pnpm lint && pnpm format:check     # oxlint + oxfmt, what CI runs
pnpm lint:fix && pnpm format       # apply fixes
pnpm type-check
```

**Packages consume each other through their `build/` output**, not `src`: every
`package.json` `exports` entry points at `build/`. After editing package A,
rebuild it (`pnpm --filter @verdaccio/<A> build`) before running tests in any
package that imports it, otherwise those tests exercise the stale build and pass
without touching your change. The [testing-changes](./.agents/skills/testing-changes/SKILL.md)
skill covers what to run for a given change.

Local server: `pnpm start` (API on port 8000 with the UI dev server), `pnpm
start:watch`, `pnpm debug`. Local registry for publishing the workspace
packages: `pnpm local:publish:release`. `DEBUG=verdaccio:* pnpm test` enables
the `debug` namespaces.

CI (`.github/workflows/ci.yml`) runs lint, format check, build and tests on
Node.js 24 and 26, a Docker build, the CLI e2e matrix (npm 10–12, yarn modern
3–4, pnpm 11–12, bun, deno) and the Cypress UI suite — but only on a ready PR
whose diff matches the workflow's `paths:` filter (`packages/**`, `tests/**`,
`docker-examples/**`, `package.json`, `pnpm-workspace.yaml`,
`vite.lib.config.mjs`, `.changeset/**`, or the workflow file itself); a
docs-only or `.agents/`/`.claude/`-only PR triggers none of it. **CI does not
run on draft PRs.** New third-party dependencies must be at least seven days old
(`minimumReleaseAge` in `pnpm-workspace.yaml`); an install that fails on that
rule is not a lockfile bug.

## Never ignore test failures

Do not dismiss a failing test as "pre-existing" or unrelated. Investigate every
failure. If a test was broken before your change, fix it as part of the work or
say explicitly why it cannot be fixed in this PR. Never skip, disable, or
loosen a test to make a run green.

## Testing conventions

- Vitest with `globals: true` (`vitest.config.mjs`). Tests live in
  `packages/<pkg>/test/`, named `*.spec.ts`; `packages/api` splits
  `test/unit` and `test/integration`, the latter driving a real Express app via
  `supertest` and `initializeServer('<config>.yaml')` with YAML fixtures in
  `test/integration/config`.
- `vitest.setup.mjs` disables network access with `nock` except for localhost.
  Mock uplinks with `nock` or a second local instance; never reach
  registry.npmjs.org from a test.
- Build fixtures with `@verdaccio/test-helper` (`generatePackageMetadata`,
  `generateRemotePackageMetadata`, `publishVersion`, ...) instead of hand-written
  manifests.
- A bug fix needs a regression test that fails without the fix. A feature
  needs tests for its observable contract at the layer that owns it (unit for
  a utility, `packages/api` integration for a route, e2e only for client wiring).
- Anything user-visible through a package manager (status codes, headers,
  packument shape, tarball URLs, auth flows) is exercised by the e2e CLI
  matrix. Run `./scripts/e2e-cli-local.sh <pm>` after `pnpm build` when a
  change touches it.

## Code style

- TypeScript with `strict: true`. Packages build with Vite
  (`vite.lib.config.mjs`) to ESM and CJS; use `import.meta.dirname` and
  `import.meta.url`, never `__dirname`.
- Formatting is oxfmt (`.oxfmtrc.json`: single quotes, 100 columns, trailing
  commas, `@verdaccio/*` imports first). Linting is oxlint (`.oxlintrc.json`).
  The pre-commit hook formats and lints staged files and verifies the lockfile;
  keep it installed and never commit with `--no-verify`.
- Errors: build them with `errorUtils` from `@verdaccio/core`
  (`errorUtils.getBadRequest(API_ERROR.X)`, `getNotFound`, `getForbidden`,
  `getInternalError`, ...) and the `HTTP_STATUS` / `API_ERROR` constants, so the