@anizoptera/publish-clean 0.2.0 → 0.4.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 +402 -158
  2. package/dist/cli.js +435 -169
  3. package/package.json +7 -8
package/README.md CHANGED
@@ -1,121 +1,378 @@
1
1
  # @anizoptera/publish-clean
2
2
 
3
+ Publish npm packages with a consumer-only `package.json`. Refuses to ship a `.env`, a
4
+ private key, or an unresolved workspace dependency.
5
+
3
6
  [![npm version](https://img.shields.io/npm/v/@anizoptera/publish-clean?label=npm)](https://www.npmjs.com/package/@anizoptera/publish-clean)
7
+ [![Signed provenance](https://img.shields.io/badge/provenance-signed-2ea44f?logo=npm&logoColor=white)](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
4
8
  [![CI](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml/badge.svg?branch=main)](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml)
9
+ [![License](https://img.shields.io/github/license/Anizoptera/publish-clean)](LICENSE)
10
+
11
+ [![Runtime deps](https://img.shields.io/badge/runtime_deps-0-2ea44f)](package.json)
5
12
  [![Node >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](package.json)
6
13
  [![pnpm pack + npm publish](https://img.shields.io/badge/pnpm_pack%20%2B%20npm_publish-f69220?logo=pnpm&logoColor=white)](https://pnpm.io/cli/pack)
7
14
  [![Bun checked](https://img.shields.io/badge/Bun-checked-000000?logo=bun&logoColor=white)](https://bun.sh/docs/cli/test)
8
- [![Runtime deps](https://img.shields.io/badge/runtime_deps-0-2ea44f)](package.json)
9
- [![License](https://img.shields.io/github/license/Anizoptera/publish-clean)](LICENSE)
10
15
 
11
- Publish a pnpm package from the tarball you actually intend to ship.
16
+ When you run `npm publish`, two things ship that you probably did not mean to ship.
12
17
 
13
- This is pnpm-first on purpose. `publish-clean` is built for packages that rely on
14
- pnpm workspace, catalog, and publish behavior.
18
+ The first is your `package.json`. It is a development manifest. It lists devDependencies,
19
+ config blocks for your test runner and linter and formatter, `packageManager`,
20
+ `workspaces`, `pnpm` settings, release-tool settings, and every script you run locally.
21
+ npm sends all of it, unchanged, to everyone who installs your package. In a pnpm
22
+ workspace it can also send `workspace:*` and `catalog:` specs that were never resolved,
23
+ and those break the install for every consumer.
15
24
 
16
- `publish-clean` runs `pnpm pack`, opens the packed package, checks for files and
17
- manifest entries that should not ship, removes development-only metadata from
18
- the extracted copy, asks npm to pack that cleaned copy, validates the final npm
19
- tarball, and publishes that tarball with `npm publish`.
25
+ The second is files. A `.env`, an `.npmrc` with a token in it, a stray `.pem`, your
26
+ tests, `.github/`, a lockfile. You do not see the tarball before it goes out, and once a
27
+ version is published you cannot edit it. Unpublishing only works for a short window and
28
+ under conditions npm decides.
20
29
 
21
- Your working tree is left alone.
30
+ `publish-clean` packs the package, rewrites the manifest of the extracted copy down to
31
+ what consumers actually use, packs that, and publishes the result. Your working tree is
32
+ never modified. If the artifact still has something in it that should not ship, or
33
+ declares a `main`, `exports`, or `bin` path that is not in the tarball, it fails instead
34
+ of publishing.
22
35
 
23
- ## Why use this
36
+ It uses pnpm to pack and npm to publish, and cleans the manifest in between. The
37
+ reasoning behind that is in [Why it works this way](#why-it-works-this-way).
24
38
 
25
- `pnpm pack` is good at workspace packages. It understands pnpm's workspace and
26
- catalog behavior in a way generic cleanup scripts usually do not.
39
+ ## Install
27
40
 
28
- The rough edge is the packed manifest. It can still carry maintainer-only
29
- fields: dev dependencies, test runner config, workspace tooling, local
30
- overrides, and other project metadata consumers do not need.
41
+ ```bash
42
+ pnpm add -D @anizoptera/publish-clean
43
+ ```
31
44
 
32
- `publish-clean` keeps pnpm in charge of deciding what the package is, then uses
33
- npm for the final registry upload so trusted publishing and provenance follow
34
- npm's first-party path.
45
+ That installs one package and nothing else. `publish-clean` has zero runtime
46
+ dependencies: it is a single file that talks to `pnpm`, `npm` and `tar` through the
47
+ tools you already have. For something that sits on your publish path and handles your
48
+ registry credentials, that matters. A publishing tool with a dependency tree is a
49
+ supply-chain risk of its own, and this one has no transitive code to audit.
35
50
 
36
- It is for packages that want the npm artifact to contain only what was meant to
37
- ship:
51
+ Needs Node.js 20+, and `pnpm`, `npm` and `tar` on `PATH`.
38
52
 
39
- - built files
40
- - README
41
- - license
42
- - package metadata
43
- - any other files the package intentionally exposes
53
+ `--provenance` also needs Node.js 22.14+, npm 11.5.1+, and a cloud CI runner. npm will
54
+ not sign a publish that came from your laptop.
44
55
 
45
- No accidental tests, CI config, local agent docs, lockfiles, private keys, or
46
- workspace-only dependency specs.
56
+ ## Package managers
47
57
 
48
- ## Install
58
+ Start `publish-clean` with any package manager and it still packs with `pnpm` and
59
+ publishes with `npm`. So both have to be installed even if your project uses neither. The
60
+ reasons are in [Why it works this way](#why-it-works-this-way).
49
61
 
50
- ```bash
51
- pnpm add -D @anizoptera/publish-clean
62
+ | Your project | How to run it | What to expect |
63
+ | ------------ | ------------------------- | --------------------------------------------------------- |
64
+ | pnpm | `pnpm exec publish-clean` | Everything works, no warning. |
65
+ | npm | `npm exec publish-clean` | Works. Prints an advisory that packing goes through pnpm. |
66
+ | Yarn | `yarn publish-clean` | Same as npm. |
67
+ | Bun | `bunx publish-clean` | Same as npm. |
68
+
69
+ The advisory is a warning on stderr, not an error. Nothing behaves differently because of
70
+ it and there's no flag to silence it. Worth seeing once if the rest of your pipeline runs
71
+ on something other than pnpm.
72
+
73
+ For a single package all four behave the same, since nothing in the manifest needs
74
+ resolving before it ships.
75
+
76
+ Monorepos are where it matters. `pnpm pack` resolves `workspace:` and `catalog:` specs by
77
+ finding the dependency inside the packing package's own `node_modules`. What decides
78
+ whether that works is the layout your installer left behind, not which installer it was.
79
+
80
+ Bun gives each package its own `node_modules`, so a Bun workspace packs as it stands: no
81
+ `pnpm-workspace.yaml`, no switching package managers. Yarn hoists workspace dependencies
82
+ to the root instead, so pnpm doesn't find them, and Yarn PnP writes no `node_modules` at
83
+ all. Both need a `pnpm-workspace.yaml` and one `pnpm install` before packing works. A Yarn
84
+ package with no `workspace:` or `catalog:` specs needs neither, because there's nothing to
85
+ resolve.
86
+
87
+ Either way the workspace has to be installed. Pack one nobody has installed and it stops
88
+ on pnpm's own error:
89
+
90
+ ```
91
+ ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL
52
92
  ```
53
93
 
54
- Requirements:
94
+ Which is what you want. Nothing gets published, and a manifest that would have been
95
+ uninstallable for everyone never reaches the registry. Run your usual install and pack
96
+ again.
97
+
98
+ ## Pick your setup
99
+
100
+ ### Publishing a public package from CI
101
+
102
+ The common case. `id-token: write` is what lets npm sign the release. Once trusted
103
+ publishing is configured for the package, no npm token is involved at all.
104
+
105
+ ```yaml
106
+ # .github/workflows/release.yml
107
+ permissions:
108
+ contents: read
109
+ id-token: write
110
+ steps:
111
+ - uses: actions/checkout@v7
112
+ - uses: pnpm/action-setup@v6
113
+ - uses: actions/setup-node@v7
114
+ with:
115
+ node-version: "24"
116
+ registry-url: https://registry.npmjs.org
117
+ - run: pnpm install --frozen-lockfile
118
+ - run: pnpm run build
119
+ - run: pnpm exec publish-clean -- --access public --tag latest --provenance
120
+ ```
55
121
 
56
- - Node.js 20 or newer
57
- - `pnpm`
58
- - `npm`
59
- - `tar`
122
+ Always pass the dist-tag. npm defaults to `latest`, which is wrong for a prerelease and
123
+ easy to forget.
60
124
 
61
- Trusted publishing with `--provenance` requires Node.js 22.14.0 or newer and
62
- npm 11.5.1 or newer.
125
+ Publishing a package name for the first time cannot use trusted publishing at all. That
126
+ case has its own page: [docs/first-publish.md](docs/first-publish.md).
63
127
 
64
- The CLI runs on Node. This repository uses Bun for fast local checks and tests.
65
- Package creation intentionally goes through pnpm. The final registry upload
66
- goes through npm. Yarn and Bun are not treated as equivalent pack/publish
67
- backends.
128
+ To stop a stray `npm publish` from bypassing all of this:
68
129
 
69
- ## Basic setup
130
+ ```json
131
+ {
132
+ "scripts": {
133
+ "prepublishOnly": "node -e \"console.error('Publish with publish-clean.'); process.exit(1)\""
134
+ }
135
+ }
136
+ ```
137
+
138
+ ### Keeping your existing release tool
139
+
140
+ If Changesets, semantic-release, release-it or np already owns your releases, use
141
+ `publish-clean` as a check rather than replacing the publish:
70
142
 
71
143
  ```json
72
144
  {
73
145
  "scripts": {
74
- "check": "bun run typecheck && bun run test && bun run build",
75
- "prepublishOnly": "node -e \"console.error('Use pnpm run publish:clean to publish the cleaned artifact.'); process.exit(1)\"",
76
- "publish:clean": "bun run check && publish-clean -- --access public --tag latest --provenance"
77
- },
78
- "devDependencies": {
79
- "@anizoptera/publish-clean": "^0.1.0"
146
+ "prepublishOnly": "publish-clean --guard-only"
80
147
  }
81
148
  }
82
149
  ```
83
150
 
84
- Then publish with:
151
+ It packs, cleans and validates, then exits without publishing. A leaked file, an
152
+ unresolved `workspace:` spec or a `main` path that is missing from the tarball fails the
153
+ release before your tool uploads anything. The limit is real though: your tool still
154
+ publishes its own tarball, so you get the checks and not the cleaned manifest.
155
+
156
+ ### Looking at what would be published
85
157
 
86
158
  ```bash
87
- pnpm run publish:clean
159
+ pnpm exec publish-clean --dry-run
88
160
  ```
89
161
 
90
- Use a script name like `publish:clean` or `release`. Avoid naming it `publish`;
91
- that collides too easily with npm lifecycle behavior.
162
+ Prints the paths of the cleaned package and the exact tarball that would be uploaded, and
163
+ leaves both on disk. Run `tar tzf` on the tarball and read the rewritten `package.json`.
92
164
 
93
- ## Commands
165
+ ### Publishing a restricted package
166
+
167
+ ```bash
168
+ publish-clean -- --access restricted --tag latest
169
+ ```
170
+
171
+ No provenance here, because npm only signs public packages. Do not set `private: true`
172
+ either. npm treats it as a publish block, and `publish-clean` refuses it too.
173
+
174
+ ### Publishing one package out of a monorepo
94
175
 
95
176
  ```bash
96
- publish-clean --dry-run
97
- publish-clean --guard-only
98
- publish-clean --registry https://registry.npmjs.org -- --access public --tag latest --provenance
99
177
  publish-clean packages/my-lib -- --access public --tag next
100
178
  ```
101
179
 
102
- Start with `--dry-run`. It prints the temporary extracted package path, so you
103
- can inspect the cleaned package and final npm tarball that would be published.
180
+ ## How it works
181
+
182
+ ```mermaid
183
+ flowchart TD
184
+ A[Your package directory] -->|pnpm pack| B[Tarball - pnpm decides the file set]
185
+ B --> C[Extract into a temp directory]
186
+ C --> D{No leaked files?}
187
+ D --> E[Clean package.json for consumers]
188
+ E --> F{Every declared main/exports/bin/types path exists?}
189
+ F -->|replace the package.json member| G[Same tarball, cleaned manifest]
190
+ G --> H{Same files, expected manifest, still no leaks?}
191
+ H --> I[npm publish that tarball]
192
+ ```
193
+
194
+ Any gate that fails exits non-zero and nothing is published. `--dry-run` and
195
+ `--guard-only` run the whole pipeline and stop before the publish.
196
+
197
+ ## Why it works this way
198
+
199
+ ### Why pnpm does the packing
200
+
201
+ Not for file selection. pnpm, npm and Bun pick the same files: same `files` field, same
202
+ `.npmignore`, same packlist defaults. There are no file rules of this tool's own either,
203
+ so that part behaves however your package manager already behaves.
204
+
205
+ Workspaces are the reason. A dependency written as `"@acme/utils": "workspace:*"` means
206
+ "whatever version of that package is in this repo right now". It has to become a real
207
+ version range before it ships, because to a stranger installing from the registry
208
+ `workspace:*` means nothing.
209
+
210
+ npm never adopted the protocol. It won't even install it:
211
+
212
+ ```
213
+ npm error code EUNSUPPORTEDPROTOCOL
214
+ npm error Unsupported URL Type "workspace:": workspace:*
215
+ ```
216
+
217
+ `npm pack` on that same package exits 0 and writes `workspace:*` straight into the
218
+ tarball. It neither resolves it nor refuses it, and silently publishing something you
219
+ can't install is the one behaviour a release tool can't be built on.
220
+
221
+ pnpm and Bun both resolve it, and both stop loudly when they can't. Their output matches
222
+ down to `workspace:^` and `workspace:~` in `peerDependencies` and `optionalDependencies`,
223
+ and `catalog:` entries too. On correctness there is nothing to choose between them.
224
+
225
+ ### Why pnpm rather than Bun
226
+
227
+ They resolve from different places, and that decides it.
228
+
229
+ pnpm looks for the dependency in the packing package's own `node_modules` and resolves it
230
+ from there. It never asks who put it there, so a Bun workspace, which gives every package
231
+ its own `node_modules`, packs as readily as pnpm's own. Yarn hoists to the root instead
232
+ and needs the one-time setup above.
233
+
234
+ Bun reads `bun.lock`. It resolves the workspaces Bun installed and refuses the others:
235
+
236
+ ```
237
+ error: Failed to resolve workspace version for "@acme/utils" in `dependencies`.
238
+ Run `bun install` and try again.
239
+ ```
240
+
241
+ That message is accurate and useless, because in a pnpm repo `bun install` is not
242
+ something you want to be told to run. A tool that executes in other people's
243
+ repositories has to cope with the repository it finds, so it packs with the one that
244
+ reads all of them.
245
+
246
+ There's a correctness gap too, and it's the quiet kind. An aliased workspace dependency,
247
+ `"utils": "workspace:@acme/utils@*"`, has to come out the other side as an npm alias.
248
+ pnpm writes `"npm:@acme/utils@1.2.3"`. Bun 1.3.14 writes `"@acme/utils@*"`: the `npm:`
249
+ prefix is dropped and the range was never resolved. npm won't take it.
250
+
251
+ ```
252
+ npm error code EINVALIDTAGNAME
253
+ npm error Invalid tag name "is-odd@3.0.1" of package "aliased@is-odd@3.0.1"
254
+ ```
255
+
256
+ `bun pm pack` exits 0 either way, so nothing tells you until someone tries to install the
257
+ release.
258
+
259
+ One silent way to publish a broken manifest is one too many for the step you can't take
260
+ back.
261
+
262
+ pnpm also applies `publishConfig` field overrides. If your manifest points `main`, `types`
263
+ and `exports` at source for local development and overrides them to `dist` for publishing,
264
+ pnpm swaps them on the way out and drops `publishConfig` itself. npm and Bun both ignore
265
+ those overrides and publish the development paths. That one is a pnpm extension rather
266
+ than a bug in the other two, but the effect on the release is the same.
267
+
268
+ Everything else we compared came out identical: file modes including the executable bit on
269
+ `bin`, negated `files` patterns, dropped symlinks, prerelease versions, pinned
270
+ `workspace:1.2.3` ranges, named catalogs, and refusing a catalog entry that doesn't exist.
271
+
272
+ ### Why the manifest is cleaned on a copy
273
+
274
+ The tarball gets extracted into a temp directory and rewritten there. Your working tree
275
+ is never touched.
276
+
277
+ The obvious alternative is what a lot of hand-rolled release scripts do: edit
278
+ `package.json`, publish, edit it back. That's fine until something dies in the middle,
279
+ and then your repo is sitting on a manifest nobody meant to keep. It also can't be run
280
+ twice at once. Cleaning a copy has neither problem and costs a directory in `/tmp`.
104
281
 
105
- ## What happens
282
+ ### Why the tarball is edited instead of packed again
283
+
284
+ Give npm a directory and it packs during the upload, so the bytes that reach the registry
285
+ only come into existence after the last check has run. Packing first means they exist
286
+ before anything is uploaded: they can be listed, scanned for leaks, kept with
287
+ `--tarball-out` for a build attestation, and then published as themselves. What you
288
+ inspect is what ships.
289
+
290
+ So the manifest has to be cleaned inside a tarball that already exists. The obvious way is
291
+ to unpack, edit, and pack again — and it is wrong. `files` is a packing instruction, and
292
+ cleaning removes it, because it is useless to anyone installing the package. A second pack
293
+ then has nothing left to select with, falls back to your `.gitignore`/`.npmignore` for
294
+ exclusion, and quietly drops files the first pack included. A package shipping a
295
+ `.gitignore` that excludes any other shipped file loses it.
296
+
297
+ Editing avoids the whole question. Only the `package/package.json` member is replaced;
298
+ every other entry is copied without being decoded, so the file set stays exactly what pnpm
299
+ chose and entry shapes this tool does not model (pax headers for long paths, prefix
300
+ splitting) pass through untouched. It also keeps pnpm's normalised metadata — owner `0:0`,
301
+ a fixed timestamp, mode 644 — which a plain `tar` invocation would replace with the build
302
+ machine's own user and group names.
303
+
304
+ Lifecycle scripts run once, at the first pack. `pnpm pack` runs your `prepare` and
305
+ `prepack`, which is how build output reaches the package at all. Nothing runs afterwards:
306
+ npm skips `prepack`/`postpack` when it is handed a tarball rather than a directory, so
307
+ nothing can alter the artifact after it was checked.
308
+
309
+ ### Why npm does the publishing
310
+
311
+ Provenance is an npm feature. The signed attestation behind the "Built and signed on
312
+ GitHub Actions" badge is minted by the npm CLI talking to Sigstore, and trusted
313
+ publishing, which removes the long-lived token entirely, is npm's own OIDC exchange with
314
+ the registry.
315
+
316
+ No other client mints it. `bun publish` offers `--access`, `--tag`, `--otp` and
317
+ `--auth-type`, and nothing at all for provenance or attestation, so publishing through it
318
+ would cost both the badge and the tokenless path. That trade isn't on the table here:
319
+ verifiable provenance is why this package exists.
320
+
321
+ `npm publish` also takes a tarball directly, which is exactly what the previous step
322
+ produced.
323
+
324
+ ## What it checks
325
+
326
+ `publish-clean` refuses to continue when:
327
+
328
+ - the package is `private: true`
329
+ - the source package has uncommitted changes, unless disabled
330
+ - the package has no non-empty `files` array, unless disabled
331
+ - the tarball contains critical leaks like `.env`, `.npmrc`, `.git`,
332
+ `node_modules`, or private-key files
333
+ - dependency specs still use `catalog:`, `workspace:`, `link:`, or `portal:`
334
+ - declared export, type, import, browser, bin, or side-effect paths are missing
335
+ from the cleaned package
336
+ - the final npm tarball drops files that were present in the cleaned package
337
+ - trusted GitHub publication uses `--provenance` but package repository metadata
338
+ does not match the workflow repository
339
+
340
+ It warns, without stopping, when it was started by npm, Yarn or Bun rather than pnpm.
341
+ The packing still goes through pnpm, but the warning is there because the rest of your
342
+ release probably should too.
343
+
344
+ Leak checks cannot be turned off by any flag or config key.
345
+
346
+ ## What the cleaned manifest keeps
347
+
348
+ Everything a consumer or a registry reads survives: `name`, `version`, `license`,
349
+ `dependencies`, `peerDependencies` and their meta, `exports`, `main`, `module`, `types`,
350
+ `bin`, `files`, `engines`, `os`, `cpu`, `sideEffects`, `publishConfig`, and the rest of
351
+ the public surface.
352
+
353
+ What goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
354
+ `resolutions`, and the config blocks belonging to test runners, linters, formatters,
355
+ coverage tools, build systems and release tools. Scripts go too, apart from the install
356
+ lifecycle ones a consumer actually runs: `preinstall`, `install`, `postinstall`,
357
+ `prepare` and `uninstall`.
358
+
359
+ Anything the tool does not recognise ships, and you get told it did:
106
360
 
107
- ```text
108
- source package
109
- -> pnpm pack
110
- -> inspect tarball contents
111
- -> write cleaned package.json
112
- -> validate declared package paths
113
- -> npm pack the cleaned package
114
- -> validate the final npm tarball
115
- -> npm publish the final tarball
116
361
  ```
362
+ publish-clean: these manifest fields are not recognised and were published as-is:
363
+ someToolConfig
364
+ Strip the ones consumers do not read, and acknowledge the ones they do:
365
+ "publish-clean": { "devFields": ["someToolConfig"] }
366
+ "publish-clean": { "keepFields": ["someToolConfig"] }
367
+ ```
368
+
369
+ The strip list cannot know about a tool invented after it was written, so new
370
+ `package.json` keys would otherwise leak into every install unnoticed. Dropping them
371
+ instead would be worse: a key some consumer actually resolves would vanish, and you would
372
+ hear about it from a stranger's broken build rather than from your own release.
117
373
 
118
- With `--dry-run` or `--guard-only`, the publish step is skipped.
374
+ Add your own with `devFields`. Better still, run `--dry-run` and read the manifest that
375
+ would ship instead of trusting this list.
119
376
 
120
377
  ## Options
121
378
 
@@ -131,6 +388,9 @@ publish-clean [options] [package-dir] [-- npm-publish-args]
131
388
  - `--skip-file-check`: skip suspicious-file checks and the required `files`
132
389
  array check. Critical leak checks still run.
133
390
  - `--no-git-checks`: skip the source git cleanliness check.
391
+ - `--tarball-out DIR`: copy the final tarball into `DIR` before publishing. The bytes
392
+ kept are the ones that were published, so a release pipeline can attach them to a
393
+ GitHub Release or sign them with build-provenance attestation.
134
394
  - `-h`, `--help`: print usage.
135
395
 
136
396
  Arguments after `--` go to `npm publish`, which publishes the final cleaned
@@ -149,122 +409,106 @@ Stable project defaults can live in `package.json`:
149
409
  "registry": "https://registry.npmjs.org",
150
410
  "skipFileCheck": false,
151
411
  "noGitChecks": false,
152
- "devFields": ["customBuildOnlyField"]
412
+ "devFields": ["customBuildOnlyField"],
413
+ "keepFields": ["contributes"]
153
414
  }
154
415
  }
155
416
  ```
156
417
 
157
- Keep one-off choices on the command line. Dist-tags are a good example.
418
+ `registry` is written as `publishConfig.registry` on the cleaned manifest and passed to
419
+ `npm publish`, so the package cannot end up on whatever registry the machine happens to
420
+ be pointed at.
158
421
 
159
- ## What it checks
422
+ `skipFileCheck` drops the suspicious-file check and the requirement for a `files` array.
423
+ Leak checks keep running; those cannot be turned off.
160
424
 
161
- `publish-clean` refuses to continue when:
425
+ `noGitChecks` allows publishing from a dirty working tree. You need it when you publish
426
+ from a build directory or a checkout that is not a git repository.
162
427
 
163
- - the package is `private: true`
164
- - the source package has uncommitted changes, unless disabled
165
- - the package has no non-empty `files` array, unless disabled
166
- - the tarball contains critical leaks like `.env`, `.npmrc`, `.git`,
167
- `node_modules`, or private-key files
168
- - dependency specs still use `catalog:`, `workspace:`, `link:`, or `portal:`
169
- - declared export, type, import, browser, bin, or side-effect paths are missing
170
- from the cleaned package
171
- - the final npm tarball drops files that were present in the cleaned package
172
- - trusted GitHub publication uses `--provenance` but package repository metadata
173
- does not match the workflow repository
174
-
175
- It also warns when a package-manager lifecycle looks like npm, Yarn, or Bun.
176
- That warning is intentional: this tool relies on pnpm's pack and publish
177
- behavior.
178
-
179
- Critical leak checks cannot be disabled.
428
+ `devFields` lists extra manifest fields to strip, for tooling this package has not heard
429
+ of. Fields that npm or your consumers actually use, like `exports`, `bin`, `engines` and
430
+ the dependency maps, are rejected here, so a typo cannot quietly break your package.
180
431
 
181
- For restricted npm packages, use `publishConfig.access: "restricted"` or pass
182
- `--access restricted`; do not set `private: true`, because npm treats that as a
183
- publish block.
432
+ `keepFields` is the other answer to the same report: the field belongs in the published
433
+ package, stop mentioning it. A VS Code extension needs `contributes` and `publisher` in
434
+ the artifact to work, and no generic publishing tool is ever going to know that.
184
435
 
185
- ## What it removes
186
-
187
- From the extracted package manifest, `publish-clean` removes maintainer-only
188
- fields such as:
189
-
190
- - `devDependencies`
191
- - `workspaces`
192
- - `pnpm`
193
- - test, lint, format, coverage, build-system, and release-tool config fields
194
- - scripts except consumer install lifecycle scripts
195
-
196
- The repository files are not changed.
436
+ Command-line flags override this block. Keep per-release choices such as dist-tags on the
437
+ command line.
197
438
 
198
439
  ## What it does not do
199
440
 
200
- This is not a release manager. It does not choose versions, write changelogs,
201
- create tags, push commits, create GitHub releases, set up npm trusted
202
- publishing, or decide your dist-tag policy.
203
-
204
- Use tools like Changesets, release-please, semantic-release, release-it, or np
205
- for that. Use `publish-clean` as the guard or final publish command.
441
+ It isn't a release manager. It won't pick your version number, write a changelog, tag
442
+ anything, push a commit, create a GitHub release, or set up trusted publishing for you.
443
+ It also doesn't check that your entry points resolve correctly for consumers, which is
444
+ what `publint` and `@arethetypeswrong/cli` are for.
206
445
 
207
- It also does not replace package validators. Run `publint` and
208
- `@arethetypeswrong/cli` for package compatibility checks.
446
+ Pick a release manager and a validator to go with it. The next section covers which.
209
447
 
210
- ## Public and private packages
448
+ It can't publish a package that uses `bundleDependencies`. pnpm links dependencies rather
449
+ than copying them, so it has nothing to bundle and refuses:
211
450
 
212
- For public npm packages, use npm trusted publishing in GitHub Actions and pass:
213
-
214
- ```bash
215
- publish-clean -- --access public --tag latest --provenance
216
451
  ```
217
-
218
- For restricted npm packages, use the same clean artifact pipeline and usually
219
- pass:
220
-
221
- ```bash
222
- publish-clean -- --access restricted --tag latest
452
+ Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
223
453
  ```
224
454
 
225
- Do not set `private: true` for a package you intend to publish. Private package
226
- install credentials are separate from publish credentials.
227
- Trusted publishing authenticates the publish operation; it does not grant
228
- consumers access to private dependencies.
229
-
230
- ## Related tools
231
-
232
- This package borrows the useful part of
233
- [`clean-publish`](https://github.com/shashkovdanil/clean-publish): publish from
234
- a cleaned copy, not from a rewritten source tree.
235
-
236
- It deliberately stays close to package-manager behavior instead of inventing its
237
- own file-selection rules. The relevant tools and specs are
238
- [`npm-packlist`](https://github.com/npm/npm-packlist),
455
+ Doing what it says makes the package publishable again. This is the one thing you give up
456
+ by packing with pnpm, and it's a fair trade: `bundleDependencies` is rare, and the failure
457
+ is loud and tells you the fix. npm and Bun bundle correctly for a standalone package, and
458
+ neither bundles anything for a package inside a workspace, because the dependency hoists
459
+ to the workspace root where the package can't see it.
460
+
461
+ ## How it compares
462
+
463
+ [`clean-publish`](https://github.com/shashkovdanil/clean-publish) is the closest prior
464
+ art, and the reason this package exists at all. It copies your source tree into a temp
465
+ directory, deletes the files and fields it recognises, and publishes that.
466
+
467
+ The difference is where the file list comes from. clean-publish starts with your whole
468
+ source tree and subtracts, so anything its rules do not recognise gets published.
469
+ `publish-clean` starts from what `pnpm pack` produced, which is already the exact file
470
+ list your package manager would have shipped, including `files`, `.npmignore`, packlist
471
+ rules and resolved `workspace:` specs. Only the manifest is rewritten after that, and the
472
+ result is validated again before upload. clean-publish does not re-check its output.
473
+
474
+ Release managers ([Changesets](https://github.com/changesets/changesets),
475
+ [release-please](https://github.com/googleapis/release-please),
476
+ [semantic-release](https://github.com/semantic-release/semantic-release),
477
+ [release-it](https://github.com/release-it/release-it),
478
+ [np](https://github.com/sindresorhus/np)) pick versions, write changelogs, tag, and call
479
+ `npm publish`. None of them look inside the tarball. Use one of them together with this,
480
+ via the `--guard-only` setup above.
481
+
482
+ [`publint`](https://publint.dev) and
483
+ [`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
484
+ check that your entry points and type definitions resolve properly for consumers. That is
485
+ a different question from what is in the tarball. Run them as well.
486
+
487
+ `npm publish --dry-run` prints the file list and stops there. It does not clean anything
488
+ and will happily list a `.env` without complaining.
489
+
490
+ [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) proves who
491
+ published. This tool decides what gets published. They solve different halves of the same
492
+ worry, and this package is built to use both.
493
+
494
+ [`pkg-pr-new`](https://github.com/stackblitz-labs/pkg.pr.new) publishes preview builds
495
+ per commit without touching the registry. Useful next to this, unrelated to cleaning.
496
+
497
+ Underlying behaviour is defined by [`npm-packlist`](https://github.com/npm/npm-packlist),
239
498
  [`npm pack`](https://docs.npmjs.com/cli/v11/commands/npm-pack/),
240
499
  [`npm publish`](https://docs.npmjs.com/cli/v11/commands/npm-publish/),
241
- [`pnpm pack`](https://pnpm.io/cli/pack), and pnpm
500
+ [`pnpm pack`](https://pnpm.io/cli/pack) and pnpm
242
501
  [`publishConfig`](https://pnpm.io/package_json#publishconfig).
243
502
 
244
- For preview installs, see
245
- [`pkg-pr-new`](https://github.com/stackblitz-labs/pkg.pr.new). For provenance,
246
- use [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/). Both
247
- are useful layers. Neither one cleans the package contents.
248
-
249
- ## Development
503
+ ## Contributing
250
504
 
251
505
  ```bash
252
506
  bun install --frozen-lockfile
253
507
  bun run check
254
508
  ```
255
509
 
256
- Before committing workflow changes:
257
-
258
- ```bash
259
- actions-up --yes
260
- ```
261
-
262
- This package has no runtime dependencies.
263
-
264
- ## Alternatives and references
265
-
266
- - [`clean-publish`](https://github.com/shashkovdanil/clean-publish)
267
- - [`npm-packlist`](https://github.com/npm/npm-packlist)
510
+ [CONTRIBUTING.md](CONTRIBUTING.md) has the rest. Security problems go through private
511
+ reporting, not public issues: see [SECURITY.md](SECURITY.md).
268
512
 
269
513
  ## License
270
514