@anizoptera/publish-clean 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +151 -216
  2. package/dist/cli.js +449 -294
  3. package/package.json +3 -8
package/README.md CHANGED
@@ -1,23 +1,21 @@
1
1
  # @anizoptera/publish-clean
2
2
 
3
- Publish npm packages with a consumer-only `package.json`. Refuses to ship a `.env`, a
4
- private key, or an unresolved workspace dependency.
3
+ Pre-publish npm package cleaner that strips common useless noise and crap from
4
+ `package.json`; prevents accidental publication of unwanted things and unresolved
5
+ dependencies. No deps, one JS file.
5
6
 
6
7
  [![npm version](https://img.shields.io/npm/v/@anizoptera/publish-clean?label=npm)](https://www.npmjs.com/package/@anizoptera/publish-clean)
7
8
  [![Signed provenance](https://img.shields.io/badge/provenance-signed-2ea44f?logo=npm&logoColor=white)](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
8
9
  [![CI](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml/badge.svg?branch=main)](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml)
9
- [![License](https://img.shields.io/github/license/Anizoptera/publish-clean)](LICENSE)
10
-
10
+ [![Node >=22.14](https://img.shields.io/badge/node-%3E%3D22.14-339933?logo=node.js&logoColor=white)](package.json)
11
11
  [![Runtime deps](https://img.shields.io/badge/runtime_deps-0-2ea44f)](package.json)
12
- [![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](package.json)
13
- [![pnpm pack + npm publish](https://img.shields.io/badge/pnpm_pack%20%2B%20npm_publish-f69220?logo=pnpm&logoColor=white)](https://pnpm.io/cli/pack)
14
- [![Bun checked](https://img.shields.io/badge/Bun-checked-000000?logo=bun&logoColor=white)](https://bun.sh/docs/cli/test)
12
+ [![License](https://img.shields.io/github/license/Anizoptera/publish-clean)](LICENSE)
15
13
 
16
14
  When you run `npm publish`, two things ship that you probably did not mean to ship.
17
15
 
18
- The first is your `package.json`. It is a development manifest. It lists devDependencies,
19
- config blocks for your test runner and linter and formatter, `packageManager`,
20
- `workspaces`, `pnpm` settings, release-tool settings, and every script you run locally.
16
+ The first is your `package.json`. It is a development manifest: devDependencies, config
17
+ blocks for your test runner, linter and formatter, `packageManager`, `workspaces`, `pnpm`
18
+ settings, release-tool settings, and every script you run locally.
21
19
  npm sends all of it, unchanged, to everyone who installs your package. In a pnpm
22
20
  workspace it can also send `workspace:*` and `catalog:` specs that were never resolved,
23
21
  and those break the install for every consumer.
@@ -27,20 +25,29 @@ tests, `.github/`, a lockfile. You do not see the tarball before it goes out, an
27
25
  version is published you cannot edit it. Unpublishing only works for a short window and
28
26
  under conditions npm decides.
29
27
 
30
- `publish-clean` packs the package, rewrites the manifest of the extracted copy down to
31
- what consumers actually use, packs that, and publishes the result. Your working tree is
32
- never modified. If the artifact still has something in it that should not ship, or
33
- declares a `main`, `exports`, or `bin` path that is not in the tarball, it fails instead
34
- of publishing.
28
+ `publish-clean` packs the package once, rewrites the `package.json` inside that tarball
29
+ down to what consumers actually use, checks the result, and publishes those exact bytes.
30
+ Your working tree is never modified. If the artifact still has something in it that should
31
+ not ship, or declares a `main`, `exports`, or `bin` path that is not in the tarball, it
32
+ fails instead of publishing.
35
33
 
36
- It uses pnpm to pack and npm to publish, and cleans the manifest in between. The
37
- reasoning behind that is in [Why it works this way](#why-it-works-this-way).
34
+ It packs with pnpm and publishes with npm, and cleans the manifest in between. Both
35
+ choices are argued, with measurements, in
36
+ [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
38
37
 
39
38
  ## Install
40
39
 
41
- ```bash
42
- pnpm add -D @anizoptera/publish-clean
43
- ```
40
+ | Project | Install | Run |
41
+ | ------- | --------------------------------------- | ------------------------- |
42
+ | pnpm | `pnpm add -D @anizoptera/publish-clean` | `pnpm exec publish-clean` |
43
+ | Bun | `bun add -d @anizoptera/publish-clean` | `bunx publish-clean` |
44
+ | npm | `npm i -D @anizoptera/publish-clean` | `npm exec publish-clean` |
45
+ | Yarn | `yarn add -D @anizoptera/publish-clean` | `yarn publish-clean` |
46
+
47
+ **Whatever you start it with, `pnpm` prepares the package and `npm` uploads it, so both
48
+ must be on `PATH`.** A Bun, npm or Yarn project needs pnpm installed too, including in CI.
49
+
50
+ Also needs `tar` and Node.js 22.14+. Below 22.14 npm cannot mint provenance.
44
51
 
45
52
  That installs one package and nothing else. `publish-clean` has zero runtime
46
53
  dependencies: it is a single file that talks to `pnpm`, `npm` and `tar` through the
@@ -48,29 +55,20 @@ tools you already have. For something that sits on your publish path and handles
48
55
  registry credentials, that matters. A publishing tool with a dependency tree is a
49
56
  supply-chain risk of its own, and this one has no transitive code to audit.
50
57
 
51
- Needs Node.js 20+, and `pnpm`, `npm` and `tar` on `PATH`.
52
-
53
- `--provenance` also needs Node.js 22.14+, npm 11.5.1+, and a cloud CI runner. npm will
54
- not sign a publish that came from your laptop.
58
+ `--provenance` additionally needs npm 11.5.1+ and a cloud CI runner. npm will not sign a
59
+ publish that came from your laptop.
55
60
 
56
61
  ## Package managers
57
62
 
58
- Start `publish-clean` with any package manager and it still packs with `pnpm` and
59
- publishes with `npm`. So both have to be installed even if your project uses neither. The
60
- reasons are in [Why it works this way](#why-it-works-this-way).
61
-
62
- | Your project | How to run it | What to expect |
63
- | ------------ | ------------------------- | --------------------------------------------------------- |
64
- | pnpm | `pnpm exec publish-clean` | Everything works, no warning. |
65
- | npm | `npm exec publish-clean` | Works. Prints an advisory that packing goes through pnpm. |
66
- | Yarn | `yarn publish-clean` | Same as npm. |
67
- | Bun | `bunx publish-clean` | Same as npm. |
63
+ Why pnpm packs and npm publishes: pnpm is the only packer that resolves every workspace
64
+ layout correctly, and npm is the only client that can sign a release. The measurements are
65
+ in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
68
66
 
69
- The advisory is a warning on stderr, not an error. Nothing behaves differently because of
70
- it and there's no flag to silence it. Worth seeing once if the rest of your pipeline runs
71
- on something other than pnpm.
67
+ Started with anything other than pnpm, it prints an advisory on stderr saying so. That is
68
+ a warning, not an error. Nothing behaves differently because of it, and there is no flag
69
+ to silence it.
72
70
 
73
- For a single package all four behave the same, since nothing in the manifest needs
71
+ For a single package every manager behaves the same, since nothing in the manifest needs
74
72
  resolving before it ships.
75
73
 
76
74
  Monorepos are where it matters. `pnpm pack` resolves `workspace:` and `catalog:` specs by
@@ -159,8 +157,8 @@ publishes its own tarball, so you get the checks and not the cleaned manifest.
159
157
  pnpm exec publish-clean --dry-run
160
158
  ```
161
159
 
162
- Prints the paths of the cleaned package and the exact tarball that would be uploaded, and
163
- leaves both on disk. Run `tar tzf` on the tarball and read the rewritten `package.json`.
160
+ Prints every file that would ship and the cleaned `package.json`, then deletes its temp
161
+ tree. Add `--tarball-out DIR` to keep the tarball itself.
164
162
 
165
163
  ### Publishing a restricted package
166
164
 
@@ -181,164 +179,109 @@ publish-clean packages/my-lib -- --access public --tag next
181
179
 
182
180
  ```mermaid
183
181
  flowchart TD
184
- A[Your package directory] -->|pnpm pack| B[Tarball 1 - pnpm decides the file set]
185
- B --> C[Extract into a temp directory]
186
- C --> D{No leaked files?}
187
- D --> E[Rewrite package.json for consumers]
188
- E --> F{Every declared main/exports/bin/types path exists?}
189
- F -->|npm pack --ignore-scripts| G[Tarball 2 - the bytes that ship]
190
- G --> H{Same files, same manifest, still no leaks?}
191
- H --> I[npm publish tarball 2]
182
+ A[Your package directory] -->|pnpm pack| B[Tarball, file set chosen by pnpm]
183
+ B --> C[Copy it, rewriting only the package.json inside]
184
+ C --> D[Final tarball]
185
+ D --> E{Checks, all reading this tarball}
186
+ E -->|any fails| F[Exit non-zero, publish nothing]
187
+ E -->|all pass| G[npm publish this same tarball]
192
188
  ```
193
189
 
194
- Any gate that fails exits non-zero and nothing is published. `--dry-run` and
195
- `--guard-only` run the whole pipeline and stop before the publish.
196
-
197
- ## Why it works this way
198
-
199
- ### Why pnpm does the packing
200
-
201
- Not for file selection. pnpm, npm and Bun pick the same files: same `files` field, same
202
- `.npmignore`, same packlist defaults. There are no file rules of this tool's own either,
203
- so that part behaves however your package manager already behaves.
190
+ The checks are listed under [What it checks](#what-it-checks). The point of the shape is
191
+ that they all read the tarball that gets uploaded, so what passed the checks and what
192
+ reached the registry are the same bytes, not two things that ought to match.
204
193
 
205
- Workspaces are the reason. A dependency written as `"@acme/utils": "workspace:*"` means
206
- "whatever version of that package is in this repo right now". It has to become a real
207
- version range before it ships, because to a stranger installing from the registry
208
- `workspace:*` means nothing.
194
+ `--dry-run` and `--guard-only` run the whole pipeline and stop before the publish.
209
195
 
210
- npm never adopted the protocol. It won't even install it:
211
-
212
- ```
213
- npm error code EUNSUPPORTEDPROTOCOL
214
- npm error Unsupported URL Type "workspace:": workspace:*
215
- ```
216
-
217
- `npm pack` on that same package exits 0 and writes `workspace:*` straight into the
218
- tarball. It neither resolves it nor refuses it, and silently publishing something you
219
- can't install is the one behaviour a release tool can't be built on.
220
-
221
- pnpm and Bun both resolve it, and both stop loudly when they can't. Their output matches
222
- down to `workspace:^` and `workspace:~` in `peerDependencies` and `optionalDependencies`,
223
- and `catalog:` entries too. On correctness there is nothing to choose between them.
224
-
225
- ### Why pnpm rather than Bun
226
-
227
- They resolve from different places, and that decides it.
228
-
229
- pnpm looks for the dependency in the packing package's own `node_modules` and resolves it
230
- from there. It never asks who put it there, so a Bun workspace, which gives every package
231
- its own `node_modules`, packs as readily as pnpm's own. Yarn hoists to the root instead
232
- and needs the one-time setup above.
233
-
234
- Bun reads `bun.lock`. It resolves the workspaces Bun installed and refuses the others:
235
-
236
- ```
237
- error: Failed to resolve workspace version for "@acme/utils" in `dependencies`.
238
- Run `bun install` and try again.
239
- ```
240
-
241
- That message is accurate and useless, because in a pnpm repo `bun install` is not
242
- something you want to be told to run. A tool that executes in other people's
243
- repositories has to cope with the repository it finds, so it packs with the one that
244
- reads all of them.
245
-
246
- There's a correctness gap too, and it's the quiet kind. An aliased workspace dependency,
247
- `"utils": "workspace:@acme/utils@*"`, has to come out the other side as an npm alias.
248
- pnpm writes `"npm:@acme/utils@1.2.3"`. Bun 1.3.14 writes `"@acme/utils@*"`: the `npm:`
249
- prefix is dropped and the range was never resolved. npm won't take it.
250
-
251
- ```
252
- npm error code EINVALIDTAGNAME
253
- npm error Invalid tag name "is-odd@3.0.1" of package "aliased@is-odd@3.0.1"
254
- ```
196
+ ## Why it works this way
255
197
 
256
- `bun pm pack` exits 0 either way, so nothing tells you until someone tries to install the
257
- release.
198
+ ### Why pnpm packs, and npm publishes
258
199
 
259
- One silent way to publish a broken manifest is one too many for the step you can't take
260
- back.
200
+ pnpm because of workspaces. A dependency written `"@acme/utils": "workspace:*"` has to
201
+ become a real version range before it ships, and pnpm is the only packer that does that
202
+ for every layout it might find, including a Bun one. npm writes `workspace:*` into the
203
+ tarball unchanged and exits 0, publishing a package nobody can install. Bun resolves only
204
+ what Bun installed, and quietly mangles an aliased workspace dependency.
261
205
 
262
- pnpm also applies `publishConfig` field overrides. If your manifest points `main`, `types`
263
- and `exports` at source for local development and overrides them to `dist` for publishing,
264
- pnpm swaps them on the way out and drops `publishConfig` itself. npm and Bun both ignore
265
- those overrides and publish the development paths. That one is a pnpm extension rather
266
- than a bug in the other two, but the effect on the release is the same.
206
+ npm because of provenance. The signed attestation behind the "Built and signed on GitHub
207
+ Actions" badge is minted by the npm CLI talking to Sigstore, and trusted publishing, which
208
+ removes the long-lived token entirely, is npm's own exchange with the registry. No other
209
+ client does either one. `npm publish` also takes a tarball directly, which is what the
210
+ packing step already produced.
267
211
 
268
- Everything else we compared came out identical: file modes including the executable bit on
269
- `bin`, negated `files` patterns, dropped symlinks, prerelease versions, pinned
270
- `workspace:1.2.3` ranges, named catalogs, and refusing a catalog entry that doesn't exist.
212
+ The measurements behind both choices, and the one thing packing with pnpm costs you, are
213
+ in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
271
214
 
272
215
  ### Why the manifest is cleaned on a copy
273
216
 
274
- The tarball gets extracted into a temp directory and rewritten there. Your working tree
275
- is never touched.
217
+ The manifest is read out of the packed tarball and written back into a copy of it, in a
218
+ temp directory. Your working tree is never touched.
276
219
 
277
220
  The obvious alternative is what a lot of hand-rolled release scripts do: edit
278
221
  `package.json`, publish, edit it back. That's fine until something dies in the middle,
279
222
  and then your repo is sitting on a manifest nobody meant to keep. It also can't be run
280
223
  twice at once. Cleaning a copy has neither problem and costs a directory in `/tmp`.
281
224
 
282
- ### Why npm packs the cleaned copy a second time
225
+ ### Why the tarball is edited instead of packed again
283
226
 
284
227
  Give npm a directory and it packs during the upload, so the bytes that reach the registry
285
- only come into existence after the last check has run.
286
-
287
- Packing first means they exist before anything is uploaded. They can be listed, compared
288
- against the cleaned directory, scanned for leaks again, kept with `--tarball-out` for a
289
- build attestation, and then published as themselves. What you inspect is what ships. If
290
- cleaning ever dropped a real file, you find out here instead of from a bug report.
291
-
292
- The second pack uses `--ignore-scripts`. The first one doesn't, deliberately: `pnpm pack`
293
- runs your `prepare` and `prepack` scripts, which is how your build output gets into the
294
- package at all. Running them again on the cleaned copy could only change it after it was
295
- checked.
296
-
297
- ### Why npm does the publishing
298
-
299
- Provenance is an npm feature. The signed attestation behind the "Built and signed on
300
- GitHub Actions" badge is minted by the npm CLI talking to Sigstore, and trusted
301
- publishing, which removes the long-lived token entirely, is npm's own OIDC exchange with
302
- the registry.
303
-
304
- No other client mints it. `bun publish` offers `--access`, `--tag`, `--otp` and
305
- `--auth-type`, and nothing at all for provenance or attestation, so publishing through it
306
- would cost both the badge and the tokenless path. That trade isn't on the table here:
307
- verifiable provenance is why this package exists.
308
-
309
- `npm publish` also takes a tarball directly, which is exactly what the previous step
310
- produced.
228
+ only come into existence after the last check has run. Packing first means they exist
229
+ before anything is uploaded: they can be listed, scanned for leaks, kept with
230
+ `--tarball-out` for a build attestation, and then published as themselves. What you
231
+ inspect is what ships.
232
+
233
+ So the manifest has to be cleaned inside a tarball that already exists. The obvious way is
234
+ to unpack, edit, and pack again — and it is wrong. `files` is a packing instruction, and
235
+ cleaning removes it, because it is useless to anyone installing the package. A second pack
236
+ then has nothing left to select with, falls back to your `.gitignore`/`.npmignore` for
237
+ exclusion, and quietly drops files the first pack included. A package shipping a
238
+ `.gitignore` that excludes any other shipped file loses it.
239
+
240
+ Editing avoids the question. Only the `package/package.json` member is replaced. Every
241
+ other entry is copied without being decoded, so the file set stays exactly what pnpm chose,
242
+ and entry shapes this tool does not model (pax headers for long paths, prefix splitting)
243
+ pass through untouched. It also keeps pnpm's normalised metadata: owner `0:0`, a fixed
244
+ timestamp, mode 644. A plain `tar` invocation would replace those with whatever the build
245
+ machine happens to have.
246
+
247
+ Lifecycle scripts run once, at the first pack. `pnpm pack` runs your `prepare` and
248
+ `prepack`, which is how build output reaches the package at all. Nothing runs afterwards:
249
+ npm skips `prepack`/`postpack` when it is handed a tarball rather than a directory, so
250
+ nothing can alter the artifact after it was checked.
311
251
 
312
252
  ## What it checks
313
253
 
314
- `publish-clean` refuses to continue when:
315
-
316
- - the package is `private: true`
317
- - the source package has uncommitted changes, unless disabled
318
- - the package has no non-empty `files` array, unless disabled
319
- - the tarball contains critical leaks like `.env`, `.npmrc`, `.git`,
320
- `node_modules`, or private-key files
321
- - dependency specs still use `catalog:`, `workspace:`, `link:`, or `portal:`
322
- - declared export, type, import, browser, bin, or side-effect paths are missing
323
- from the cleaned package
324
- - the final npm tarball drops files that were present in the cleaned package
325
- - trusted GitHub publication uses `--provenance` but package repository metadata
326
- does not match the workflow repository
327
-
328
- It warns, without stopping, when it was started by npm, Yarn or Bun rather than pnpm.
329
- The packing still goes through pnpm, but the warning is there because the rest of your
330
- release probably should too.
331
-
332
- Leak checks cannot be turned off by any flag or config key.
254
+ `publish-clean` stops, and publishes nothing, when:
255
+
256
+ - the package is marked `private: true`
257
+ - the working tree has uncommitted changes (`--no-git-checks` to allow it)
258
+ - the package has no non-empty `files` array (`--skip-file-check` to allow it)
259
+ - the tarball holds something that should never ship: a `.env`, an `.npmrc`, `.git`,
260
+ `node_modules`, or a private key. This one has no off switch, by any flag or config key
261
+ - a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, which
262
+ nobody outside your repo can install
263
+ - the manifest points `exports`, `types`, `main`, `browser`, `bin` or `sideEffects` at a
264
+ path that is not in the tarball
265
+ - rewriting the manifest changed anything else in the tarball
266
+ - you asked for `--provenance` from GitHub Actions, but the `repository` in your manifest
267
+ is not the repository the workflow is running in
268
+
269
+ It warns, without stopping, when it was started by npm, Yarn or Bun rather than pnpm. The
270
+ packing still goes through pnpm, but the warning is there because the rest of your release
271
+ probably should too.
333
272
 
334
273
  ## What the cleaned manifest keeps
335
274
 
336
275
  Everything a consumer or a registry reads survives: `name`, `version`, `license`,
337
276
  `dependencies`, `peerDependencies` and their meta, `exports`, `main`, `module`, `types`,
338
- `bin`, `files`, `engines`, `os`, `cpu`, `sideEffects`, `publishConfig`, and the rest of
339
- the public surface.
277
+ `bin`, `engines`, `os`, `cpu`, `sideEffects`, `publishConfig`, and the rest of the public
278
+ surface.
340
279
 
341
- What goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
280
+ `files` goes, because it is spent: it told the packer what to include, the tarball already
281
+ exists, nothing re-selects afterwards, and an install extracts every entry unfiltered. npm
282
+ agrees — its registry drops the field from the metadata it serves.
283
+
284
+ What else goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
342
285
  `resolutions`, and the config blocks belonging to test runners, linters, formatters,
343
286
  coverage tools, build systems and release tools. Scripts go too, apart from the install
344
287
  lifecycle ones a consumer actually runs: `preinstall`, `install`, `postinstall`,
@@ -362,34 +305,14 @@ hear about it from a stranger's broken build rather than from your own release.
362
305
  Add your own with `devFields`. Better still, run `--dry-run` and read the manifest that
363
306
  would ship instead of trusting this list.
364
307
 
365
- ## Options
308
+ ## Options and config
366
309
 
367
310
  ```bash
368
311
  publish-clean [options] [package-dir] [-- npm-publish-args]
369
312
  ```
370
313
 
371
- - `--dry-run`: pack, check, clean, and print the cleaned package and final
372
- tarball paths.
373
- - `--guard-only`: run the full pack, clean, and final-tarball guard without
374
- publishing.
375
- - `--registry URL`: set `publishConfig.registry` on the cleaned manifest.
376
- - `--skip-file-check`: skip suspicious-file checks and the required `files`
377
- array check. Critical leak checks still run.
378
- - `--no-git-checks`: skip the source git cleanliness check.
379
- - `--tarball-out DIR`: copy the final tarball into `DIR` before publishing. The bytes
380
- kept are the ones that were published, so a release pipeline can attach them to a
381
- GitHub Release or sign them with build-provenance attestation.
382
- - `-h`, `--help`: print usage.
383
-
384
- Arguments after `--` go to `npm publish`, which publishes the final cleaned
385
- tarball.
386
-
387
- Pass the npm dist-tag explicitly. For normal public releases, use
388
- `--tag latest`.
389
-
390
- ## Package config
391
-
392
- Stable project defaults can live in `package.json`:
314
+ Most settings can be a flag or a `package.json` key. Flags win, so keep per-release
315
+ choices like dist-tags on the command line and stable project policy in the manifest:
393
316
 
394
317
  ```json
395
318
  {
@@ -403,35 +326,49 @@ Stable project defaults can live in `package.json`:
403
326
  }
404
327
  ```
405
328
 
406
- `registry` is written as `publishConfig.registry` on the cleaned manifest and passed to
407
- `npm publish`, so the package cannot end up on whatever registry the machine happens to
408
- be pointed at.
329
+ | Flag | `package.json` | What it does |
330
+ | ------------------- | --------------- | ------------------------------------------------------------------------------------------ |
331
+ | `--dry-run` | - | Run everything up to the publish, then print the file list and the cleaned `package.json`. |
332
+ | `--guard-only` | - | Run everything up to the publish and exit, printing nothing. |
333
+ | `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
334
+ | `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
335
+ | `--skip-file-check` | `skipFileCheck` | Drop the suspicious-file check and the required `files` array. |
336
+ | `--no-git-checks` | `noGitChecks` | Allow publishing from a dirty working tree. |
337
+ | - | `devFields` | Extra manifest fields to strip. |
338
+ | - | `keepFields` | Fields that belong in the published package, so stop reporting them. |
339
+ | `-h`, `--help` | - | Print usage. |
340
+
341
+ Arguments after `--` go to `npm publish`. Pass the dist-tag explicitly: `--tag latest` for
342
+ a normal public release.
409
343
 
410
- `skipFileCheck` drops the suspicious-file check and the requirement for a `files` array.
411
- Leak checks keep running; those cannot be turned off.
344
+ A few of these deserve a sentence more.
412
345
 
413
- `noGitChecks` allows publishing from a dirty working tree. You need it when you publish
414
- from a build directory or a checkout that is not a git repository.
346
+ `--tarball-out` keeps the bytes that were published, so a release pipeline can attach them
347
+ to a GitHub Release or sign them with build-provenance attestation. The copy happens in
348
+ every mode, before the publish, so you get the validated artifact even if the upload fails.
415
349
 
416
- `devFields` lists extra manifest fields to strip, for tooling this package has not heard
417
- of. Fields that npm or your consumers actually use, like `exports`, `bin`, `engines` and
418
- the dependency maps, are rejected here, so a typo cannot quietly break your package.
350
+ `registry` pins where the package goes, so it cannot end up on whatever registry the
351
+ machine happens to be pointed at.
419
352
 
420
- `keepFields` is the other answer to the same report: the field belongs in the published
421
- package, stop mentioning it. A VS Code extension needs `contributes` and `publisher` in
422
- the artifact to work, and no generic publishing tool is ever going to know that.
353
+ `skipFileCheck` does not touch the leak checks.
423
354
 
424
- Command-line flags override this block. Keep per-release choices such as dist-tags on the
425
- command line.
355
+ `noGitChecks` is what you need when you publish from a build directory, or from a checkout
356
+ that is not a git repository at all.
357
+
358
+ `devFields` refuses fields that npm or your consumers actually read, like `exports`, `bin`,
359
+ `engines` and the dependency maps, so a typo cannot quietly break your package.
360
+
361
+ `keepFields` answers the unrecognised-field report the other way: the field belongs in the
362
+ published package, stop mentioning it. A VS Code extension needs `contributes` and
363
+ `publisher` in the artifact to work, and no generic publishing tool is ever going to know
364
+ that.
426
365
 
427
366
  ## What it does not do
428
367
 
429
368
  It isn't a release manager. It won't pick your version number, write a changelog, tag
430
- anything, push a commit, create a GitHub release, or set up trusted publishing for you.
431
- It also doesn't check that your entry points resolve correctly for consumers, which is
432
- what `publint` and `@arethetypeswrong/cli` are for.
433
-
434
- Pick a release manager and a validator to go with it. The next section covers which.
369
+ anything, push a commit, create a GitHub release, or set up trusted publishing for you. It
370
+ also doesn't check that your entry points resolve correctly for consumers. Pair it with a
371
+ release manager and a validator; the next section names them.
435
372
 
436
373
  It can't publish a package that uses `bundleDependencies`. pnpm links dependencies rather
437
374
  than copying them, so it has nothing to bundle and refuses:
@@ -442,9 +379,7 @@ Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
442
379
 
443
380
  Doing what it says makes the package publishable again. This is the one thing you give up
444
381
  by packing with pnpm, and it's a fair trade: `bundleDependencies` is rare, and the failure
445
- is loud and tells you the fix. npm and Bun bundle correctly for a standalone package, and
446
- neither bundles anything for a package inside a workspace, because the dependency hoists
447
- to the workspace root where the package can't see it.
382
+ is loud and tells you the fix.
448
383
 
449
384
  ## How it compares
450
385