@anizoptera/publish-clean 0.7.3 → 0.8.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 +54 -66
- package/dist/cli.js +597 -370
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -27,7 +27,7 @@ under conditions npm decides.
|
|
|
27
27
|
|
|
28
28
|
`publish-clean` packs the package once, rewrites the `package.json` inside that tarball
|
|
29
29
|
down to what consumers actually use, checks the result, and publishes those exact bytes.
|
|
30
|
-
|
|
30
|
+
Cleaning does not edit your working tree; your pack lifecycle scripts can. If the artifact still has something in it that should
|
|
31
31
|
not ship, or declares a `main`, `exports`, or `bin` path that is not in the tarball, it
|
|
32
32
|
fails instead of publishing.
|
|
33
33
|
|
|
@@ -61,22 +61,17 @@ supply-chain risk of its own, and this one has no transitive code to audit.
|
|
|
61
61
|
`--provenance` additionally needs npm 11.5.1+ and a cloud CI runner. npm will not sign a
|
|
62
62
|
publish that came from your laptop.
|
|
63
63
|
|
|
64
|
-
### Running it under Bun
|
|
64
|
+
### Running it under Bun
|
|
65
65
|
|
|
66
|
-
gzip
|
|
67
|
-
|
|
68
|
-
a byte-identical archive inside. To get it, pass Bun the **file path**:
|
|
66
|
+
gzip bytes depend on the runtime and version executing the CLI. To run it under Bun,
|
|
67
|
+
pass Bun the **file path**:
|
|
69
68
|
|
|
70
69
|
```sh
|
|
71
70
|
bun ./node_modules/.bin/publish-clean
|
|
72
71
|
```
|
|
73
72
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
its `#!/usr/bin/env node` shebang and runs Node. They succeed, and you get Node's bytes.
|
|
77
|
-
|
|
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.
|
|
73
|
+
The installed command has a Node shebang. Passing the file directly avoids relying on
|
|
74
|
+
how a package runner selects an interpreter or changes the child tools' environment.
|
|
80
75
|
|
|
81
76
|
Either runtime produces valid gzip with identical contents, so the choice is free. The one
|
|
82
77
|
rule is not to switch runtimes _within_ a version: if a release is re-run to repair its
|
|
@@ -84,9 +79,9 @@ artifacts, the bytes have to come out the same, and the two encoders do not agre
|
|
|
84
79
|
|
|
85
80
|
## Package managers
|
|
86
81
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
82
|
+
pnpm resolves workspace dependencies and applies its manifest overrides; npm uploads the
|
|
83
|
+
resulting tarball. Compatibility evidence and limitations live in
|
|
84
|
+
[why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
|
|
90
85
|
|
|
91
86
|
Started with anything other than pnpm, it prints an advisory on stderr saying so. That is
|
|
92
87
|
a warning, not an error. Nothing behaves differently because of it, and there is no flag
|
|
@@ -170,10 +165,10 @@ If Changesets, semantic-release, release-it or np already owns your releases, us
|
|
|
170
165
|
}
|
|
171
166
|
```
|
|
172
167
|
|
|
173
|
-
It
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
168
|
+
It checks a pnpm-produced preview and exits without publishing. Your release tool still
|
|
169
|
+
creates and uploads its own artifact, which may differ: this gate does not validate those
|
|
170
|
+
uploaded bytes or clean their manifest. To publish the checked bytes, configure that tool
|
|
171
|
+
to invoke `publish-clean` for the upload instead.
|
|
177
172
|
|
|
178
173
|
### Looking at what would be published
|
|
179
174
|
|
|
@@ -215,36 +210,28 @@ The checks are listed under [What it checks](#what-it-checks). The point of the
|
|
|
215
210
|
that they all read the tarball that gets uploaded, so what passed the checks and what
|
|
216
211
|
reached the registry are the same bytes, not two things that ought to match.
|
|
217
212
|
|
|
218
|
-
`--dry-run` and `--guard-only`
|
|
213
|
+
`--dry-run` and `--guard-only` validate the artifact. They do not contact the registry or
|
|
214
|
+
validate publication credentials, provenance runtime requirements or repository identity.
|
|
219
215
|
|
|
220
216
|
## Why it works this way
|
|
221
217
|
|
|
222
218
|
### Why pnpm packs, and npm publishes
|
|
223
219
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
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).
|
|
220
|
+
Use the [packer and uploader rationale](docs/why-pnpm-and-npm.md) when evaluating a replacement.
|
|
221
|
+
It covers workspace resolution, pnpm overrides, bundled dependencies and the exact-byte
|
|
222
|
+
upload requirement. Other clients also support provenance; that feature alone does not
|
|
223
|
+
establish equivalent behavior throughout this pipeline.
|
|
238
224
|
|
|
239
|
-
### Why
|
|
225
|
+
### Why cleaning happens in the tarball
|
|
240
226
|
|
|
241
|
-
The manifest is
|
|
242
|
-
|
|
227
|
+
The manifest is rewritten inside the tarball in a temporary directory.
|
|
228
|
+
The cleaner never writes the source manifest; pack hooks still run in
|
|
229
|
+
your source directory and may change it.
|
|
243
230
|
|
|
244
231
|
The obvious alternative is what a lot of hand-rolled release scripts do: edit
|
|
245
232
|
`package.json`, publish, edit it back. That's fine until something dies in the middle,
|
|
246
233
|
and then your repo is sitting on a manifest nobody meant to keep. It also can't be run
|
|
247
|
-
twice at once. Cleaning
|
|
234
|
+
twice at once. Cleaning the temporary tarball avoids those source edits.
|
|
248
235
|
|
|
249
236
|
### Why the tarball is edited instead of packed again
|
|
250
237
|
|
|
@@ -262,16 +249,15 @@ exclusion, and quietly drops files the first pack included. A package shipping a
|
|
|
262
249
|
`.gitignore` that excludes any other shipped file loses it.
|
|
263
250
|
|
|
264
251
|
Editing avoids the question. Only the `package/package.json` member is replaced. Every
|
|
265
|
-
other entry
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
timestamp
|
|
252
|
+
other entry's raw bytes are preserved. The reader resolves USTAR prefixes and PAX paths
|
|
253
|
+
before scanning; malformed or unsupported path metadata is refused. This keeps pnpm's
|
|
254
|
+
normalised metadata: owner `0:0`, a fixed
|
|
255
|
+
timestamp and file modes. A plain `tar` invocation would replace those with whatever the build
|
|
269
256
|
machine happens to have.
|
|
270
257
|
|
|
271
258
|
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.
|
|
273
|
-
|
|
274
|
-
nothing can alter the artifact after it was checked.
|
|
259
|
+
`prepack`, which is how build output reaches the package at all. npm skips package lifecycle
|
|
260
|
+
scripts for a tarball input, so upload does not rerun hooks against the checked artifact.
|
|
275
261
|
|
|
276
262
|
## What it checks
|
|
277
263
|
|
|
@@ -285,8 +271,8 @@ nothing can alter the artifact after it was checked.
|
|
|
285
271
|
silently disarms the artifact scan)
|
|
286
272
|
- the tarball holds something that should never ship: a `.env`, an `.npmrc`, `.git`,
|
|
287
273
|
`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:`,
|
|
289
|
-
|
|
274
|
+
- a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, or a local
|
|
275
|
+
dependency points outside the shipped files
|
|
290
276
|
- the manifest points `exports`, `types`, `main`, `browser`, `bin` or `sideEffects` at a
|
|
291
277
|
path that is not in the tarball
|
|
292
278
|
- rewriting the manifest changed anything else in the tarball
|
|
@@ -310,15 +296,15 @@ agrees — its registry drops the field from the metadata it serves.
|
|
|
310
296
|
|
|
311
297
|
What else goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
|
|
312
298
|
`resolutions`, and the config blocks belonging to test runners, linters, formatters,
|
|
313
|
-
coverage tools, build systems and release tools.
|
|
314
|
-
|
|
315
|
-
|
|
299
|
+
coverage tools, build systems and release tools. When `preinstall`, `install`, `postinstall`,
|
|
300
|
+
`prepare` or `uninstall` exists, the complete scripts block survives: a lifecycle may call
|
|
301
|
+
any helper script. Otherwise the development-only scripts block is removed.
|
|
316
302
|
|
|
317
303
|
Anything the tool does not recognise ships, and you get told it did:
|
|
318
304
|
|
|
319
305
|
```
|
|
320
|
-
publish-clean: these manifest fields are not recognised and
|
|
321
|
-
someToolConfig
|
|
306
|
+
publish-clean: these manifest fields are not recognised and are retained as-is:
|
|
307
|
+
"someToolConfig"
|
|
322
308
|
Strip the ones consumers do not read, and acknowledge the ones they do:
|
|
323
309
|
"publish-clean": { "devFields": ["someToolConfig"] }
|
|
324
310
|
"publish-clean": { "keepFields": ["someToolConfig"] }
|
|
@@ -356,8 +342,8 @@ choices like dist-tags on the command line and stable project policy in the mani
|
|
|
356
342
|
|
|
357
343
|
| Flag | `package.json` | What it does |
|
|
358
344
|
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
|
|
359
|
-
| `--dry-run` | - |
|
|
360
|
-
| `--guard-only` | - |
|
|
345
|
+
| `--dry-run` | - | Validate a preview artifact and print its file list and cleaned `package.json`. |
|
|
346
|
+
| `--guard-only` | - | Validate a preview artifact without the file list or manifest output. |
|
|
361
347
|
| `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
|
|
362
348
|
| `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
|
|
363
349
|
| `--skip-file-check` | `skipFileCheck` | Allow a manifest with no `files` array. |
|
|
@@ -368,8 +354,10 @@ choices like dist-tags on the command line and stable project policy in the mani
|
|
|
368
354
|
| `-h`, `--help` | - | Print usage, every flag, and the config keys. |
|
|
369
355
|
| `-v`, `--version` | - | Print the installed version. |
|
|
370
356
|
|
|
371
|
-
Arguments after `--`
|
|
372
|
-
|
|
357
|
+
Arguments after `--` accept publication options only; `--help` lists them. Extra package
|
|
358
|
+
operands, workspace selectors, unknown options and values starting with `-` are rejected
|
|
359
|
+
so npm cannot substitute an unchecked package. For a filename starting with `-`, use `./`.
|
|
360
|
+
Pass the dist-tag explicitly: `--tag latest` for a normal public release.
|
|
373
361
|
|
|
374
362
|
A few of these deserve a sentence more.
|
|
375
363
|
|
|
@@ -379,6 +367,8 @@ every mode, before the publish, so you get the validated artifact even if the up
|
|
|
379
367
|
|
|
380
368
|
`registry` pins where the package goes, so it cannot end up on whatever registry the
|
|
381
369
|
machine happens to be pointed at.
|
|
370
|
+
Registry URLs must not contain usernames or passwords, including scoped destinations in
|
|
371
|
+
`publishConfig`. Configure npm authentication in npm configuration instead.
|
|
382
372
|
|
|
383
373
|
`skipFileCheck` and `allowSuspicious` are deliberately two switches. A missing `files`
|
|
384
374
|
array is a manifest convention some packages do not follow; tests or a lockfile in the
|
|
@@ -400,8 +390,8 @@ that.
|
|
|
400
390
|
|
|
401
391
|
It isn't a release manager. It won't pick your version number, write a changelog, tag
|
|
402
392
|
anything, push a commit, create a GitHub release, or set up trusted publishing for you. It
|
|
403
|
-
|
|
404
|
-
release manager and a validator; the next section names them.
|
|
393
|
+
checks declared paths, not whether the JavaScript executes or the type declarations work
|
|
394
|
+
for every consumer. Pair it with a release manager and a validator; the next section names them.
|
|
405
395
|
|
|
406
396
|
It can't publish a package that uses `bundleDependencies`. pnpm links dependencies rather
|
|
407
397
|
than copying them, so it has nothing to bundle and refuses:
|
|
@@ -410,9 +400,9 @@ than copying them, so it has nothing to bundle and refuses:
|
|
|
410
400
|
Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
|
|
411
401
|
```
|
|
412
402
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
403
|
+
A hoisted layout can let pnpm bundle dependencies, but this tool still refuses the resulting
|
|
404
|
+
`node_modules` entries. Changing the linker does not bypass that artifact policy. Packages
|
|
405
|
+
that must ship bundled dependencies need a different publication policy.
|
|
416
406
|
|
|
417
407
|
## How it compares
|
|
418
408
|
|
|
@@ -420,20 +410,18 @@ is loud and tells you the fix.
|
|
|
420
410
|
art, and the reason this package exists at all. It copies your source tree into a temp
|
|
421
411
|
directory, deletes the files and fields it recognises, and publishes that.
|
|
422
412
|
|
|
423
|
-
|
|
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
|
|
413
|
+
`publish-clean` starts from what `pnpm pack` produced, which is the file
|
|
426
414
|
list your package manager would have shipped, including `files`, `.npmignore`, packlist
|
|
427
415
|
rules and resolved `workspace:` specs. Only the manifest is rewritten after that, and the
|
|
428
|
-
result is validated again before upload.
|
|
416
|
+
result is validated again before upload.
|
|
429
417
|
|
|
430
418
|
Release managers ([Changesets](https://github.com/changesets/changesets),
|
|
431
419
|
[release-please](https://github.com/googleapis/release-please),
|
|
432
420
|
[semantic-release](https://github.com/semantic-release/semantic-release),
|
|
433
421
|
[release-it](https://github.com/release-it/release-it),
|
|
434
422
|
[np](https://github.com/sindresorhus/np)) pick versions, write changelogs, tag, and call
|
|
435
|
-
`npm publish`.
|
|
436
|
-
|
|
423
|
+
`npm publish`. See the `--guard-only` setup above for its preview-only boundary; configure
|
|
424
|
+
the upload through `publish-clean` when the release must use the checked artifact.
|
|
437
425
|
|
|
438
426
|
[`publint`](https://publint.dev) and
|
|
439
427
|
[`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
|