@anizoptera/publish-clean 0.7.3 → 0.9.1

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 +166 -231
  2. package/dist/cli.js +617 -372
  3. package/package.json +4 -2
package/README.md CHANGED
@@ -1,8 +1,7 @@
1
1
  # @anizoptera/publish-clean
2
2
 
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.
3
+ Publish npm packages with a clean `package.json` and checks for unwanted files,
4
+ unresolved workspace dependencies and missing entry points.
6
5
 
7
6
  [![npm version](https://img.shields.io/npm/v/@anizoptera/publish-clean?label=npm)](https://www.npmjs.com/package/@anizoptera/publish-clean)
8
7
  [![Signed provenance](https://img.shields.io/badge/provenance-signed-2ea44f?logo=npm&logoColor=white)](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
@@ -11,29 +10,23 @@ dependencies. No deps, one JS file.
11
10
  [![Runtime deps](https://img.shields.io/badge/runtime_deps-0-2ea44f)](package.json)
12
11
  [![License](https://img.shields.io/github/license/Anizoptera/publish-clean)](LICENSE)
13
12
 
14
- When you run `npm publish`, two things ship that you probably did not mean to ship.
13
+ `publish-clean` removes `devDependencies`, workspace settings and tool config from the
14
+ published manifest. Consumer fields and lifecycle helpers stay. Unknown fields are
15
+ reported for review and kept unless you choose to remove them.
15
16
 
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.
19
- npm sends all of it, unchanged, to everyone who installs your package. In a pnpm
20
- workspace it can also send `workspace:*` and `catalog:` specs that were never resolved,
21
- and those break the install for every consumer.
17
+ It packs once with pnpm, cleans the manifest inside the tarball, checks that file, then
18
+ uploads it with npm. The checked bytes are the published bytes. Cleaning leaves your
19
+ source files alone; your pack hooks still run and can change them.
22
20
 
23
- The second is files. A `.env`, an `.npmrc` with a token in it, a stray `.pem`, your
24
- tests, `.github/`, a lockfile. You do not see the tarball before it goes out, and once a
25
- version is published you cannot edit it. Unpublishing only works for a short window and
26
- under conditions npm decides.
21
+ Preview, then publish:
27
22
 
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.
23
+ ```sh
24
+ pnpm exec publish-clean --dry-run
25
+ pnpm exec publish-clean -- --access public --tag latest --provenance
26
+ ```
33
27
 
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).
28
+ Requires Node.js 22+, pnpm and npm. The CLI has no runtime dependencies. The publish
29
+ command above needs [CI provenance setup](#publishing-a-public-package-from-ci).
37
30
 
38
31
  ## Install
39
32
 
@@ -44,60 +37,40 @@ choices are argued, with measurements, in
44
37
  | npm | `npm i -D @anizoptera/publish-clean` | `npm exec publish-clean` |
45
38
  | Yarn | `yarn add -D @anizoptera/publish-clean` | `yarn publish-clean` |
46
39
 
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
- Node.js 22+ runs it. npm provenance additionally needs 22.14+, because below that npm
51
- cannot mint it.
40
+ Both `pnpm` and `npm` must be on `PATH`, including in Bun, npm and Yarn projects and CI.
41
+ The CLI is one JavaScript file with no runtime dependencies. pnpm and npm are separate
42
+ requirements, not bundled dependencies.
52
43
 
53
- That installs one package and nothing else. `publish-clean` has zero runtime
54
- dependencies: it is a single file that talks to `pnpm` and `npm`, and reads and rewrites
55
- the tarball itself, so there is nothing else to have on the machine.
44
+ For trusted publishing, use Node.js 22.14+ and npm 11.5.1+. Provenance requires a public
45
+ package, a public source repository and a supported CI provider. See
46
+ [npm's requirements](https://docs.npmjs.com/trusted-publishers/).
56
47
 
57
- For something that sits on your publish path and handles your
58
- registry credentials, that matters. A publishing tool with a dependency tree is a
59
- supply-chain risk of its own, and this one has no transitive code to audit.
48
+ ### Running it under Bun
60
49
 
61
- `--provenance` additionally needs npm 11.5.1+ and a cloud CI runner. npm will not sign a
62
- publish that came from your laptop.
63
-
64
- ### Running it under Bun packs a smaller tarball
65
-
66
- gzip encoding belongs to whichever runtime executes the CLI, and Bun's (libdeflate) beats
67
- Node's zlib on tar-shaped data: 0.17% smaller for this package, 0.28% for a sibling one, with
68
- a byte-identical archive inside. To get it, pass Bun the **file path**:
50
+ gzip bytes depend on the runtime and version executing the CLI. To run it under Bun,
51
+ pass Bun the **file path**:
69
52
 
70
53
  ```sh
71
54
  bun ./node_modules/.bin/publish-clean
72
55
  ```
73
56
 
74
- Naming the bin instead does not work, and does not say so: `bun publish-clean`,
75
- `bun run publish-clean` and `bunx publish-clean` all hand the file to the OS, which honours
76
- its `#!/usr/bin/env node` shebang and runs Node. They succeed, and you get Node's bytes.
57
+ The installed command has a Node shebang. Passing the file directly avoids relying on
58
+ how a package runner selects an interpreter or changes the child tools' environment.
77
59
 
78
- Not `bunx --bun`, which forces Bun onto the `pnpm` this tool spawns as well; pnpm 11 needs
79
- `node:sqlite`, which Bun does not implement, and that is the error you get.
80
-
81
- Either runtime produces valid gzip with identical contents, so the choice is free. The one
82
- rule is not to switch runtimes _within_ a version: if a release is re-run to repair its
83
- artifacts, the bytes have to come out the same, and the two encoders do not agree.
60
+ Keep the runtime and its version fixed when rebuilding a release artifact. Node and
61
+ Bun can encode the same archive contents into different gzip bytes, which changes the
62
+ artifact's hash.
84
63
 
85
64
  ## Package managers
86
65
 
87
- Why pnpm packs and npm publishes: pnpm is the only packer that resolves every workspace
88
- layout correctly, and npm is the only client that can sign a release. The measurements are
89
- in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
90
-
91
- Started with anything other than pnpm, it prints an advisory on stderr saying so. That is
92
- a warning, not an error. Nothing behaves differently because of it, and there is no flag
93
- to silence it.
66
+ The CLI uses pnpm for workspace resolution and `publishConfig` overrides, and npm to upload the
67
+ checked tarball. The [packer comparison](docs/why-pnpm-and-npm.md) explains the trade-offs.
94
68
 
95
- For a single package every manager behaves the same, since nothing in the manifest needs
96
- resolving before it ships.
69
+ Starting through another package manager prints an advisory on stderr. It does not change
70
+ the packer or stop publication, and there is no option to suppress it.
97
71
 
98
- Monorepos are where it matters. `pnpm pack` resolves `workspace:` and `catalog:` specs by
99
- finding the dependency inside the packing package's own `node_modules`. What decides
100
- whether that works is the layout your installer left behind, not which installer it was.
72
+ For `workspace:` and `catalog:` specs, pnpm needs the installed dependency in the packing
73
+ package's own `node_modules`. Compatibility depends on your install layout.
101
74
 
102
75
  Bun gives each package its own `node_modules`, so a Bun workspace packs as it stands: no
103
76
  `pnpm-workspace.yaml`, no switching package managers. Yarn hoists workspace dependencies
@@ -106,32 +79,32 @@ all. Both need a `pnpm-workspace.yaml` and one `pnpm install` before packing wor
106
79
  package with no `workspace:` or `catalog:` specs needs neither, because there's nothing to
107
80
  resolve.
108
81
 
109
- Either way the workspace has to be installed. Pack one nobody has installed and it stops
110
- on pnpm's own error:
82
+ Install the workspace before packing. An unresolved workspace dependency stops packing:
111
83
 
112
84
  ```
113
85
  ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL
114
86
  ```
115
87
 
116
- Which is what you want. Nothing gets published, and a manifest that would have been
117
- uninstallable for everyone never reaches the registry. Run your usual install and pack
118
- again.
88
+ Install with the layout described above, then retry.
119
89
 
120
90
  ## Pick your setup
121
91
 
122
92
  ### Publishing a public package from CI
123
93
 
124
- The common case. `id-token: write` is what lets npm sign the release. Once trusted
125
- publishing is configured for the package, no npm token is involved at all.
94
+ Configure an npm trusted publisher for your repository and workflow filename, with
95
+ permission for direct `npm publish`. In the publish job, grant `id-token: write` so npm
96
+ can authenticate through GitHub OIDC without an npm token. Run tests in a separate job
97
+ and make the publish job depend on their success.
126
98
 
127
99
  ```yaml
128
- # .github/workflows/release.yml
100
+ # Inside the publish job, after its required check jobs have passed:
129
101
  permissions:
130
102
  contents: read
131
103
  id-token: write
132
104
  steps:
133
105
  - uses: actions/checkout@v7
134
106
  - uses: pnpm/action-setup@v6
107
+ # Set packageManager in package.json to select your pnpm version.
135
108
  - uses: actions/setup-node@v7
136
109
  with:
137
110
  node-version: "24"
@@ -141,13 +114,13 @@ steps:
141
114
  - run: pnpm exec publish-clean -- --access public --tag latest --provenance
142
115
  ```
143
116
 
144
- Always pass the dist-tag. npm defaults to `latest`, which is wrong for a prerelease and
145
- easy to forget.
117
+ Use `--tag latest` for stable releases and `--tag next` for prereleases. npm defaults
118
+ to `latest`, so omitting the tag can give ordinary installs a prerelease.
146
119
 
147
- Publishing a package name for the first time cannot use trusted publishing at all. That
148
- case has its own page: [docs/first-publish.md](docs/first-publish.md).
120
+ For a new package name, follow the [first-publish setup](docs/first-publish.md).
149
121
 
150
- To stop a stray `npm publish` from bypassing all of this:
122
+ To block direct publication from your source directory, add this hook. Publishing a
123
+ tarball does not run it:
151
124
 
152
125
  ```json
153
126
  {
@@ -159,8 +132,8 @@ To stop a stray `npm publish` from bypassing all of this:
159
132
 
160
133
  ### Keeping your existing release tool
161
134
 
162
- If Changesets, semantic-release, release-it or np already owns your releases, use
163
- `publish-clean` as a check rather than replacing the publish:
135
+ If your release tool supports a custom upload command, use `publish-clean` there.
136
+ For a preview check only, add:
164
137
 
165
138
  ```json
166
139
  {
@@ -170,10 +143,10 @@ If Changesets, semantic-release, release-it or np already owns your releases, us
170
143
  }
171
144
  ```
172
145
 
173
- It packs, cleans and validates, then exits without publishing. A leaked file, an
174
- unresolved `workspace:` spec or a `main` path that is missing from the tarball fails the
175
- release before your tool uploads anything. The limit is real though: your tool still
176
- publishes its own tarball, so you get the checks and not the cleaned manifest.
146
+ It checks a pnpm-produced preview and exits without publishing. Your release tool still
147
+ creates and uploads its own artifact, which may differ: this gate does not validate those
148
+ uploaded bytes or clean their manifest. To publish the checked bytes, configure that tool
149
+ to invoke `publish-clean` for the upload instead.
177
150
 
178
151
  ### Looking at what would be published
179
152
 
@@ -181,8 +154,8 @@ publishes its own tarball, so you get the checks and not the cleaned manifest.
181
154
  pnpm exec publish-clean --dry-run
182
155
  ```
183
156
 
184
- Prints every file that would ship and the cleaned `package.json`, then deletes its temp
185
- tree. Add `--tarball-out DIR` to keep the tarball itself.
157
+ Prints the checked file list and cleaned `package.json`. Add `--tarball-out DIR` to keep
158
+ the tarball; otherwise temporary files are removed.
186
159
 
187
160
  ### Publishing a restricted package
188
161
 
@@ -190,8 +163,8 @@ tree. Add `--tarball-out DIR` to keep the tarball itself.
190
163
  publish-clean -- --access restricted --tag latest
191
164
  ```
192
165
 
193
- No provenance here, because npm only signs public packages. Do not set `private: true`
194
- either. npm treats it as a publish block, and `publish-clean` refuses it too.
166
+ Omit provenance for restricted packages. Leave `private: true` unset: it prohibits
167
+ publication, even to a private registry.
195
168
 
196
169
  ### Publishing one package out of a monorepo
197
170
 
@@ -204,133 +177,89 @@ publish-clean packages/my-lib -- --access public --tag next
204
177
  ```mermaid
205
178
  flowchart TD
206
179
  A[Your package directory] -->|pnpm pack| B[Tarball, file set chosen by pnpm]
207
- B --> C[Copy it, rewriting only the package.json inside]
180
+ B --> C[Rewrite only package.json inside]
208
181
  C --> D[Final tarball]
209
182
  D --> E{Checks, all reading this tarball}
210
183
  E -->|any fails| F[Exit non-zero, publish nothing]
211
184
  E -->|all pass| G[npm publish this same tarball]
212
185
  ```
213
186
 
214
- The checks are listed under [What it checks](#what-it-checks). The point of the shape is
215
- that they all read the tarball that gets uploaded, so what passed the checks and what
216
- reached the registry are the same bytes, not two things that ought to match.
217
-
218
- `--dry-run` and `--guard-only` run the whole pipeline and stop before the publish.
187
+ `--dry-run` and `--guard-only` validate the artifact, but skip publication preflight.
188
+ Neither proves that registry access, credentials, provenance requirements or repository
189
+ identity are correct. Pack hooks still run, including any network operations they perform.
219
190
 
220
191
  ## Why it works this way
221
192
 
222
- ### Why pnpm packs, and npm publishes
223
-
224
- pnpm because of workspaces. A dependency written `"@acme/utils": "workspace:*"` has to
225
- become a real version range before it ships, and pnpm is the only packer that does that
226
- for every layout it might find, including a Bun one. npm writes `workspace:*` into the
227
- tarball unchanged and exits 0, publishing a package nobody can install. Bun resolves only
228
- what Bun installed, and quietly mangles an aliased workspace dependency.
229
-
230
- npm because of provenance. The signed attestation behind the "Built and signed on GitHub
231
- Actions" badge is minted by the npm CLI talking to Sigstore, and trusted publishing, which
232
- removes the long-lived token entirely, is npm's own exchange with the registry. No other
233
- client does either one. `npm publish` also takes a tarball directly, which is what the
234
- packing step already produced.
235
-
236
- The measurements behind both choices, and the one thing packing with pnpm costs you, are
237
- in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
193
+ ### Why cleaning happens in the tarball
238
194
 
239
- ### Why the manifest is cleaned on a copy
195
+ Cleaning stays out of the source tree so an interrupted publish cannot leave your
196
+ `package.json` half-edited. Pack hooks still run in the source directory and may change it.
240
197
 
241
- The manifest is read out of the packed tarball and written back into a copy of it, in a
242
- temp directory. Your working tree is never touched.
198
+ ### Why the tarball is edited instead of packed again
243
199
 
244
- The obvious alternative is what a lot of hand-rolled release scripts do: edit
245
- `package.json`, publish, edit it back. That's fine until something dies in the middle,
246
- and then your repo is sitting on a manifest nobody meant to keep. It also can't be run
247
- twice at once. Cleaning a copy has neither problem and costs a directory in `/tmp`.
200
+ Uploading the checked tarball prevents npm from choosing files again.
201
+ Cleaning removes `files` from its manifest because installation no longer needs that
202
+ packing instruction. Repacking the cleaned directory could then fall back to ignore rules
203
+ and drop files the first pack included.
248
204
 
249
- ### Why the tarball is edited instead of packed again
205
+ Only `package/package.json` is replaced. Other archive entries retain their bytes,
206
+ order and metadata, including pnpm's owner `0:0`, fixed timestamps and file modes.
207
+ The reader resolves USTAR and PAX paths before checking files and rejects malformed or
208
+ unsupported path metadata.
250
209
 
251
- Give npm a directory and it packs during the upload, so the bytes that reach the registry
252
- only come into existence after the last check has run. Packing first means they exist
253
- before anything is uploaded: they can be listed, scanned for leaks, kept with
254
- `--tarball-out` for a build attestation, and then published as themselves. What you
255
- inspect is what ships.
256
-
257
- So the manifest has to be cleaned inside a tarball that already exists. The obvious way is
258
- to unpack, edit, and pack again — and it is wrong. `files` is a packing instruction, and
259
- cleaning removes it, because it is useless to anyone installing the package. A second pack
260
- then has nothing left to select with, falls back to your `.gitignore`/`.npmignore` for
261
- exclusion, and quietly drops files the first pack included. A package shipping a
262
- `.gitignore` that excludes any other shipped file loses it.
263
-
264
- Editing avoids the question. Only the `package/package.json` member is replaced. Every
265
- other entry is copied without being decoded, so the file set stays exactly what pnpm chose,
266
- and entry shapes this tool does not model (pax headers for long paths, prefix splitting)
267
- pass through untouched. It also keeps pnpm's normalised metadata: owner `0:0`, a fixed
268
- timestamp, mode 644. A plain `tar` invocation would replace those with whatever the build
269
- machine happens to have.
270
-
271
- Lifecycle scripts run once, at the first pack. `pnpm pack` runs your `prepare` and
272
- `prepack`, which is how build output reaches the package at all. Nothing runs afterwards:
273
- npm skips `prepack`/`postpack` when it is handed a tarball rather than a directory, so
274
- nothing can alter the artifact after it was checked.
210
+ `pnpm pack` runs pack hooks, including `prepare` and `prepack`. npm runs no package
211
+ lifecycle scripts when uploading a tarball, so those hooks cannot change the checked
212
+ artifact during upload.
275
213
 
276
214
  ## What it checks
277
215
 
278
- `publish-clean` stops, and publishes nothing, when:
216
+ Publication stops when:
279
217
 
280
218
  - the package is marked `private: true`
281
219
  - the working tree has uncommitted changes (`--no-git-checks` to allow it)
282
220
  - the package has no non-empty `files` array (`--skip-file-check` to allow it)
283
- - the tarball holds tests, CI config, a lockfile or a `tsconfig` (`--allow-suspicious` to
284
- allow it — a separate switch from the one above, so waiving a manifest convention never
285
- silently disarms the artifact scan)
286
- - the tarball holds something that should never ship: a `.env`, an `.npmrc`, `.git`,
287
- `node_modules`, or a private key. This one has no off switch, by any flag or config key
288
- - a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, which
289
- nobody outside your repo can install
290
- - the manifest points `exports`, `types`, `main`, `browser`, `bin` or `sideEffects` at a
291
- path that is not in the tarball
221
+ - the tarball contains a recognised test, CI, lockfile or `tsconfig` path
222
+ (`--allow-suspicious` to allow it)
223
+ - a filename matches the protected rules for environment files, npm credentials, Git
224
+ internals, `node_modules` or key files; these checks cannot be disabled
225
+ - a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, or a local
226
+ dependency points outside the shipped files
227
+ - a declared entry point cannot resolve against the shipped files; checks account for
228
+ extension lookup, conditions and fallbacks, and allow unmatched `sideEffects` globs
292
229
  - rewriting the manifest changed anything else in the tarball
293
- - you asked for `--provenance` from GitHub Actions, but the `repository` in your manifest
230
+ - GitHub trusted publishing or provenance is enabled, but the `repository` in your manifest
294
231
  is not the repository the workflow is running in
295
232
 
296
- It warns, without stopping, when it was started by npm, Yarn or Bun rather than pnpm. The
297
- packing still goes through pnpm, but the warning is there because the rest of your release
298
- probably should too.
233
+ File guards check paths, not file contents. They cannot detect a credential embedded
234
+ in an otherwise allowed source file. See [the rules](src/artifact.ts).
299
235
 
300
236
  ## What the cleaned manifest keeps
301
237
 
302
- Everything a consumer or a registry reads survives: `name`, `version`, `license`,
238
+ The cleaner preserves consumer and registry fields: `name`, `version`, `license`,
303
239
  `dependencies`, `peerDependencies` and their meta, `exports`, `main`, `module`, `types`,
304
- `bin`, `engines`, `os`, `cpu`, `sideEffects`, `publishConfig`, and the rest of the public
305
- surface.
240
+ `bin`, `engines`, `os`, `cpu`, `sideEffects` and `publishConfig`, among others.
306
241
 
307
- `files` goes, because it is spent: it told the packer what to include, the tarball already
308
- exists, nothing re-selects afterwards, and an install extracts every entry unfiltered. npm
309
- agrees — its registry drops the field from the metadata it serves.
242
+ It removes `files` after packing; installers extract the tarball without using that field.
310
243
 
311
- What else goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
244
+ It also removes `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
312
245
  `resolutions`, and the config blocks belonging to test runners, linters, formatters,
313
- coverage tools, build systems and release tools. Scripts go too, apart from the install
314
- lifecycle ones a consumer actually runs: `preinstall`, `install`, `postinstall`,
315
- `prepare` and `uninstall`.
246
+ coverage tools, build systems and release tools. When `preinstall`, `install`, `postinstall`,
247
+ `prepare` or `uninstall` exists, the complete scripts block survives: a lifecycle may call
248
+ any helper script. Otherwise the development-only scripts block is removed.
316
249
 
317
- Anything the tool does not recognise ships, and you get told it did:
250
+ Unknown fields are kept and reported:
318
251
 
319
252
  ```
320
- publish-clean: these manifest fields are not recognised and were published as-is:
321
- someToolConfig
253
+ publish-clean: these manifest fields are not recognised and are retained as-is:
254
+ "someToolConfig"
322
255
  Strip the ones consumers do not read, and acknowledge the ones they do:
323
256
  "publish-clean": { "devFields": ["someToolConfig"] }
324
257
  "publish-clean": { "keepFields": ["someToolConfig"] }
325
258
  ```
326
259
 
327
- The strip list cannot know about a tool invented after it was written, so new
328
- `package.json` keys would otherwise leak into every install unnoticed. Dropping them
329
- instead would be worse: a key some consumer actually resolves would vanish, and you would
330
- hear about it from a stranger's broken build rather than from your own release.
331
-
332
- Add your own with `devFields`. Better still, run `--dry-run` and read the manifest that
333
- would ship instead of trusting this list.
260
+ Unknown fields stay because removing an unfamiliar field can break a consumer's build.
261
+ Use `devFields` to remove a field you know is development-only, or `keepFields` to suppress
262
+ its report. Inspect the result with `--dry-run`.
334
263
 
335
264
  ## Options and config
336
265
 
@@ -338,8 +267,8 @@ would ship instead of trusting this list.
338
267
  publish-clean [options] [package-dir] [-- npm-publish-args]
339
268
  ```
340
269
 
341
- Most settings can be a flag or a `package.json` key. Flags win, so keep per-release
342
- choices like dist-tags on the command line and stable project policy in the manifest:
270
+ Set project defaults in `package.json`. A CLI registry overrides the configured registry;
271
+ boolean flags enable their setting. Pass per-release npm options, such as dist-tags, after `--`:
343
272
 
344
273
  ```json
345
274
  {
@@ -356,8 +285,8 @@ choices like dist-tags on the command line and stable project policy in the mani
356
285
 
357
286
  | Flag | `package.json` | What it does |
358
287
  | -------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
359
- | `--dry-run` | - | Run everything up to the publish, then print the file list and the cleaned `package.json`. |
360
- | `--guard-only` | - | Run everything up to the publish and exit, printing nothing. |
288
+ | `--dry-run` | - | Validate a preview artifact and print its file list and cleaned `package.json`. |
289
+ | `--guard-only` | - | Validate a preview artifact without the file list or manifest output. |
361
290
  | `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
362
291
  | `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
363
292
  | `--skip-file-check` | `skipFileCheck` | Allow a manifest with no `files` array. |
@@ -368,87 +297,72 @@ choices like dist-tags on the command line and stable project policy in the mani
368
297
  | `-h`, `--help` | - | Print usage, every flag, and the config keys. |
369
298
  | `-v`, `--version` | - | Print the installed version. |
370
299
 
371
- Arguments after `--` go to `npm publish`. Pass the dist-tag explicitly: `--tag latest` for
372
- a normal public release.
373
-
374
- A few of these deserve a sentence more.
300
+ Arguments after `--` accept publication options only; `--help` lists them. Extra package
301
+ operands, workspace selectors, unknown options and values starting with `-` are rejected
302
+ so npm cannot substitute an unchecked package. For a filename starting with `-`, use `./`.
303
+ Pass the dist-tag explicitly: `--tag latest` for a normal public release.
375
304
 
376
- `--tarball-out` keeps the bytes that were published, so a release pipeline can attach them
377
- to a GitHub Release or sign them with build-provenance attestation. The copy happens in
378
- every mode, before the publish, so you get the validated artifact even if the upload fails.
305
+ `--tarball-out` saves the checked bytes in every mode, before any upload. You can inspect
306
+ them, attach them to a release or attest them, even if publication fails.
379
307
 
380
- `registry` pins where the package goes, so it cannot end up on whatever registry the
381
- machine happens to be pointed at.
308
+ `registry` sets both the general and package-scope destination in the cleaned manifest.
309
+ Registry URLs must not contain usernames or passwords, including scoped destinations in
310
+ `publishConfig`. Configure npm authentication in npm configuration instead.
382
311
 
383
- `skipFileCheck` and `allowSuspicious` are deliberately two switches. A missing `files`
384
- array is a manifest convention some packages do not follow; tests or a lockfile in the
385
- tarball is content nobody meant to ship. Neither touches the leak checks, which have no
386
- off switch at all.
312
+ `skipFileCheck` waives the manifest's `files` requirement. `allowSuspicious` permits the
313
+ listed development files. Neither disables the protected filename checks.
387
314
 
388
- `noGitChecks` is what you need when you publish from a build directory, or from a checkout
389
- that is not a git repository at all.
315
+ Use `noGitChecks` for a build directory or another directory outside a Git repository.
390
316
 
391
- `devFields` refuses fields that npm or your consumers actually read, like `exports`, `bin`,
392
- `engines` and the dependency maps, so a typo cannot quietly break your package.
317
+ `devFields` refuses known consumer fields such as `exports`, `bin`, `engines` and dependency
318
+ maps to prevent accidental removal.
393
319
 
394
- `keepFields` answers the unrecognised-field report the other way: the field belongs in the
395
- published package, stop mentioning it. A VS Code extension needs `contributes` and
396
- `publisher` in the artifact to work, and no generic publishing tool is ever going to know
397
- that.
320
+ Use `keepFields` for consumer fields the tool does not recognise, such as a VS Code
321
+ extension's `contributes` and `publisher`. It suppresses reports; it does not restore stripped fields.
398
322
 
399
323
  ## What it does not do
400
324
 
401
- It isn't a release manager. It won't pick your version number, write a changelog, tag
402
- anything, push a commit, create a GitHub release, or set up trusted publishing for you. It
403
- also doesn't check that your entry points resolve correctly for consumers. Pair it with a
404
- release manager and a validator; the next section names them.
325
+ Use your release tool for versions, changelogs, tags and GitHub releases. Configure trusted
326
+ publishing separately. `publish-clean` checks declared paths; it does not execute your
327
+ package or validate its type declarations.
405
328
 
406
- It can't publish a package that uses `bundleDependencies`. pnpm links dependencies rather
407
- than copying them, so it has nothing to bundle and refuses:
329
+ Bundled `node_modules` are not allowed. pnpm may first reject `bundleDependencies` with:
408
330
 
409
331
  ```
410
332
  Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
411
333
  ```
412
334
 
413
- Doing what it says makes the package publishable again. This is the one thing you give up
414
- by packing with pnpm, and it's a fair trade: `bundleDependencies` is rare, and the failure
415
- is loud and tells you the fix.
335
+ A hoisted layout can make pnpm pack them, but the resulting `node_modules` entries still
336
+ fail this tool's file checks. Use another publication path if you need to ship them.
416
337
 
417
- ## How it compares
338
+ ## Related tools
418
339
 
419
- [`clean-publish`](https://github.com/shashkovdanil/clean-publish) is the closest prior
420
- art, and the reason this package exists at all. It copies your source tree into a temp
421
- directory, deletes the files and fields it recognises, and publishes that.
340
+ [`clean-publish`](https://github.com/shashkovdanil/clean-publish) cleans a temporary copy
341
+ of the source tree before publishing. `publish-clean` instead cleans a pnpm-produced tarball.
422
342
 
423
- The difference is where the file list comes from. clean-publish starts with your whole
424
- source tree and subtracts, so anything its rules do not recognise gets published.
425
- `publish-clean` starts from what `pnpm pack` produced, which is already the exact file
426
- list your package manager would have shipped, including `files`, `.npmignore`, packlist
427
- rules and resolved `workspace:` specs. Only the manifest is rewritten after that, and the
428
- result is validated again before upload. clean-publish does not re-check its output.
343
+ That preserves pnpm's file selection and workspace resolution, and lets the checks read
344
+ the same bytes npm uploads.
429
345
 
430
- Release managers ([Changesets](https://github.com/changesets/changesets),
431
- [release-please](https://github.com/googleapis/release-please),
346
+ Release tools such as [Changesets](https://github.com/changesets/changesets),
432
347
  [semantic-release](https://github.com/semantic-release/semantic-release),
433
- [release-it](https://github.com/release-it/release-it),
434
- [np](https://github.com/sindresorhus/np)) pick versions, write changelogs, tag, and call
435
- `npm publish`. None of them look inside the tarball. Use one of them together with this,
436
- via the `--guard-only` setup above.
348
+ [release-please](https://github.com/googleapis/release-please),
349
+ [release-it](https://github.com/release-it/release-it) and [np](https://github.com/sindresorhus/np)
350
+ handle release tasks. See [integration](#keeping-your-existing-release-tool) for the
351
+ difference between a preview check and publishing through this CLI.
437
352
 
438
353
  [`publint`](https://publint.dev) and
439
354
  [`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
440
- check that your entry points and type definitions resolve properly for consumers. That is
441
- a different question from what is in the tarball. Run them as well.
355
+ check package entry points and TypeScript compatibility. Use them alongside this tool.
442
356
 
443
- `npm publish --dry-run` prints the file list and stops there. It does not clean anything
444
- and will happily list a `.env` without complaining.
357
+ `npm publish --dry-run` previews npm's publication. It does not clean the manifest or apply
358
+ this tool's protected filename rules.
445
359
 
446
- [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) proves who
447
- published. This tool decides what gets published. They solve different halves of the same
448
- worry, and this package is built to use both.
360
+ [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) authorises a CI
361
+ workflow to publish. Provenance links a release to its source and build; it does not
362
+ check package contents for you.
449
363
 
450
364
  [`pkg-pr-new`](https://github.com/stackblitz-labs/pkg.pr.new) publishes preview builds
451
- per commit without touching the registry. Useful next to this, unrelated to cleaning.
365
+ per commit without publishing a version to npm.
452
366
 
453
367
  Underlying behaviour is defined by [`npm-packlist`](https://github.com/npm/npm-packlist),
454
368
  [`npm pack`](https://docs.npmjs.com/cli/v11/commands/npm-pack/),
@@ -469,3 +383,24 @@ reporting, not public issues: see [SECURITY.md](SECURITY.md).
469
383
  ## License
470
384
 
471
385
  Apache-2.0. Copyright 2026 Anizoptera and Art Shendrik.
386
+
387
+
388
+ ## Validate the final artifact
389
+
390
+ Set `publish-clean.validateArtifact` to an executable and its arguments to check the exact cleaned tarball before retention or upload:
391
+
392
+ ```json
393
+ {
394
+ "publish-clean": {
395
+ "validateArtifact": ["node", "scripts/check-artifact.mjs"]
396
+ }
397
+ }
398
+ ```
399
+
400
+ The command runs once in the source package directory, with the absolute tarball path appended as its last argument. It runs in normal, `--dry-run` and `--guard-only` modes, after built-in artifact checks and before `--tarball-out` copies anything. The configuration is stripped from the published manifest.
401
+
402
+ Use an executable, not a shell command or a Windows `.cmd` shim. Arguments remain literal; pipes, redirection and environment assignments are not interpreted. Relative script paths resolve from the package directory. The executable must be available in PATH or named by a path.
403
+
404
+ The validator must finish successfully and leave the tarball bytes unchanged. A launch failure, nonzero exit, changed or missing artifact stops retention and publication. Successful output is quiet; failure output is reported, with captured output bounded to prevent runaway memory use. Cancellation stops the child process tree before temporary files are removed. The validator is trusted project code, not a sandbox: it must not leave background writers or modify other project files.
405
+
406
+ Inspect the supplied archive directly. Do not invoke `publish-clean` or pack the package again inside the validator; that would recurse or validate different bytes.