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