@anizoptera/publish-clean 0.2.0 → 0.3.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 +390 -158
- package/dist/cli.js +198 -40
- package/package.json +7 -3
package/README.md
CHANGED
|
@@ -1,121 +1,366 @@
|
|
|
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
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean)
|
|
7
|
+
[](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
|
|
4
8
|
[](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml)
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
|
|
11
|
+
[](package.json)
|
|
5
12
|
[](package.json)
|
|
6
13
|
[](https://pnpm.io/cli/pack)
|
|
7
14
|
[](https://bun.sh/docs/cli/test)
|
|
8
|
-
[](package.json)
|
|
9
|
-
[](LICENSE)
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
When you run `npm publish`, two things ship that you probably did not mean to ship.
|
|
12
17
|
|
|
13
|
-
|
|
14
|
-
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
26
|
-
catalog behavior in a way generic cleanup scripts usually do not.
|
|
39
|
+
## Install
|
|
27
40
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
41
|
+
```bash
|
|
42
|
+
pnpm add -D @anizoptera/publish-clean
|
|
43
|
+
```
|
|
31
44
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
-
|
|
37
|
-
ship:
|
|
51
|
+
Needs Node.js 20+, and `pnpm`, `npm` and `tar` on `PATH`.
|
|
38
52
|
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
46
|
-
workspace-only dependency specs.
|
|
56
|
+
## Package managers
|
|
47
57
|
|
|
48
|
-
|
|
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
|
-
|
|
51
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
57
|
-
|
|
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
|
-
|
|
62
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
"
|
|
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
|
-
|
|
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
|
|
159
|
+
pnpm exec publish-clean --dry-run
|
|
88
160
|
```
|
|
89
161
|
|
|
90
|
-
|
|
91
|
-
|
|
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
|
-
|
|
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
|
-
|
|
103
|
-
|
|
180
|
+
## How it works
|
|
181
|
+
|
|
182
|
+
```mermaid
|
|
183
|
+
flowchart TD
|
|
184
|
+
A[Your package directory] -->|pnpm pack| B[Tarball 1 - pnpm decides the file set]
|
|
185
|
+
B --> C[Extract into a temp directory]
|
|
186
|
+
C --> D{No leaked files?}
|
|
187
|
+
D --> E[Rewrite package.json for consumers]
|
|
188
|
+
E --> F{Every declared main/exports/bin/types path exists?}
|
|
189
|
+
F -->|npm pack --ignore-scripts| G[Tarball 2 - the bytes that ship]
|
|
190
|
+
G --> H{Same files, same manifest, still no leaks?}
|
|
191
|
+
H --> I[npm publish tarball 2]
|
|
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.
|
|
104
233
|
|
|
105
|
-
|
|
234
|
+
Bun reads `bun.lock`. It resolves the workspaces Bun installed and refuses the others:
|
|
106
235
|
|
|
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
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`.
|
|
281
|
+
|
|
282
|
+
### Why npm packs the cleaned copy a second time
|
|
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.
|
|
286
|
+
|
|
287
|
+
Packing first means they exist before anything is uploaded. They can be listed, compared
|
|
288
|
+
against the cleaned directory, scanned for leaks again, kept with `--tarball-out` for a
|
|
289
|
+
build attestation, and then published as themselves. What you inspect is what ships. If
|
|
290
|
+
cleaning ever dropped a real file, you find out here instead of from a bug report.
|
|
117
291
|
|
|
118
|
-
|
|
292
|
+
The second pack uses `--ignore-scripts`. The first one doesn't, deliberately: `pnpm pack`
|
|
293
|
+
runs your `prepare` and `prepack` scripts, which is how your build output gets into the
|
|
294
|
+
package at all. Running them again on the cleaned copy could only change it after it was
|
|
295
|
+
checked.
|
|
296
|
+
|
|
297
|
+
### Why npm does the publishing
|
|
298
|
+
|
|
299
|
+
Provenance is an npm feature. The signed attestation behind the "Built and signed on
|
|
300
|
+
GitHub Actions" badge is minted by the npm CLI talking to Sigstore, and trusted
|
|
301
|
+
publishing, which removes the long-lived token entirely, is npm's own OIDC exchange with
|
|
302
|
+
the registry.
|
|
303
|
+
|
|
304
|
+
No other client mints it. `bun publish` offers `--access`, `--tag`, `--otp` and
|
|
305
|
+
`--auth-type`, and nothing at all for provenance or attestation, so publishing through it
|
|
306
|
+
would cost both the badge and the tokenless path. That trade isn't on the table here:
|
|
307
|
+
verifiable provenance is why this package exists.
|
|
308
|
+
|
|
309
|
+
`npm publish` also takes a tarball directly, which is exactly what the previous step
|
|
310
|
+
produced.
|
|
311
|
+
|
|
312
|
+
## What it checks
|
|
313
|
+
|
|
314
|
+
`publish-clean` refuses to continue when:
|
|
315
|
+
|
|
316
|
+
- the package is `private: true`
|
|
317
|
+
- the source package has uncommitted changes, unless disabled
|
|
318
|
+
- the package has no non-empty `files` array, unless disabled
|
|
319
|
+
- the tarball contains critical leaks like `.env`, `.npmrc`, `.git`,
|
|
320
|
+
`node_modules`, or private-key files
|
|
321
|
+
- dependency specs still use `catalog:`, `workspace:`, `link:`, or `portal:`
|
|
322
|
+
- declared export, type, import, browser, bin, or side-effect paths are missing
|
|
323
|
+
from the cleaned package
|
|
324
|
+
- the final npm tarball drops files that were present in the cleaned package
|
|
325
|
+
- trusted GitHub publication uses `--provenance` but package repository metadata
|
|
326
|
+
does not match the workflow repository
|
|
327
|
+
|
|
328
|
+
It warns, without stopping, when it was started by npm, Yarn or Bun rather than pnpm.
|
|
329
|
+
The packing still goes through pnpm, but the warning is there because the rest of your
|
|
330
|
+
release probably should too.
|
|
331
|
+
|
|
332
|
+
Leak checks cannot be turned off by any flag or config key.
|
|
333
|
+
|
|
334
|
+
## What the cleaned manifest keeps
|
|
335
|
+
|
|
336
|
+
Everything a consumer or a registry reads survives: `name`, `version`, `license`,
|
|
337
|
+
`dependencies`, `peerDependencies` and their meta, `exports`, `main`, `module`, `types`,
|
|
338
|
+
`bin`, `files`, `engines`, `os`, `cpu`, `sideEffects`, `publishConfig`, and the rest of
|
|
339
|
+
the public surface.
|
|
340
|
+
|
|
341
|
+
What goes: `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
|
|
342
|
+
`resolutions`, and the config blocks belonging to test runners, linters, formatters,
|
|
343
|
+
coverage tools, build systems and release tools. Scripts go too, apart from the install
|
|
344
|
+
lifecycle ones a consumer actually runs: `preinstall`, `install`, `postinstall`,
|
|
345
|
+
`prepare` and `uninstall`.
|
|
346
|
+
|
|
347
|
+
Anything the tool does not recognise ships, and you get told it did:
|
|
348
|
+
|
|
349
|
+
```
|
|
350
|
+
publish-clean: these manifest fields are not recognised and were published as-is:
|
|
351
|
+
someToolConfig
|
|
352
|
+
Strip the ones consumers do not read, and acknowledge the ones they do:
|
|
353
|
+
"publish-clean": { "devFields": ["someToolConfig"] }
|
|
354
|
+
"publish-clean": { "keepFields": ["someToolConfig"] }
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
The strip list cannot know about a tool invented after it was written, so new
|
|
358
|
+
`package.json` keys would otherwise leak into every install unnoticed. Dropping them
|
|
359
|
+
instead would be worse: a key some consumer actually resolves would vanish, and you would
|
|
360
|
+
hear about it from a stranger's broken build rather than from your own release.
|
|
361
|
+
|
|
362
|
+
Add your own with `devFields`. Better still, run `--dry-run` and read the manifest that
|
|
363
|
+
would ship instead of trusting this list.
|
|
119
364
|
|
|
120
365
|
## Options
|
|
121
366
|
|
|
@@ -131,6 +376,9 @@ publish-clean [options] [package-dir] [-- npm-publish-args]
|
|
|
131
376
|
- `--skip-file-check`: skip suspicious-file checks and the required `files`
|
|
132
377
|
array check. Critical leak checks still run.
|
|
133
378
|
- `--no-git-checks`: skip the source git cleanliness check.
|
|
379
|
+
- `--tarball-out DIR`: copy the final tarball into `DIR` before publishing. The bytes
|
|
380
|
+
kept are the ones that were published, so a release pipeline can attach them to a
|
|
381
|
+
GitHub Release or sign them with build-provenance attestation.
|
|
134
382
|
- `-h`, `--help`: print usage.
|
|
135
383
|
|
|
136
384
|
Arguments after `--` go to `npm publish`, which publishes the final cleaned
|
|
@@ -149,122 +397,106 @@ Stable project defaults can live in `package.json`:
|
|
|
149
397
|
"registry": "https://registry.npmjs.org",
|
|
150
398
|
"skipFileCheck": false,
|
|
151
399
|
"noGitChecks": false,
|
|
152
|
-
"devFields": ["customBuildOnlyField"]
|
|
400
|
+
"devFields": ["customBuildOnlyField"],
|
|
401
|
+
"keepFields": ["contributes"]
|
|
153
402
|
}
|
|
154
403
|
}
|
|
155
404
|
```
|
|
156
405
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
`publish-clean` refuses to continue when:
|
|
406
|
+
`registry` is written as `publishConfig.registry` on the cleaned manifest and passed to
|
|
407
|
+
`npm publish`, so the package cannot end up on whatever registry the machine happens to
|
|
408
|
+
be pointed at.
|
|
162
409
|
|
|
163
|
-
- the
|
|
164
|
-
|
|
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
|
|
410
|
+
`skipFileCheck` drops the suspicious-file check and the requirement for a `files` array.
|
|
411
|
+
Leak checks keep running; those cannot be turned off.
|
|
174
412
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
behavior.
|
|
413
|
+
`noGitChecks` allows publishing from a dirty working tree. You need it when you publish
|
|
414
|
+
from a build directory or a checkout that is not a git repository.
|
|
178
415
|
|
|
179
|
-
|
|
416
|
+
`devFields` lists extra manifest fields to strip, for tooling this package has not heard
|
|
417
|
+
of. Fields that npm or your consumers actually use, like `exports`, `bin`, `engines` and
|
|
418
|
+
the dependency maps, are rejected here, so a typo cannot quietly break your package.
|
|
180
419
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
420
|
+
`keepFields` is the other answer to the same report: the field belongs in the published
|
|
421
|
+
package, stop mentioning it. A VS Code extension needs `contributes` and `publisher` in
|
|
422
|
+
the artifact to work, and no generic publishing tool is ever going to know that.
|
|
184
423
|
|
|
185
|
-
|
|
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.
|
|
424
|
+
Command-line flags override this block. Keep per-release choices such as dist-tags on the
|
|
425
|
+
command line.
|
|
197
426
|
|
|
198
427
|
## What it does not do
|
|
199
428
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
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.
|
|
429
|
+
It isn't a release manager. It won't pick your version number, write a changelog, tag
|
|
430
|
+
anything, push a commit, create a GitHub release, or set up trusted publishing for you.
|
|
431
|
+
It also doesn't check that your entry points resolve correctly for consumers, which is
|
|
432
|
+
what `publint` and `@arethetypeswrong/cli` are for.
|
|
206
433
|
|
|
207
|
-
|
|
208
|
-
`@arethetypeswrong/cli` for package compatibility checks.
|
|
434
|
+
Pick a release manager and a validator to go with it. The next section covers which.
|
|
209
435
|
|
|
210
|
-
|
|
436
|
+
It can't publish a package that uses `bundleDependencies`. pnpm links dependencies rather
|
|
437
|
+
than copying them, so it has nothing to bundle and refuses:
|
|
211
438
|
|
|
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
439
|
```
|
|
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
|
|
440
|
+
Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
|
|
223
441
|
```
|
|
224
442
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
[`clean-publish`](https://github.com/shashkovdanil/clean-publish)
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
443
|
+
Doing what it says makes the package publishable again. This is the one thing you give up
|
|
444
|
+
by packing with pnpm, and it's a fair trade: `bundleDependencies` is rare, and the failure
|
|
445
|
+
is loud and tells you the fix. npm and Bun bundle correctly for a standalone package, and
|
|
446
|
+
neither bundles anything for a package inside a workspace, because the dependency hoists
|
|
447
|
+
to the workspace root where the package can't see it.
|
|
448
|
+
|
|
449
|
+
## How it compares
|
|
450
|
+
|
|
451
|
+
[`clean-publish`](https://github.com/shashkovdanil/clean-publish) is the closest prior
|
|
452
|
+
art, and the reason this package exists at all. It copies your source tree into a temp
|
|
453
|
+
directory, deletes the files and fields it recognises, and publishes that.
|
|
454
|
+
|
|
455
|
+
The difference is where the file list comes from. clean-publish starts with your whole
|
|
456
|
+
source tree and subtracts, so anything its rules do not recognise gets published.
|
|
457
|
+
`publish-clean` starts from what `pnpm pack` produced, which is already the exact file
|
|
458
|
+
list your package manager would have shipped, including `files`, `.npmignore`, packlist
|
|
459
|
+
rules and resolved `workspace:` specs. Only the manifest is rewritten after that, and the
|
|
460
|
+
result is validated again before upload. clean-publish does not re-check its output.
|
|
461
|
+
|
|
462
|
+
Release managers ([Changesets](https://github.com/changesets/changesets),
|
|
463
|
+
[release-please](https://github.com/googleapis/release-please),
|
|
464
|
+
[semantic-release](https://github.com/semantic-release/semantic-release),
|
|
465
|
+
[release-it](https://github.com/release-it/release-it),
|
|
466
|
+
[np](https://github.com/sindresorhus/np)) pick versions, write changelogs, tag, and call
|
|
467
|
+
`npm publish`. None of them look inside the tarball. Use one of them together with this,
|
|
468
|
+
via the `--guard-only` setup above.
|
|
469
|
+
|
|
470
|
+
[`publint`](https://publint.dev) and
|
|
471
|
+
[`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
|
|
472
|
+
check that your entry points and type definitions resolve properly for consumers. That is
|
|
473
|
+
a different question from what is in the tarball. Run them as well.
|
|
474
|
+
|
|
475
|
+
`npm publish --dry-run` prints the file list and stops there. It does not clean anything
|
|
476
|
+
and will happily list a `.env` without complaining.
|
|
477
|
+
|
|
478
|
+
[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) proves who
|
|
479
|
+
published. This tool decides what gets published. They solve different halves of the same
|
|
480
|
+
worry, and this package is built to use both.
|
|
481
|
+
|
|
482
|
+
[`pkg-pr-new`](https://github.com/stackblitz-labs/pkg.pr.new) publishes preview builds
|
|
483
|
+
per commit without touching the registry. Useful next to this, unrelated to cleaning.
|
|
484
|
+
|
|
485
|
+
Underlying behaviour is defined by [`npm-packlist`](https://github.com/npm/npm-packlist),
|
|
239
486
|
[`npm pack`](https://docs.npmjs.com/cli/v11/commands/npm-pack/),
|
|
240
487
|
[`npm publish`](https://docs.npmjs.com/cli/v11/commands/npm-publish/),
|
|
241
|
-
[`pnpm pack`](https://pnpm.io/cli/pack)
|
|
488
|
+
[`pnpm pack`](https://pnpm.io/cli/pack) and pnpm
|
|
242
489
|
[`publishConfig`](https://pnpm.io/package_json#publishconfig).
|
|
243
490
|
|
|
244
|
-
|
|
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
|
|
491
|
+
## Contributing
|
|
250
492
|
|
|
251
493
|
```bash
|
|
252
494
|
bun install --frozen-lockfile
|
|
253
495
|
bun run check
|
|
254
496
|
```
|
|
255
497
|
|
|
256
|
-
|
|
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)
|
|
498
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) has the rest. Security problems go through private
|
|
499
|
+
reporting, not public issues: see [SECURITY.md](SECURITY.md).
|
|
268
500
|
|
|
269
501
|
## License
|
|
270
502
|
|
package/dist/cli.js
CHANGED
|
@@ -6,7 +6,7 @@ import { tmpdir } from "node:os";
|
|
|
6
6
|
import path from "node:path";
|
|
7
7
|
import { parseArgs } from "node:util";
|
|
8
8
|
//#region src/cli.ts
|
|
9
|
-
const DEV_FIELDS = new Set(/* @__PURE__ */ "devDependencies.overrides.resolutions.ava.c8.jest.mocha.nyc.tap.vitest.babel.biome.browserslist.eslintConfig.eslintIgnore.prettier.remarkConfig.xo.commitlint.husky.lint-staged.simple-git-hooks.clean-publish.publish-clean.semantic-release.packageManager.pnpm.volta.workspaces.nx.turbo".split(".")), CONSUMER_SCRIPTS = new Set([
|
|
9
|
+
const DEV_FIELDS = /* @__PURE__ */ new Set(/* @__PURE__ */ "$schema.catalog.catalogs.patchedDependencies.private.stylelint.trustedDependencies.wireit.devDependencies.overrides.resolutions.ava.c8.jest.mocha.nyc.tap.vitest.babel.biome.browserslist.eslintConfig.eslintIgnore.prettier.remarkConfig.xo.commitlint.husky.lint-staged.simple-git-hooks.clean-publish.publish-clean.semantic-release.packageManager.pnpm.volta.workspaces.nx.turbo".split(".")), CONSUMER_SCRIPTS = /* @__PURE__ */ new Set([
|
|
10
10
|
"preinstall",
|
|
11
11
|
"install",
|
|
12
12
|
"postinstall",
|
|
@@ -24,7 +24,7 @@ const DEV_FIELDS = new Set(/* @__PURE__ */ "devDependencies.overrides.resolution
|
|
|
24
24
|
"workspace:",
|
|
25
25
|
"link:",
|
|
26
26
|
"portal:"
|
|
27
|
-
], RUNTIME_MANIFEST_FIELDS = new Set([
|
|
27
|
+
], RUNTIME_MANIFEST_FIELDS = /* @__PURE__ */ new Set([
|
|
28
28
|
...DEP_FIELDS,
|
|
29
29
|
"bin",
|
|
30
30
|
"browser",
|
|
@@ -35,11 +35,11 @@ const DEV_FIELDS = new Set(/* @__PURE__ */ "devDependencies.overrides.resolution
|
|
|
35
35
|
"exports",
|
|
36
36
|
"files",
|
|
37
37
|
"imports",
|
|
38
|
+
"libc",
|
|
38
39
|
"license",
|
|
39
40
|
"main",
|
|
40
41
|
"module",
|
|
41
42
|
"name",
|
|
42
|
-
"optionalDependencies",
|
|
43
43
|
"os",
|
|
44
44
|
"peerDependenciesMeta",
|
|
45
45
|
"publishConfig",
|
|
@@ -49,23 +49,105 @@ const DEV_FIELDS = new Set(/* @__PURE__ */ "devDependencies.overrides.resolution
|
|
|
49
49
|
"typesVersions",
|
|
50
50
|
"typings",
|
|
51
51
|
"version"
|
|
52
|
-
]),
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
52
|
+
]), REGISTRY_MANIFEST_FIELDS = /* @__PURE__ */ new Set([
|
|
53
|
+
"author",
|
|
54
|
+
"bugs",
|
|
55
|
+
"config",
|
|
56
|
+
"contributors",
|
|
57
|
+
"deno",
|
|
58
|
+
"description",
|
|
59
|
+
"directories",
|
|
60
|
+
"funding",
|
|
61
|
+
"gitHead",
|
|
62
|
+
"homepage",
|
|
63
|
+
"jsdelivr",
|
|
64
|
+
"keywords",
|
|
65
|
+
"maintainers",
|
|
66
|
+
"man",
|
|
67
|
+
"preferGlobal",
|
|
68
|
+
"react-native",
|
|
69
|
+
"repository",
|
|
70
|
+
"sass",
|
|
71
|
+
"scripts",
|
|
72
|
+
"style",
|
|
73
|
+
"styleModule",
|
|
74
|
+
"svelte",
|
|
75
|
+
"unpkg"
|
|
76
|
+
]);
|
|
77
|
+
/**
|
|
78
|
+
* Names the fields that survived cleaning without anyone recognising them.
|
|
79
|
+
*
|
|
80
|
+
* The strip list can only ever describe tools that existed when it was written, so every
|
|
81
|
+
* new `package.json` key some tool invents ships to consumers until a human notices. This
|
|
82
|
+
* cannot be fixed by keeping only recognised fields: that would silently drop a key some
|
|
83
|
+
* consumer genuinely resolves, and the breakage would surface in a stranger's project
|
|
84
|
+
* rather than here. So the field ships, and the maintainer is told it did, with the exact
|
|
85
|
+
* config that would drop it next time.
|
|
86
|
+
*
|
|
87
|
+
* Reported on stderr because it is advice about the package, not an error in it. Nothing
|
|
88
|
+
* about the published artifact depends on whether anyone reads this.
|
|
89
|
+
*/
|
|
90
|
+
/**
|
|
91
|
+
* Refuses a published manifest that lost a field the source declared and consumers read.
|
|
92
|
+
*
|
|
93
|
+
* Every other check here asks whether something got in that should not have. This asks the
|
|
94
|
+
* opposite, and nothing else does: cleaning is subtraction, so the way it fails is by
|
|
95
|
+
* taking too much. A dropped `repository` breaks provenance verification, a dropped
|
|
96
|
+
* `exports` makes the package unimportable, and neither leaves any trace in the artifact
|
|
97
|
+
* to notice later. The registry keeps the version forever either way.
|
|
98
|
+
*
|
|
99
|
+
* Compared against the *final* tarball rather than the cleaned directory, so a loss
|
|
100
|
+
* introduced by the re-pack is caught as well as one introduced by stripping.
|
|
101
|
+
*
|
|
102
|
+
* `devFields` entries are exempt: removing those was the request. `scripts` is exempt
|
|
103
|
+
* because it is rewritten rather than removed, down to the install lifecycle hooks a
|
|
104
|
+
* consumer runs, and a package whose scripts are all developer-only correctly ends up with
|
|
105
|
+
* none.
|
|
106
|
+
*/
|
|
107
|
+
function assertNoLostConsumerFields(sourcePkg, finalPkg, removedOnRequest) {
|
|
108
|
+
let expected = /* @__PURE__ */ new Set([
|
|
109
|
+
...DEV_FIELDS,
|
|
110
|
+
...removedOnRequest,
|
|
111
|
+
"scripts"
|
|
112
|
+
]), lost = Object.keys(sourcePkg).filter((field) => (RUNTIME_MANIFEST_FIELDS.has(field) || REGISTRY_MANIFEST_FIELDS.has(field)) && !expected.has(field) && !(field in finalPkg));
|
|
113
|
+
if (lost.length > 0) throw new PublishCleanError(`The published manifest is missing fields the source declared and consumers read:\n${lost.join("\n")}`);
|
|
114
|
+
}
|
|
115
|
+
function reportUnrecognizedFields(pkg, kept) {
|
|
116
|
+
let acknowledged = new Set(kept), unrecognized = Object.keys(pkg).filter((field) => !RUNTIME_MANIFEST_FIELDS.has(field) && !REGISTRY_MANIFEST_FIELDS.has(field) && !acknowledged.has(field));
|
|
117
|
+
unrecognized.length !== 0 && console.warn(`publish-clean: these manifest fields are not recognised and were published as-is:\n${unrecognized.map((field) => ` ${field}`).join("\n")}\nStrip the ones consumers do not read, and acknowledge the ones they do:\n "publish-clean": { "devFields": [${unrecognized.map((f) => `"${f}"`).join(", ")}] }\n "publish-clean": { "keepFields": [${unrecognized.map((f) => `"${f}"`).join(", ")}] }`);
|
|
118
|
+
}
|
|
119
|
+
/**
|
|
120
|
+
* Content that must never reach a registry. Matched against tarball paths with the
|
|
121
|
+
* `package/` prefix already stripped, so `^` means the package root.
|
|
122
|
+
*
|
|
123
|
+
* Case-insensitive throughout, because the filesystems most packages are built on are
|
|
124
|
+
* too. On macOS and Windows `Server.PEM` and `server.pem` are the same file, so a
|
|
125
|
+
* case-sensitive guard refuses one and publishes the other, which is worse than no guard:
|
|
126
|
+
* it reads as coverage.
|
|
127
|
+
*
|
|
128
|
+
* Private keys are matched by extension and, separately, by exact filename. SSH keys carry
|
|
129
|
+
* no extension at all, and `id_rsa` is the most common private-key filename there is. The
|
|
130
|
+
* exact-name form deliberately does not match `id_rsa.pub`, which is public by design and
|
|
131
|
+
* legitimate to ship.
|
|
132
|
+
*/
|
|
133
|
+
const CRITICAL_PATTERNS = [
|
|
134
|
+
/(?:^|\/)node_modules(?:\/|$)/i,
|
|
135
|
+
/(?:^|\/)\.git(?:\/|$)/i,
|
|
136
|
+
/(?:^|\/)\.env(?:\.|$)/i,
|
|
137
|
+
/(?:^|\/)\.npmrc$/i,
|
|
138
|
+
/\.(?:pem|key|p12|pfx|p8|ppk|jks|keystore)$/i,
|
|
139
|
+
/(?:^|\/)id_(?:rsa|dsa|ecdsa|ed25519)$/i
|
|
58
140
|
], SUSPICIOUS_PATTERNS = [
|
|
59
141
|
/(?:^|\/)(?:test|tests|__tests__|__snapshots__|coverage)(?:\/|$)/,
|
|
60
142
|
/(?:^|\/)\.github(?:\/|$)/,
|
|
61
143
|
/(?:^|\/)tsconfig[^/]*\.json$/,
|
|
62
144
|
/(?:^|\/)(?:pnpm-lock\.yaml|bun\.lock|package-lock\.json)$/,
|
|
63
145
|
/\.(?:test|spec)\.[cm]?[jt]sx?$/
|
|
64
|
-
], PUBLISH_ADVISORY = "publish-clean
|
|
146
|
+
], PUBLISH_ADVISORY = "publish-clean packs with pnpm: it resolves workspace: and catalog: specs from the packing package's own node_modules, so a Bun workspace works as-is and a Yarn one needs a pnpm-workspace.yaml plus one pnpm install. npm packs those specs unresolved.", MIN_TRUSTED_NPM_VERSION = [
|
|
65
147
|
11,
|
|
66
148
|
5,
|
|
67
149
|
1
|
|
68
|
-
];
|
|
150
|
+
], TOOL_PROBE_TIMEOUT_MS = 1e4;
|
|
69
151
|
var PublishCleanError = class extends Error {
|
|
70
152
|
constructor(message, options) {
|
|
71
153
|
super(message, options), this.name = "PublishCleanError";
|
|
@@ -109,11 +191,60 @@ function outputFromError(error, key) {
|
|
|
109
191
|
let output = error[key];
|
|
110
192
|
return typeof output == "string" ? output.trim() : output instanceof Uint8Array ? Buffer.from(output).toString("utf8").trim() : "";
|
|
111
193
|
}
|
|
194
|
+
/**
|
|
195
|
+
* Runs a command with its streams attached to this process instead of captured.
|
|
196
|
+
*
|
|
197
|
+
* Reserved for `npm publish`. Every other command here is run for its output or its
|
|
198
|
+
* effect, but the publish is the one irreversible step, and npm's output is the only
|
|
199
|
+
* receipt the operator gets: the version that went out, the tarball size, the integrity
|
|
200
|
+
* hash, and the registry's own wording when it refuses. `run` would swallow all of it on
|
|
201
|
+
* success and hold the failure text until the process exits, which in CI means a log
|
|
202
|
+
* that says nothing about the one action that cannot be undone.
|
|
203
|
+
*/
|
|
204
|
+
function runAttached(command, args, cwd) {
|
|
205
|
+
execFileSync(command, [...args], {
|
|
206
|
+
cwd,
|
|
207
|
+
stdio: [
|
|
208
|
+
"ignore",
|
|
209
|
+
"inherit",
|
|
210
|
+
"inherit"
|
|
211
|
+
]
|
|
212
|
+
});
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* A required tool can fail three ways, and each one asks something different of the
|
|
216
|
+
* reader, so the probe reports what it observed instead of assuming the common case.
|
|
217
|
+
* A version-manager shim (asdf, mise, volta, corepack) resolves in PATH and still refuses
|
|
218
|
+
* to run when no version is pinned; calling that absence sends the reader to verify the
|
|
219
|
+
* one thing already correct, and `which pnpm` then agrees with them and not with us. The
|
|
220
|
+
* shim's own message names the fix, so it is forwarded rather than replaced.
|
|
221
|
+
*/
|
|
222
|
+
function toolFailureReason(cause) {
|
|
223
|
+
if (isObject(cause)) {
|
|
224
|
+
if (cause.code === "ENOENT") return "is not available in PATH";
|
|
225
|
+
if (cause.code === "ETIMEDOUT") return `did not answer --version within ${TOOL_PROBE_TIMEOUT_MS}ms`;
|
|
226
|
+
}
|
|
227
|
+
let stderr = outputFromError(cause, "stderr");
|
|
228
|
+
return `is present but failed to run${stderr ? `: ${stderr}` : ""}`;
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* The probe is bounded because a wedged shim would otherwise hang the publish with no end:
|
|
232
|
+
* `execFileSync` blocks this thread, so no timer here could ever interrupt it. The bound
|
|
233
|
+
* belongs on the spawn itself. It stays generous because the only job is to separate a
|
|
234
|
+
* tool that answers from one that never will.
|
|
235
|
+
*/
|
|
112
236
|
function requireTool(name) {
|
|
113
237
|
try {
|
|
114
|
-
execFileSync(name, ["--version"], {
|
|
238
|
+
execFileSync(name, ["--version"], {
|
|
239
|
+
stdio: [
|
|
240
|
+
"ignore",
|
|
241
|
+
"ignore",
|
|
242
|
+
"pipe"
|
|
243
|
+
],
|
|
244
|
+
timeout: TOOL_PROBE_TIMEOUT_MS
|
|
245
|
+
});
|
|
115
246
|
} catch (cause) {
|
|
116
|
-
throw new PublishCleanError(`Required tool "${name}"
|
|
247
|
+
throw new PublishCleanError(`Required tool "${name}" ${toolFailureReason(cause)}.`, { cause });
|
|
117
248
|
}
|
|
118
249
|
}
|
|
119
250
|
function npmVersion() {
|
|
@@ -209,14 +340,22 @@ function stripManifest(pkg, extraDevFields) {
|
|
|
209
340
|
}
|
|
210
341
|
return stripped;
|
|
211
342
|
}
|
|
343
|
+
/**
|
|
344
|
+
* Refuses a manifest that still carries a spec only a workspace can resolve. Published
|
|
345
|
+
* with one, the package is uninstallable for everyone, and the version cannot be taken
|
|
346
|
+
* back.
|
|
347
|
+
*
|
|
348
|
+
* Both call sites pass an already-stripped manifest, so the dev-only members of
|
|
349
|
+
* DEP_FIELDS are absent by construction. They are still checked, because a guard whose
|
|
350
|
+
* correctness depends on the order it happens to be called in fails silently the day
|
|
351
|
+
* someone reorders it.
|
|
352
|
+
*/
|
|
212
353
|
function assertNoMonorepoProtocols(pkg) {
|
|
213
354
|
let failures = [];
|
|
214
355
|
for (let field of DEP_FIELDS) {
|
|
215
356
|
let map = pkg[field];
|
|
216
357
|
if (isObject(map)) for (let [name, spec] of Object.entries(map)) typeof spec == "string" && MONOREPO_PROTOCOLS.some((prefix) => spec.includes(prefix)) && failures.push(`${field}.${name}: ${spec}`);
|
|
217
358
|
}
|
|
218
|
-
let pnpm = pkg.pnpm;
|
|
219
|
-
if (isObject(pnpm) && isObject(pnpm.overrides)) for (let [name, spec] of Object.entries(pnpm.overrides)) typeof spec == "string" && MONOREPO_PROTOCOLS.some((prefix) => spec.includes(prefix)) && failures.push(`pnpm.overrides.${name}: ${spec}`);
|
|
220
359
|
if (failures.length > 0) throw new PublishCleanError(`Packed manifest contains unresolved monorepo-only dependency specs:\n${failures.join("\n")}\n${PUBLISH_ADVISORY}`);
|
|
221
360
|
}
|
|
222
361
|
function customDevFields(config) {
|
|
@@ -225,6 +364,20 @@ function customDevFields(config) {
|
|
|
225
364
|
if (unsafe.length > 0) throw new PublishCleanError(`publish-clean.devFields cannot remove runtime/public manifest fields:\n${unsafe.join("\n")}`);
|
|
226
365
|
return fields;
|
|
227
366
|
}
|
|
367
|
+
/**
|
|
368
|
+
* Fields the maintainer has confirmed belong in the published package, so they stop being
|
|
369
|
+
* reported as unrecognised.
|
|
370
|
+
*
|
|
371
|
+
* Without this the report has only one resolution, `devFields`, which deletes the field.
|
|
372
|
+
* That is the wrong answer for every package whose ecosystem this tool has never heard of:
|
|
373
|
+
* a VS Code extension needs `contributes` and `publisher` in the artifact to function at
|
|
374
|
+
* all. Its author would face a warning on every release that can only be silenced by
|
|
375
|
+
* breaking the extension, and a warning nobody can act on trains everyone to ignore the
|
|
376
|
+
* next one, including a real leak.
|
|
377
|
+
*/
|
|
378
|
+
function keptFields(config) {
|
|
379
|
+
return Array.isArray(config.keepFields) ? config.keepFields.filter((field) => typeof field == "string") : [];
|
|
380
|
+
}
|
|
228
381
|
async function walkFiles(dir, root, files) {
|
|
229
382
|
let entries = await readdir(dir, { withFileTypes: !0 });
|
|
230
383
|
for (let entry of entries) {
|
|
@@ -285,30 +438,35 @@ function assertFinalTarballIncludesCleanedFiles(cleanedFiles, finalFiles) {
|
|
|
285
438
|
let missing = cleanedFiles.filter((file) => !finalFiles.includes(file)).sort();
|
|
286
439
|
if (missing.length !== 0) throw new PublishCleanError(`Final npm tarball dropped files from the cleaned package:\n${missing.join("\n")}`);
|
|
287
440
|
}
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
441
|
+
/**
|
|
442
|
+
* Walks a manifest value of any shape and collects the strings that name a file inside
|
|
443
|
+
* the package, so the caller can prove each one exists in the tarball.
|
|
444
|
+
*
|
|
445
|
+
* `mode` exists because the two families of path-bearing fields disagree about what a
|
|
446
|
+
* bare string means, and reading one by the other's rules produces wrong answers in both
|
|
447
|
+
* directions:
|
|
448
|
+
*
|
|
449
|
+
* - `"every-string"` for `main`, `module`, `types`, `typings`, `bin` and `typesVersions`,
|
|
450
|
+
* where every string is a path into this package.
|
|
451
|
+
* - `"relative-only"` for `exports`, `imports`, `sideEffects` and the object form of
|
|
452
|
+
* `browser`, where a string may just as well be an external package name, a condition
|
|
453
|
+
* target or a glob. Only a `./` or `../` prefix marks it as a path here. Collecting the
|
|
454
|
+
* rest would report a missing file for something that was never a file.
|
|
455
|
+
*
|
|
456
|
+
* Booleans are skipped rather than ignored by accident: `sideEffects: false` and
|
|
457
|
+
* `exports` condition values legitimately hold them.
|
|
458
|
+
*/
|
|
459
|
+
function collectDeclaredPaths(value, out, mode) {
|
|
302
460
|
if (typeof value == "string") {
|
|
303
|
-
(value.startsWith("./") || value.startsWith("../")) && out.push(value);
|
|
461
|
+
(mode === "every-string" || value.startsWith("./") || value.startsWith("../")) && out.push(value);
|
|
304
462
|
return;
|
|
305
463
|
}
|
|
306
464
|
if (typeof value != "boolean") {
|
|
307
465
|
if (Array.isArray(value)) {
|
|
308
|
-
for (let item of value)
|
|
466
|
+
for (let item of value) collectDeclaredPaths(item, out, mode);
|
|
309
467
|
return;
|
|
310
468
|
}
|
|
311
|
-
if (isObject(value)) for (let item of Object.values(value))
|
|
469
|
+
if (isObject(value)) for (let item of Object.values(value)) collectDeclaredPaths(item, out, mode);
|
|
312
470
|
}
|
|
313
471
|
}
|
|
314
472
|
function normalizeDeclaredPath(declared) {
|
|
@@ -325,14 +483,14 @@ function assertDeclaredFiles(pkg, packageDir) {
|
|
|
325
483
|
"types",
|
|
326
484
|
"typings",
|
|
327
485
|
"bin"
|
|
328
|
-
]) collectDeclaredPaths(pkg[field], paths);
|
|
329
|
-
typeof pkg.browser == "string" ? collectDeclaredPaths(pkg.browser, paths) :
|
|
486
|
+
]) collectDeclaredPaths(pkg[field], paths, "every-string");
|
|
487
|
+
typeof pkg.browser == "string" ? collectDeclaredPaths(pkg.browser, paths, "every-string") : collectDeclaredPaths(pkg.browser, paths, "relative-only");
|
|
330
488
|
for (let field of [
|
|
331
489
|
"exports",
|
|
332
490
|
"imports",
|
|
333
491
|
"sideEffects"
|
|
334
|
-
])
|
|
335
|
-
collectDeclaredPaths(pkg.typesVersions, paths);
|
|
492
|
+
]) collectDeclaredPaths(pkg[field], paths, "relative-only");
|
|
493
|
+
collectDeclaredPaths(pkg.typesVersions, paths, "every-string");
|
|
336
494
|
let normalized = paths.map((declared) => ({
|
|
337
495
|
declared,
|
|
338
496
|
normalized: normalizeDeclaredPath(declared)
|
|
@@ -356,7 +514,7 @@ async function packAndClean(packageDir, opts) {
|
|
|
356
514
|
requireTool("pnpm"), requireTool("npm"), requireTool("tar"), warnIfNonPnpmLifecycle();
|
|
357
515
|
let sourcePkg = readJson(path.join(packageDir, "package.json"));
|
|
358
516
|
!opts.guardOnly && !opts.dryRun && assertTrustedPublishingRuntime(sourcePkg, opts.publishArgs);
|
|
359
|
-
let config = packageConfig(sourcePkg), skipFileCheck = opts.skipFileCheck || config.skipFileCheck === !0, noGitChecks = opts.noGitChecks || config.noGitChecks === !0, registry = opts.registry ?? (typeof config.registry == "string" ? config.registry : null), extraDevFields = customDevFields(config);
|
|
517
|
+
let config = packageConfig(sourcePkg), skipFileCheck = opts.skipFileCheck || config.skipFileCheck === !0, noGitChecks = opts.noGitChecks || config.noGitChecks === !0, registry = opts.registry ?? (typeof config.registry == "string" ? config.registry : null), extraDevFields = customDevFields(config), keepFields = keptFields(config);
|
|
360
518
|
assertPublicPackage(sourcePkg), assertCleanGit(packageDir, noGitChecks), assertFilesField(sourcePkg, skipFileCheck);
|
|
361
519
|
let root = await mkdtemp(path.join(tmpdir(), "publish-clean-")), keepRoot = !1;
|
|
362
520
|
try {
|
|
@@ -379,7 +537,7 @@ async function packAndClean(packageDir, opts) {
|
|
|
379
537
|
let publishConfig = isObject(cleanedPkg.publishConfig) ? { ...cleanedPkg.publishConfig } : {};
|
|
380
538
|
publishConfig.registry = registry, cleanedPkg.publishConfig = publishConfig;
|
|
381
539
|
}
|
|
382
|
-
assertNoMonorepoProtocols(cleanedPkg), await writeFile(packedPkgPath, stringifyJson(cleanedPkg)), assertDeclaredFiles(cleanedPkg, extracted);
|
|
540
|
+
assertNoMonorepoProtocols(cleanedPkg), reportUnrecognizedFields(cleanedPkg, keepFields), await writeFile(packedPkgPath, stringifyJson(cleanedPkg)), assertDeclaredFiles(cleanedPkg, extracted);
|
|
383
541
|
let cleanedFiles = [];
|
|
384
542
|
await walkFiles(extracted, extracted, cleanedFiles);
|
|
385
543
|
let finalPackRoot = path.join(root, "npm-pack");
|
|
@@ -392,7 +550,7 @@ async function packAndClean(packageDir, opts) {
|
|
|
392
550
|
let finalTarball = await soleTarball(finalPackRoot, "npm pack"), finalFiles = listTarballFiles(finalTarball, extracted);
|
|
393
551
|
validatePackedFiles(finalFiles, skipFileCheck), assertFinalTarballIncludesCleanedFiles(cleanedFiles, finalFiles);
|
|
394
552
|
let finalPkg = readTarballJson(finalTarball, "package.json", extracted);
|
|
395
|
-
if (assertNoMonorepoProtocols(finalPkg), stableJson(finalPkg) !== stableJson(cleanedPkg)) throw new PublishCleanError("Final npm tarball manifest differs from the cleaned manifest.");
|
|
553
|
+
if (assertNoMonorepoProtocols(finalPkg), assertNoLostConsumerFields(sourcePkg, finalPkg, extraDevFields), stableJson(finalPkg) !== stableJson(cleanedPkg)) throw new PublishCleanError("Final npm tarball manifest differs from the cleaned manifest.");
|
|
396
554
|
if (opts.tarballOut !== null) {
|
|
397
555
|
await mkdir(opts.tarballOut, { recursive: !0 });
|
|
398
556
|
let kept = path.join(opts.tarballOut, path.basename(finalTarball));
|
|
@@ -403,7 +561,7 @@ async function packAndClean(packageDir, opts) {
|
|
|
403
561
|
keepRoot = !0, console.log(`[dry-run] Extracted package at: ${extracted}`), console.log(`[dry-run] Final tarball at: ${finalTarball}`);
|
|
404
562
|
return;
|
|
405
563
|
}
|
|
406
|
-
assertRepositoryForTrustedPublish(cleanedPkg, opts.publishArgs),
|
|
564
|
+
assertRepositoryForTrustedPublish(cleanedPkg, opts.publishArgs), runAttached("npm", registry ? [
|
|
407
565
|
"publish",
|
|
408
566
|
finalTarball,
|
|
409
567
|
"--registry",
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@anizoptera/publish-clean",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Publish
|
|
3
|
+
"version": "0.3.0",
|
|
4
|
+
"description": "Publish npm packages with a consumer-only package.json. Refuses to ship a .env, a private key, or an unresolved workspace dependency.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"bun",
|
|
7
7
|
"cleanup",
|
|
@@ -9,8 +9,12 @@
|
|
|
9
9
|
"npm",
|
|
10
10
|
"pack",
|
|
11
11
|
"package",
|
|
12
|
+
"package.json",
|
|
12
13
|
"pnpm",
|
|
13
|
-
"
|
|
14
|
+
"provenance",
|
|
15
|
+
"publish",
|
|
16
|
+
"supply-chain",
|
|
17
|
+
"workspace"
|
|
14
18
|
],
|
|
15
19
|
"homepage": "https://github.com/Anizoptera/publish-clean#readme",
|
|
16
20
|
"bugs": {
|