AGENTS.md

1# AGENTS.md (pnpr)
2 
3Guidance for AI coding agents working in `pnpr/`.
4 
5**Read [`../AGENTS.md`](../AGENTS.md) first.** It covers the monorepo-wide
6conventions: GitHub PR workflow, signing agent-authored content, conventional
7commit messages, code-reuse philosophy, and "never ignore test failures."
8 
9## What this project is
10 
11`pnpr/` is a pnpm-compatible npm registry server written in Rust —
12roughly the role [verdaccio](https://verdaccio.org/) plays in the JS
13ecosystem. It is a **sibling** of `pnpm/`, not part of it.
14 
15The two Rust projects share the same Cargo workspace at the repo root so
16that the registry can depend directly on `pacquet-*` crates (tarball
17handling, integrity hashes, manifest parsing, network plumbing, etc.) and
18the `Cargo.lock` stays unified.
19 
20## Relationship to pacquet
21 
22- **`pnpm/`** is a *port* of the pnpm CLI. Its cardinal rule is
23  "match pnpm exactly" — see [`../pnpm/AGENTS.md`](../pnpm/AGENTS.md).
24- **`pnpr/`** has no pnpm-CLI counterpart to mirror. It is a new
25  server. Behavior here is designed, not ported.
26 
27That means the "match upstream pnpm" discipline that governs `pnpm/`
28does **not** apply here. The registry can pick its own architecture,
29flags, and config format. It must still be compatible with the npm
30registry protocol that pnpm (and npm, yarn, etc.) clients speak.
31 
32## Layout
33 
34Mirrors `pnpm/`:
35 
36```text
37pnpr/
38  AGENTS.md
39  crates/
40    pnpr/          -> package "pnpr"
41      Cargo.toml
42      README.md
43      src/
44        lib.rs              -> library API
45        main.rs             -> binary entry point (ships the `pnpr` binary)
46    # future sibling crates land here, see "New registry-only crates" below
47```
48 
49The Rust workspace itself, `rust-toolchain.toml`, `justfile`, and
50`Cargo.lock` live at the **repo root** — run `cargo` and `just` from there.
51`pnpr/crates/*` is wired into the root workspace `members`.
52 
53## Code reuse
54 
55**Prefer existing `pacquet-*` crates over writing new code.** Before
56implementing anything non-trivial, check whether `pacquet-*` already
57solves it. Candidates worth checking first: `pacquet-tarball`,
58`pacquet-crypto-hash`, `pacquet-crypto-shasums-file`,
59`pacquet-package-manifest`, `pacquet-network`, `pacquet-registry`,
60`pacquet-fs`, `pacquet-diagnostics`. Add a `pacquet-*` crate the same
61way pacquet crates do: declare it in the root `[workspace.dependencies]`
62(already done for the pacquet crates) and use `{ workspace = true }`
63in this crate's `Cargo.toml`.
64 
65If a piece of code currently inside `pnpm/` turns out to be genuinely
66shared between the two stacks and the `pacquet-` prefix becomes
67misleading, propose renaming/relocating it in a dedicated PR — not as a
68drive-by during feature work.
69 
70### New registry-only crates
71 
72When the registry needs its own crate (logic that isn't shared with the
73pnpm port and doesn't fit in `pnpm/`), put it under
74`pnpr/crates/<short-name>/` and name the package
75`pnpr-<short-name>` in its `Cargo.toml`. The
76`pnpr/crates/*` glob in the root workspace `members` picks it up
77automatically; just add the new crate to `[workspace.dependencies]` at
78the root with the `pnpr-` prefix so other crates can use
79`{ workspace = true }`.
80 
81Use the `pnpr-` prefix exclusively for registry-only crates.
82Don't reach for `pacquet-` to name something new on the registry side.
83 
84## Dependencies
85 
86Same rule as pacquet: a dependency that is already declared in
87`[workspace.dependencies]` may be used by any crate that needs it.
88Adding a new third-party crate to the workspace requires an explicit
89human request (see [`../pnpm/AGENTS.md`](../pnpm/AGENTS.md#things-not-to-do)).
90 
91## Style, tests, commits
92 
93Follow the pacquet code-style guide
94([`../pnpm/CODE_STYLE_GUIDE.md`](../pnpm/CODE_STYLE_GUIDE.md)) and the
95pacquet contributing guide ([`../pnpm/CONTRIBUTING.md`](../pnpm/CONTRIBUTING.md))
96for Rust-level conventions — imports, naming, ownership, error handling,
97test layout. They are written for pacquet but apply to any Rust code in
98this workspace.
99 
100### Comments
101 
102Follow the repo-wide comment baseline in [`../AGENTS.md`](../AGENTS.md#comments) and the Rust-specific additions in [`../pnpm/AGENTS.md`](../pnpm/AGENTS.md#comments).
103 
104Commit messages use Conventional Commits with `pnpr` as the scope
105(`feat(pnpr): ...`, `fix(pnpr): ...`).
106 
107Run the same checks pacquet does before declaring work done:
108 
109```sh
110just check     # cargo check --locked --workspace --all-targets
111just test      # cargo nextest run
112just lint      # cargo clippy --workspace --all-targets -- --deny warnings
113just fmt       # cargo fmt + taplo format
114```
115