@anizoptera/publish-clean 0.9.1 → 0.11.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.
- package/README.md +326 -57
- package/dist/cli.js +48 -1384
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @anizoptera/publish-clean
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
unresolved workspace dependencies and missing entry points.
|
|
3
|
+
Cleans and helps to publish npm packages properly with a clean `package.json` (no unnecessary entries),
|
|
4
|
+
verified `exports`, checks for unwanted files, unresolved workspace dependencies and missing entry points.
|
|
5
5
|
|
|
6
6
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean)
|
|
7
7
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
|
|
@@ -10,23 +10,133 @@ unresolved workspace dependencies and missing entry points.
|
|
|
10
10
|
[](package.json)
|
|
11
11
|
[](LICENSE)
|
|
12
12
|
|
|
13
|
+
**TL;DR** — pack once, clean and check *that* tarball, upload *those* bytes. It never repacks, so
|
|
14
|
+
what was verified is exactly what the registry stores and what provenance signs.
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
pnpm pack
|
|
18
|
+
│
|
|
19
|
+
▼
|
|
20
|
+
rewrite package.json inside the tarball
|
|
21
|
+
│
|
|
22
|
+
▼
|
|
23
|
+
re-read it from disk and check it
|
|
24
|
+
│
|
|
25
|
+
├─▶ unrepaired, and it leaks
|
|
26
|
+
│ or breaks a consumer
|
|
27
|
+
│ └─▶ exit 1
|
|
28
|
+
│
|
|
29
|
+
└─▶ repaired, or only reported
|
|
30
|
+
└─▶ npm publish <that exact file>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
pnpm exec publish-clean verify # all checks, uploads nothing
|
|
35
|
+
pnpm exec publish-clean --dry-run # checks, prints file list and manifest
|
|
36
|
+
pnpm exec publish-clean -- --provenance --access public # check, then publish
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
| What you get | How |
|
|
40
|
+
| --- | --- |
|
|
41
|
+
| [Broken packages stop here](#what-it-checks) | Declared entry points that resolve to nothing, `exports` conditions in an order that loses a consumer its target, `require` branches resolving to ESM, names two filesystems read as one file, `bin` without a shebang, `workspace:`/`catalog:` specs left unresolved. |
|
|
42
|
+
| [Credential files can't ship](#a-packed-secret-is-already-leaked) | A packed `.env`, `.npmrc`, `.pem`/`.key`/keystore or SSH key aborts the run. No flag waives it, and it is not stripped for you: a stripped secret has still leaked and still needs rotating. Matched by file name, so a credential hardcoded inside your source is not caught. |
|
|
43
|
+
| [No dead weight](#dead-weight-ships-forever) | `devDependencies`, `files`, `packageManager`, workspace and catalog config, and tool config blocks (`jest`, `eslint`, `prettier`, `turbo`, …) leave the published manifest. So does the whole `scripts` block, unless it holds an install or `prepare` hook consumers actually run. Packed files nothing references are reported. |
|
|
44
|
+
| [Checked bytes = published bytes](#what-this-buys-for-provenance) | The manifest is rewritten inside pnpm's own tarball and that file is uploaded. A pipeline that repacks after checking signs bytes nothing verified. |
|
|
45
|
+
| [Rules measured, not guessed](#rules-are-measured-not-guessed) | Every rule and every tolerance was measured against thousands of installed published packages first. Equality alone on declared paths refused 373 of 5192; a fixed `exports` order refused 97 of 3674. |
|
|
46
|
+
| [Nothing new to trust](#install) | One JavaScript file, zero runtime dependencies. It runs on the path that handles your registry token, so a transitive package would be unaudited code next to a live credential. |
|
|
47
|
+
| [Check without publishing](#checking-every-pull-request) | `verify` gates pull requests and works on `private: true` packages. Exit 1 on failure, findings on stderr. |
|
|
48
|
+
|
|
49
|
+
It edits nothing outside the tarball, and fixes only what the packed files settle without guessing.
|
|
50
|
+
One run lists every defect instead of stopping at the first. What it repaired does not fail the run;
|
|
51
|
+
what it could not repair does. Every judgement call has a flag to waive it. A leaked credential
|
|
52
|
+
does not.
|
|
53
|
+
|
|
54
|
+
## Why
|
|
55
|
+
|
|
56
|
+
Publishing is the one step you cannot take back. npm lets you unpublish within 72 hours only if no
|
|
57
|
+
other package depends on yours. After that you also need fewer than 300 weekly downloads and a
|
|
58
|
+
single maintainer. The version number is gone either way:
|
|
59
|
+
[npm's policy](https://docs.npmjs.com/policies/unpublish) is that "once `package@version` has been
|
|
60
|
+
used, you can never use it again". You fix a bad release by publishing another one.
|
|
61
|
+
|
|
62
|
+
The defects that reach consumers are the ones your own machine cannot show you:
|
|
63
|
+
|
|
64
|
+
| Defect | Your machine | Consumer installs | Consumer uses it |
|
|
65
|
+
| ------ | ------------ | ----------------- | ---------------- |
|
|
66
|
+
| Two packed names differing only in letter case | fine (case-sensitive disk) | **reports success** | file silently missing |
|
|
67
|
+
| `bin` file with no shebang | fine (you run `node file.js`) | fine | `exec format error` |
|
|
68
|
+
| Package imports itself through a subpath `exports` hides | fine (resolves by path in your repo) | fine | cannot resolve |
|
|
69
|
+
| `./Utils.js` imported as `./utils.js` | fine on macOS | fine | fails on Linux |
|
|
70
|
+
| `types` pointing at JavaScript with no `.d.ts` | fine | fine | every type silently `any` |
|
|
71
|
+
| `require` branch resolving to an ES module | fine (you use `import`) | fine | fails on older Node |
|
|
72
|
+
|
|
73
|
+
Green the whole way down. Nothing in the normal chain fails, so the first report comes from a
|
|
74
|
+
stranger, against a version you can no longer replace.
|
|
75
|
+
|
|
76
|
+
### A packed secret is already leaked
|
|
77
|
+
|
|
78
|
+
The worst case is not a broken package. It is a `.env` or an `.npmrc` inside the tarball. By the
|
|
79
|
+
time anything notices, the key exists outside your machine: it was written into an archive, and if
|
|
80
|
+
the upload went through, into a registry that hands it to anyone who asks.
|
|
81
|
+
|
|
82
|
+
`publish-clean` refuses those outright. No flag waives it and `--strict` has nothing to add. It will
|
|
83
|
+
not strip the file for you either, though that is what most people expect: a stripped secret has
|
|
84
|
+
still leaked, and a clean-looking artifact is how it goes unrotated. The report says to rotate the
|
|
85
|
+
credential first, then narrow `files`.
|
|
86
|
+
|
|
87
|
+
### Dead weight ships forever
|
|
88
|
+
|
|
89
|
+
The second cost is invisible to the only person who can fix it. You pay nothing for a bloated
|
|
90
|
+
package: you build it once. Everyone else pays, on every install, every CI run, every Docker layer.
|
|
91
|
+
Those bytes sit in every `node_modules` that ever resolved your package, and they cannot be taken
|
|
92
|
+
out of a version that is already published.
|
|
93
|
+
|
|
94
|
+
Nothing complains, because nothing is broken. A shipped `__tests__` directory installs fine. A jest
|
|
95
|
+
config block in `package.json` parses fine. Both are downloaded forever by people who will never
|
|
96
|
+
use them.
|
|
97
|
+
|
|
98
|
+
So waste here is a defect with a rule id and an exit code, not a matter of taste. The one thing this
|
|
99
|
+
tool will not do is drop a manifest field it does not recognise: breaking a stranger's build costs
|
|
100
|
+
more than the bytes do.
|
|
101
|
+
|
|
102
|
+
### Rules are measured, not guessed
|
|
103
|
+
|
|
104
|
+
A checker that rejects a working package is worse than no checker. Its mistake and a real defect
|
|
105
|
+
look identical from the outside, and the only way to find out which you have is to publish anyway.
|
|
106
|
+
That is the step this tool exists to protect.
|
|
107
|
+
|
|
108
|
+
So no rule here is written from the spec alone. Each is measured against thousands of installed
|
|
109
|
+
packages first, and every tolerance exists because its absence refused a package that works.
|
|
110
|
+
Matching declared paths to packed names by equality refused 373 of 5192 packages: `vite`, `svelte`,
|
|
111
|
+
every `@types/*` package, every `@aws-sdk` client. Demanding a fixed order for `exports` conditions
|
|
112
|
+
refused 97 of 3674. After the tolerances those measurements forced, 14 remain, every one a real
|
|
113
|
+
defect.
|
|
114
|
+
[`docs/exports.md`](https://github.com/Anizoptera/publish-clean/blob/main/docs/exports.md) carries
|
|
115
|
+
the measurements and the specimens.
|
|
116
|
+
|
|
117
|
+
If it still refuses a package that works, that is a bug here. Report it.
|
|
118
|
+
|
|
119
|
+
## What it does
|
|
120
|
+
|
|
13
121
|
`publish-clean` removes `devDependencies`, workspace settings and tool config from the
|
|
14
122
|
published manifest. Consumer fields and lifecycle helpers stay. Unknown fields are
|
|
15
123
|
reported for review and kept unless you choose to remove them.
|
|
16
124
|
|
|
17
|
-
It packs once with pnpm, cleans the manifest inside the tarball, checks that file, then
|
|
18
|
-
|
|
19
|
-
source files alone; your pack hooks still run and can change them.
|
|
125
|
+
It packs once with pnpm, cleans the manifest inside the tarball, checks that file, then uploads it
|
|
126
|
+
with npm. Cleaning leaves your source files alone; your pack hooks still run and can change them.
|
|
20
127
|
|
|
21
|
-
|
|
128
|
+
Check, then publish:
|
|
22
129
|
|
|
23
130
|
```sh
|
|
24
|
-
pnpm exec publish-clean
|
|
131
|
+
pnpm exec publish-clean verify
|
|
25
132
|
pnpm exec publish-clean -- --access public --tag latest --provenance
|
|
26
133
|
```
|
|
27
134
|
|
|
28
|
-
|
|
29
|
-
|
|
135
|
+
`verify` runs every check and publishes nothing. It works on a `private: true` package, so
|
|
136
|
+
a package that never goes to a registry can still be checked by the rules it would face.
|
|
137
|
+
|
|
138
|
+
Requires Node.js 22+ and pnpm, plus npm to publish. The publish command above needs
|
|
139
|
+
[CI provenance setup](#publishing-a-public-package-from-ci).
|
|
30
140
|
|
|
31
141
|
## Install
|
|
32
142
|
|
|
@@ -37,9 +147,17 @@ command above needs [CI provenance setup](#publishing-a-public-package-from-ci).
|
|
|
37
147
|
| npm | `npm i -D @anizoptera/publish-clean` | `npm exec publish-clean` |
|
|
38
148
|
| Yarn | `yarn add -D @anizoptera/publish-clean` | `yarn publish-clean` |
|
|
39
149
|
|
|
40
|
-
Both `pnpm` and `npm` must be on `PATH
|
|
41
|
-
|
|
42
|
-
requirements, not bundled dependencies.
|
|
150
|
+
Both `pnpm` and `npm` must be on `PATH` to publish, including in Bun, npm and Yarn projects
|
|
151
|
+
and CI. `pnpm` alone is enough to check one: `verify` and `--dry-run` stop before the upload,
|
|
152
|
+
so they never start npm. pnpm and npm are separate requirements, not bundled dependencies.
|
|
153
|
+
|
|
154
|
+
The CLI is one JavaScript file with no runtime dependencies, and that is deliberate: it sits on the
|
|
155
|
+
publish path and handles registry credentials, so any transitive package would be unaudited code
|
|
156
|
+
next to a live token.
|
|
157
|
+
|
|
158
|
+
pnpm 12 installs its native binary from its own install script, so install it with build scripts
|
|
159
|
+
allowed. Under Bun, which blocks them by default, list `pnpm` in `trustedDependencies`. Otherwise
|
|
160
|
+
pnpm's command stays a placeholder that this tool cannot start. pnpm 11 needs nothing special.
|
|
43
161
|
|
|
44
162
|
For trusted publishing, use Node.js 22.14+ and npm 11.5.1+. Provenance requires a public
|
|
45
163
|
package, a public source repository and a supported CI provider. See
|
|
@@ -64,7 +182,7 @@ artifact's hash.
|
|
|
64
182
|
## Package managers
|
|
65
183
|
|
|
66
184
|
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.
|
|
185
|
+
checked tarball. The [packer comparison](https://github.com/Anizoptera/publish-clean/blob/main/docs/why-pnpm-and-npm.md) explains the trade-offs.
|
|
68
186
|
|
|
69
187
|
Starting through another package manager prints an advisory on stderr. It does not change
|
|
70
188
|
the packer or stop publication, and there is no option to suppress it.
|
|
@@ -117,7 +235,7 @@ steps:
|
|
|
117
235
|
Use `--tag latest` for stable releases and `--tag next` for prereleases. npm defaults
|
|
118
236
|
to `latest`, so omitting the tag can give ordinary installs a prerelease.
|
|
119
237
|
|
|
120
|
-
For a new package name, follow the [first-publish setup](docs/first-publish.md).
|
|
238
|
+
For a new package name, follow the [first-publish setup](https://github.com/Anizoptera/publish-clean/blob/main/docs/first-publish.md).
|
|
121
239
|
|
|
122
240
|
To block direct publication from your source directory, add this hook. Publishing a
|
|
123
241
|
tarball does not run it:
|
|
@@ -130,6 +248,22 @@ tarball does not run it:
|
|
|
130
248
|
}
|
|
131
249
|
```
|
|
132
250
|
|
|
251
|
+
### Checking every pull request
|
|
252
|
+
|
|
253
|
+
`verify` needs no registry, no credentials and no npm, so it runs in ordinary PR CI next to your
|
|
254
|
+
tests:
|
|
255
|
+
|
|
256
|
+
```yaml
|
|
257
|
+
- run: pnpm exec publish-clean verify
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
A packaging defect then shows up in the change that caused it, instead of on release day with
|
|
261
|
+
everyone waiting. Most of what this tool finds is introduced by an edit to `package.json` or to the
|
|
262
|
+
file layout, so the PR that made the edit is where the answer is cheapest.
|
|
263
|
+
|
|
264
|
+
`--strict` is worth considering here even if you do not use it when publishing: a warning that fails
|
|
265
|
+
a PR costs a rerun, while the same warning at release costs a version number.
|
|
266
|
+
|
|
133
267
|
### Keeping your existing release tool
|
|
134
268
|
|
|
135
269
|
If your release tool supports a custom upload command, use `publish-clean` there.
|
|
@@ -138,7 +272,7 @@ For a preview check only, add:
|
|
|
138
272
|
```json
|
|
139
273
|
{
|
|
140
274
|
"scripts": {
|
|
141
|
-
"prepublishOnly": "publish-clean
|
|
275
|
+
"prepublishOnly": "publish-clean verify"
|
|
142
276
|
}
|
|
143
277
|
}
|
|
144
278
|
```
|
|
@@ -166,6 +300,19 @@ publish-clean -- --access restricted --tag latest
|
|
|
166
300
|
Omit provenance for restricted packages. Leave `private: true` unset: it prohibits
|
|
167
301
|
publication, even to a private registry.
|
|
168
302
|
|
|
303
|
+
### Adding it to a package that already exists
|
|
304
|
+
|
|
305
|
+
A package published for years will usually report several findings the first time. You do not have
|
|
306
|
+
to clear them all before you can publish again.
|
|
307
|
+
|
|
308
|
+
Run `verify` first: it shows the whole list and cannot publish anything. Then decide per finding.
|
|
309
|
+
The judgement calls have opt-outs, one per rule, so you can disagree with one and keep shipping:
|
|
310
|
+
`--allow-suspicious` for development files you ship on purpose, `allowUnreferenced` for files
|
|
311
|
+
nothing imports by design, `--skip-file-check` for a package with no `files` array.
|
|
312
|
+
|
|
313
|
+
What has no opt-out is a leaked credential, a packed `node_modules` or `.git`, and a defect that
|
|
314
|
+
breaks a consumer. Those are the ones worth stopping for.
|
|
315
|
+
|
|
169
316
|
### Publishing one package out of a monorepo
|
|
170
317
|
|
|
171
318
|
```bash
|
|
@@ -184,7 +331,12 @@ flowchart TD
|
|
|
184
331
|
E -->|all pass| G[npm publish this same tarball]
|
|
185
332
|
```
|
|
186
333
|
|
|
187
|
-
|
|
334
|
+
Exit code is 0 when nothing stopped the run, 1 when something did, and 130 or 143 when a SIGINT or
|
|
335
|
+
SIGTERM cancelled it. A CI job can tell a real failure from a cancelled runner by that alone.
|
|
336
|
+
Findings and the verdict go to stderr; `--dry-run` prints the file list and the cleaned manifest on
|
|
337
|
+
stdout, so you can read one without the other.
|
|
338
|
+
|
|
339
|
+
`verify` and `--dry-run` validate the artifact, but skip publication preflight.
|
|
188
340
|
Neither proves that registry access, credentials, provenance requirements or repository
|
|
189
341
|
identity are correct. Pack hooks still run, including any network operations they perform.
|
|
190
342
|
|
|
@@ -204,34 +356,135 @@ and drop files the first pack included.
|
|
|
204
356
|
|
|
205
357
|
Only `package/package.json` is replaced. Other archive entries retain their bytes,
|
|
206
358
|
order and metadata, including pnpm's owner `0:0`, fixed timestamps and file modes.
|
|
207
|
-
The reader resolves USTAR and
|
|
208
|
-
unsupported path metadata.
|
|
359
|
+
The reader resolves USTAR, PAX and GNU long-name paths before checking files and rejects
|
|
360
|
+
malformed or unsupported path metadata. A path too long for a plain tar name is stated by a
|
|
361
|
+
header in front of the entry it names, so every guard judges the path the archive actually
|
|
362
|
+
extracts to rather than the placeholder in the entry's own header.
|
|
209
363
|
|
|
210
364
|
`pnpm pack` runs pack hooks, including `prepare` and `prepack`. npm runs no package
|
|
211
365
|
lifecycle scripts when uploading a tarball, so those hooks cannot change the checked
|
|
212
366
|
artifact during upload.
|
|
213
367
|
|
|
368
|
+
### What this buys for provenance
|
|
369
|
+
|
|
370
|
+
npm builds a provenance attestation from the SHA-512 of the file it uploads. A pipeline that checks
|
|
371
|
+
one artifact and then repacks signs bytes that nothing verified, and the attestation still looks
|
|
372
|
+
perfectly valid. Uploading the checked file is what makes the signature cover what the checks
|
|
373
|
+
actually passed.
|
|
374
|
+
|
|
214
375
|
## What it checks
|
|
215
376
|
|
|
377
|
+
Every finding prints as `publish-clean [severity] rule-id at where`. The id in brackets below is
|
|
378
|
+
that id. Search this file for the one in your output.
|
|
379
|
+
|
|
380
|
+
Two rules cover the whole output:
|
|
381
|
+
|
|
382
|
+
- **`[warning]` never stops the run.** Wasted bytes, nothing a consumer can trip over. `--strict`
|
|
383
|
+
turns these into errors.
|
|
384
|
+
- **`[error]` stops the run, unless the finding says it was repaired.** A repair fixed the
|
|
385
|
+
published tarball, not your source, so it still prints as an error and you still have something
|
|
386
|
+
to fix. It does not stop the publish, because the artifact going up is correct. `--strict` never
|
|
387
|
+
changes that.
|
|
388
|
+
|
|
389
|
+
A leaked credential or a packed `node_modules`/`.git` always stops the run, and no flag waives it.
|
|
390
|
+
Every run ends with a verdict line, so a pass is never silent.
|
|
391
|
+
|
|
216
392
|
Publication stops when:
|
|
217
393
|
|
|
218
394
|
- the package is marked `private: true`
|
|
219
|
-
- the working tree has uncommitted changes (`--no-git-checks` to allow it)
|
|
395
|
+
- the working tree has uncommitted changes (`--no-git-checks` to allow it). A directory under no
|
|
396
|
+
version control has no commit to differ from, so it warns and continues instead
|
|
220
397
|
- the package has no non-empty `files` array (`--skip-file-check` to allow it)
|
|
221
398
|
- 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,
|
|
224
|
-
internals, `node_modules
|
|
399
|
+
(`--allow-suspicious` to allow it) [`suspicious-file`]
|
|
400
|
+
- a filename matches the protected rules for environment files, npm credentials [`secret-file`],
|
|
401
|
+
or Git internals, `node_modules`, and editor or coding-agent state (`.idea`, `.vscode`,
|
|
402
|
+
`.cursor`, `.windsurf`, `.junie`, `.claude`, `.codex`, `.gemini`, `.agent`, `.agents`, `.omc`,
|
|
403
|
+
`.aider*`) at any depth [`internal-file`]; these checks cannot be disabled
|
|
225
404
|
- a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, or a local
|
|
226
|
-
dependency points outside the shipped files
|
|
405
|
+
dependency points outside the shipped files [`monorepo-only-spec`]
|
|
227
406
|
- a declared entry point cannot resolve against the shipped files; checks account for
|
|
228
|
-
extension lookup, conditions and fallbacks
|
|
407
|
+
extension lookup, conditions and fallbacks. A declared path no consumer can resolve — an object
|
|
408
|
+
`browser`, `sideEffects`, an internal `#` import, a `*` pattern matching no packed file — reports
|
|
409
|
+
and continues instead [`declared-path-inert`], and `--strict` refuses it
|
|
229
410
|
- rewriting the manifest changed anything else in the tarball
|
|
230
411
|
- GitHub trusted publishing or provenance is enabled, but the `repository` in your manifest
|
|
231
412
|
is not the repository the workflow is running in
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
413
|
+
- a `require` condition resolves to an ES module [`require-branch-is-esm`]. Node can require one
|
|
414
|
+
only from 20.19 and 22.12 onward, a consumer can switch that off, and top-level await fails on
|
|
415
|
+
every version. Point `require` at a CommonJS build, or add a `module-sync` branch
|
|
416
|
+
- a condition sits out of canonical order where reordering it would change what somebody resolves,
|
|
417
|
+
and a consumer really loses its target: a runtime-specific build shadowed by a generic one. The
|
|
418
|
+
tool will not guess here, so it reports and stops instead [`exports-condition-order-unsafe`]
|
|
419
|
+
- two packed names differ only in letter case or Unicode form [`packed-name-collision`]. They
|
|
420
|
+
collapse onto one path on macOS and Windows, which ignore both by default. Two files means one
|
|
421
|
+
silently overwrites the other and the install still reports success; a file colliding with a
|
|
422
|
+
directory means the install fails outright. Only a case-sensitive filesystem can produce the
|
|
423
|
+
pair, which is why the author never sees it
|
|
424
|
+
- a packed name Windows cannot create [`packed-name-unportable`]: a path component named after a
|
|
425
|
+
DOS device (`aux`, `con`, `nul`, `com1`…, with or without an extension), a character such as `:`
|
|
426
|
+
or `?`, a trailing dot or space. Declare `"os": ["!win32"]` if the package genuinely does not run
|
|
427
|
+
there and this stops applying. A path component over 255 bytes is refused regardless, because no
|
|
428
|
+
filesystem accepts one
|
|
429
|
+
- a `bin` file has no shebang [`bin-no-shebang`], or its shebang ends in CR
|
|
430
|
+
[`shebang-carriage-return`]. An installer symlinks the file and the command is executed directly,
|
|
431
|
+
so without that first line Linux and macOS fail with `exec format error` and npm has no
|
|
432
|
+
interpreter for its Windows shim. A trailing CR is invisible in an editor and makes the kernel
|
|
433
|
+
look for an interpreter literally named `node\r`. A `bin` file holding a NUL byte in its first
|
|
434
|
+
512 bytes is exempt: it is a compiled binary
|
|
435
|
+
- a shipped file imports another by the wrong letter case [`import-case-mismatch`], so it works on
|
|
436
|
+
the author's macOS and fails on a consumer's Linux
|
|
437
|
+
- the package imports itself by name through a subpath its `exports` does not expose
|
|
438
|
+
[`self-import-not-exported`], which resolves for nobody, and looks fine in your own repository,
|
|
439
|
+
where it resolves by path
|
|
440
|
+
- the tarball holds a file nothing in the package reaches [`unreferenced-file`]: no entry point,
|
|
441
|
+
no import from a reached file, no script. Declare the ones that are deliberate:
|
|
442
|
+
`"publish-clean": { "allowUnreferenced": ["assets"] }`, matched as a prefix, so naming a directory
|
|
443
|
+
covers everything under it. This check only runs when the package has an `exports` field, because
|
|
444
|
+
that is what makes unlisted paths unimportable. Without it every shipped file is reachable and
|
|
445
|
+
none is dead.
|
|
446
|
+
|
|
447
|
+
A malformed registry URL [`registry-not-a-url`], or one carrying a password
|
|
448
|
+
[`registry-credentials`], also stops the run. Treat such a password as compromised: it is in your
|
|
449
|
+
`package.json` and was about to be published inside the tarball's manifest.
|
|
450
|
+
|
|
451
|
+
File guards match paths, not file contents. A credential hardcoded inside an otherwise allowed
|
|
452
|
+
source file is published and nothing here reports it.
|
|
453
|
+
|
|
454
|
+
## What it repairs
|
|
455
|
+
|
|
456
|
+
An `exports` map is order-sensitive: a consumer activates a whole set of conditions at once and
|
|
457
|
+
takes the first key in that set, so the order you wrote picks the winner. `publish-clean`
|
|
458
|
+
flattens the map into the resolution it produces for every possible consumer, and rewrites it
|
|
459
|
+
only when the result is provably identical: dropping a `node` branch that repeats `default`
|
|
460
|
+
[`exports-inert-condition`], collapsing `{"default": "./x.js"}` [`exports-redundant-default`], and
|
|
461
|
+
putting keys that real resolvers require in a fixed order into it [`exports-condition-order`].
|
|
462
|
+
A branch no consumer reaches [`exports-unreachable-branch`], a consumer no branch serves
|
|
463
|
+
[`exports-unresolvable`] and a condition name no known runtime or bundler activates
|
|
464
|
+
[`exports-unknown-condition`] are reported, never guessed at. Every repair is
|
|
465
|
+
reported, lands only in the published manifest, and never touches your source. `--no-heal`, or
|
|
466
|
+
`"publish-clean": { "heal": false }`, reports without rewriting.
|
|
467
|
+
|
|
468
|
+
`types` is the one exception, and the only rewrite here that changes what somebody resolves. Only
|
|
469
|
+
a type checker activates it, so nothing that runs your package can tell the difference:
|
|
470
|
+
|
|
471
|
+
- a `types` branch pointing at JavaScript with no declaration file beside it is **removed**
|
|
472
|
+
[`types-branch-not-declarations`]. It promised an API the package does not carry, and a checker
|
|
473
|
+
was reading that JavaScript as your declarations and typing everything `any`.
|
|
474
|
+
- declarations hidden behind a key that leads a checker nowhere are **moved to the front**
|
|
475
|
+
[`types-branch-unreachable`], where every checker looks first.
|
|
476
|
+
|
|
477
|
+
Both print as errors — fix your source — and neither stops the publish, because the published
|
|
478
|
+
artifact is correct. Under `--no-heal` neither rewrite is applied, and then both defects stop it.
|
|
479
|
+
|
|
480
|
+
Anything the archive cannot settle is left exactly as you wrote it: a `types` target the package
|
|
481
|
+
does not ship is a missing file and keeps that report, and nothing is moved across a condition this
|
|
482
|
+
tool does not recognise, since a private name may be meant for a consumer configured to take it.
|
|
483
|
+
|
|
484
|
+
Still reported and left alone: anything inside a fallback array [`exports-fallback-array`], because
|
|
485
|
+
Bun resolves those differently from Node and Deno and no rewrite is safe for everyone, and any map
|
|
486
|
+
too large to enumerate [`exports-too-complex`]. [`docs/exports.md`](https://github.com/Anizoptera/publish-clean/blob/main/docs/exports.md) has
|
|
487
|
+
the measured condition sets behind these rules.
|
|
235
488
|
|
|
236
489
|
## What the cleaned manifest keeps
|
|
237
490
|
|
|
@@ -250,7 +503,8 @@ any helper script. Otherwise the development-only scripts block is removed.
|
|
|
250
503
|
Unknown fields are kept and reported:
|
|
251
504
|
|
|
252
505
|
```
|
|
253
|
-
publish-clean
|
|
506
|
+
publish-clean [warning] unrecognized-field at 1 manifest field
|
|
507
|
+
These manifest fields are not recognised and are retained as-is:
|
|
254
508
|
"someToolConfig"
|
|
255
509
|
Strip the ones consumers do not read, and acknowledge the ones they do:
|
|
256
510
|
"publish-clean": { "devFields": ["someToolConfig"] }
|
|
@@ -259,7 +513,8 @@ Strip the ones consumers do not read, and acknowledge the ones they do:
|
|
|
259
513
|
|
|
260
514
|
Unknown fields stay because removing an unfamiliar field can break a consumer's build.
|
|
261
515
|
Use `devFields` to remove a field you know is development-only, or `keepFields` to suppress
|
|
262
|
-
its report. Inspect the result
|
|
516
|
+
its report. `--strict` promotes this warning to an error like any other. Inspect the result
|
|
517
|
+
with `--dry-run`.
|
|
263
518
|
|
|
264
519
|
## Options and config
|
|
265
520
|
|
|
@@ -285,8 +540,12 @@ boolean flags enable their setting. Pass per-release npm options, such as dist-t
|
|
|
285
540
|
|
|
286
541
|
| Flag | `package.json` | What it does |
|
|
287
542
|
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
|
|
543
|
+
| `verify [dir]` | - | Run every check and publish nothing. Works on a `private: true` package. |
|
|
544
|
+
| `--verify-only` | - | The `verify` subcommand, for scripts that can only pass flags. |
|
|
545
|
+
| `--strict` | - | Treat warnings as errors. Never makes an already-applied repair fatal. |
|
|
546
|
+
| `--no-heal` | `heal: false` | Report repairable `exports`/`imports` defects without repairing them. |
|
|
288
547
|
| `--dry-run` | - | Validate a preview artifact and print its file list and cleaned `package.json`. |
|
|
289
|
-
| `--guard-only` | - |
|
|
548
|
+
| `--guard-only` | - | Deprecated alias for `verify`; fails on a `private: true` package. |
|
|
290
549
|
| `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
|
|
291
550
|
| `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
|
|
292
551
|
| `--skip-file-check` | `skipFileCheck` | Allow a manifest with no `files` array. |
|
|
@@ -294,6 +553,8 @@ boolean flags enable their setting. Pass per-release npm options, such as dist-t
|
|
|
294
553
|
| `--no-git-checks` | `noGitChecks` | Allow publishing from a dirty working tree. |
|
|
295
554
|
| - | `devFields` | Extra manifest fields to strip. |
|
|
296
555
|
| - | `keepFields` | Fields that belong in the published package, so stop reporting them. |
|
|
556
|
+
| - | `allowUnreferenced` | Shipped paths nothing imports, on purpose. Matched as a prefix, so a directory name covers everything under it. |
|
|
557
|
+
| - | [`validateArtifact`](#validate-the-final-artifact) | Run your checks on the cleaned tarball before copying or publishing it. |
|
|
297
558
|
| `-h`, `--help` | - | Print usage, every flag, and the config keys. |
|
|
298
559
|
| `-v`, `--version` | - | Print the installed version. |
|
|
299
560
|
|
|
@@ -312,7 +573,9 @@ Registry URLs must not contain usernames or passwords, including scoped destinat
|
|
|
312
573
|
`skipFileCheck` waives the manifest's `files` requirement. `allowSuspicious` permits the
|
|
313
574
|
listed development files. Neither disables the protected filename checks.
|
|
314
575
|
|
|
315
|
-
Use `noGitChecks`
|
|
576
|
+
Use `noGitChecks` to publish from a checkout whose working tree is dirty. A directory outside any
|
|
577
|
+
Git repository does not need it: there is no commit there for a tree to differ from, so the check
|
|
578
|
+
reports that it was skipped and the run continues.
|
|
316
579
|
|
|
317
580
|
`devFields` refuses known consumer fields such as `exports`, `bin`, `engines` and dependency
|
|
318
581
|
maps to prevent accidental removal.
|
|
@@ -320,11 +583,35 @@ maps to prevent accidental removal.
|
|
|
320
583
|
Use `keepFields` for consumer fields the tool does not recognise, such as a VS Code
|
|
321
584
|
extension's `contributes` and `publisher`. It suppresses reports; it does not restore stripped fields.
|
|
322
585
|
|
|
586
|
+
### Validate the final artifact
|
|
587
|
+
|
|
588
|
+
Use `validateArtifact` to check what users will install, such as package imports or type declarations. Add the command to your `package.json`:
|
|
589
|
+
|
|
590
|
+
```json
|
|
591
|
+
{
|
|
592
|
+
"publish-clean": {
|
|
593
|
+
"validateArtifact": ["node", "scripts/check-artifact.mjs"]
|
|
594
|
+
}
|
|
595
|
+
}
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
This runs `node scripts/check-artifact.mjs /absolute/path/to/package.tgz` from your package directory. Read the tarball path from `process.argv.at(-1)`; configured arguments come before it.
|
|
599
|
+
|
|
600
|
+
The command runs once after built-in checks and before publication or a `--tarball-out` copy. It also runs in `verify` and `--dry-run` modes. The config is removed from the published manifest.
|
|
601
|
+
|
|
602
|
+
The first item must name an executable on `PATH` or by its path. Use `node` or `bun` to run scripts, including on Windows; `.cmd` shims are not supported. Arguments are passed literally, without a shell: no pipes, redirection or environment assignments. Relative paths start at your package directory.
|
|
603
|
+
|
|
604
|
+
Exit with code 0 to pass or a nonzero code to reject the package. A failed launch, failed check, or changed or deleted tarball stops publication and copying. Output is hidden on success and shown on failure, with a capture limit to bound memory use. Cancellation stops the command and its child processes before removing temporary files.
|
|
605
|
+
|
|
606
|
+
Your script runs with your permissions. Keep it read-only and wait for its child processes to finish; publish-clean does not sandbox it or protect other project files.
|
|
607
|
+
|
|
608
|
+
Check the supplied tarball. Packing again checks different bytes; calling publish-clean from the script runs the same hook again.
|
|
609
|
+
|
|
323
610
|
## What it does not do
|
|
324
611
|
|
|
325
612
|
Use your release tool for versions, changelogs, tags and GitHub releases. Configure trusted
|
|
326
|
-
publishing separately.
|
|
327
|
-
|
|
613
|
+
publishing separately. Built-in checks verify declared paths. To test package imports or
|
|
614
|
+
type declarations, supply a [validation command](#validate-the-final-artifact).
|
|
328
615
|
|
|
329
616
|
Bundled `node_modules` are not allowed. pnpm may first reject `bundleDependencies` with:
|
|
330
617
|
|
|
@@ -352,7 +639,10 @@ difference between a preview check and publishing through this CLI.
|
|
|
352
639
|
|
|
353
640
|
[`publint`](https://publint.dev) and
|
|
354
641
|
[`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
|
|
355
|
-
check package entry points and TypeScript compatibility.
|
|
642
|
+
check package entry points and TypeScript compatibility. Run them alongside this tool. They only
|
|
643
|
+
report: they do not clean the manifest, repair anything, or publish. They also cover what this tool
|
|
644
|
+
deliberately leaves out of scope: type resolution and module-format analysis. Neither replaces the
|
|
645
|
+
other, and no check here is skipped on the grounds that publint reports it too.
|
|
356
646
|
|
|
357
647
|
`npm publish --dry-run` previews npm's publication. It does not clean the manifest or apply
|
|
358
648
|
this tool's protected filename rules.
|
|
@@ -377,30 +667,9 @@ bun install --frozen-lockfile
|
|
|
377
667
|
bun run check
|
|
378
668
|
```
|
|
379
669
|
|
|
380
|
-
[CONTRIBUTING.md](CONTRIBUTING.md) has the rest. Security problems go through private
|
|
381
|
-
reporting, not public issues: see [SECURITY.md](SECURITY.md).
|
|
670
|
+
[CONTRIBUTING.md](https://github.com/Anizoptera/publish-clean/blob/main/CONTRIBUTING.md) has the rest. Security problems go through private
|
|
671
|
+
reporting, not public issues: see [SECURITY.md](https://github.com/Anizoptera/publish-clean/blob/main/SECURITY.md).
|
|
382
672
|
|
|
383
673
|
## License
|
|
384
674
|
|
|
385
675
|
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.
|