@anizoptera/publish-clean 0.7.2 → 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.
Files changed (3) hide show
  1. package/README.md +54 -66
  2. package/dist/cli.js +598 -369
  3. 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
- Your working tree is never modified. If the artifact still has something in it that should
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 packs a smaller tarball
64
+ ### Running it under Bun
65
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**:
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
- 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.
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
- 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).
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 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.
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` run the whole pipeline and stop before the publish.
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
- 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).
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 the manifest is cleaned on a copy
225
+ ### Why cleaning happens in the tarball
240
226
 
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.
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 a copy has neither problem and costs a directory in `/tmp`.
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 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
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. 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.
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:`, which
289
- nobody outside your repo can install
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. Scripts go too, apart from the install
314
- lifecycle ones a consumer actually runs: `preinstall`, `install`, `postinstall`,
315
- `prepare` and `uninstall`.
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 were published as-is:
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` | - | 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. |
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 `--` go to `npm publish`. Pass the dist-tag explicitly: `--tag latest` for
372
- a normal public release.
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
- 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.
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
- 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.
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
- 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
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. clean-publish does not re-check its output.
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`. None of them look inside the tarball. Use one of them together with this,
436
- via the `--guard-only` setup above.
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)