@anizoptera/publish-clean 0.7.3 → 0.9.1
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 +166 -231
- package/dist/cli.js +617 -372
- package/package.json +4 -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
|
+
Publish npm packages with a clean `package.json` and checks for unwanted files,
|
|
4
|
+
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,23 @@ dependencies. No deps, one JS file.
|
|
|
11
10
|
[](package.json)
|
|
12
11
|
[](LICENSE)
|
|
13
12
|
|
|
14
|
-
|
|
13
|
+
`publish-clean` removes `devDependencies`, workspace settings and tool config from the
|
|
14
|
+
published manifest. Consumer fields and lifecycle helpers stay. Unknown fields are
|
|
15
|
+
reported for review and kept unless you choose to remove them.
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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.
|
|
17
|
+
It packs once with pnpm, cleans the manifest inside the tarball, checks that file, then
|
|
18
|
+
uploads it with npm. The checked bytes are the published bytes. Cleaning leaves your
|
|
19
|
+
source files alone; your pack hooks still run and can change them.
|
|
22
20
|
|
|
23
|
-
|
|
24
|
-
tests, `.github/`, a lockfile. You do not see the tarball before it goes out, and once a
|
|
25
|
-
version is published you cannot edit it. Unpublishing only works for a short window and
|
|
26
|
-
under conditions npm decides.
|
|
21
|
+
Preview, then publish:
|
|
27
22
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
fails instead of publishing.
|
|
23
|
+
```sh
|
|
24
|
+
pnpm exec publish-clean --dry-run
|
|
25
|
+
pnpm exec publish-clean -- --access public --tag latest --provenance
|
|
26
|
+
```
|
|
33
27
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
[why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
|
|
28
|
+
Requires Node.js 22+, pnpm and npm. The CLI has no runtime dependencies. The publish
|
|
29
|
+
command above needs [CI provenance setup](#publishing-a-public-package-from-ci).
|
|
37
30
|
|
|
38
31
|
## Install
|
|
39
32
|
|
|
@@ -44,60 +37,40 @@ choices are argued, with measurements, in
|
|
|
44
37
|
| npm | `npm i -D @anizoptera/publish-clean` | `npm exec publish-clean` |
|
|
45
38
|
| Yarn | `yarn add -D @anizoptera/publish-clean` | `yarn publish-clean` |
|
|
46
39
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
Node.js 22+ runs it. npm provenance additionally needs 22.14+, because below that npm
|
|
51
|
-
cannot mint it.
|
|
40
|
+
Both `pnpm` and `npm` must be on `PATH`, including in Bun, npm and Yarn projects and CI.
|
|
41
|
+
The CLI is one JavaScript file with no runtime dependencies. pnpm and npm are separate
|
|
42
|
+
requirements, not bundled dependencies.
|
|
52
43
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
44
|
+
For trusted publishing, use Node.js 22.14+ and npm 11.5.1+. Provenance requires a public
|
|
45
|
+
package, a public source repository and a supported CI provider. See
|
|
46
|
+
[npm's requirements](https://docs.npmjs.com/trusted-publishers/).
|
|
56
47
|
|
|
57
|
-
|
|
58
|
-
registry credentials, that matters. A publishing tool with a dependency tree is a
|
|
59
|
-
supply-chain risk of its own, and this one has no transitive code to audit.
|
|
48
|
+
### Running it under Bun
|
|
60
49
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
### Running it under Bun packs a smaller tarball
|
|
65
|
-
|
|
66
|
-
gzip encoding belongs to whichever runtime executes the CLI, and Bun's (libdeflate) beats
|
|
67
|
-
Node's zlib on tar-shaped data: 0.17% smaller for this package, 0.28% for a sibling one, with
|
|
68
|
-
a byte-identical archive inside. To get it, pass Bun the **file path**:
|
|
50
|
+
gzip bytes depend on the runtime and version executing the CLI. To run it under Bun,
|
|
51
|
+
pass Bun the **file path**:
|
|
69
52
|
|
|
70
53
|
```sh
|
|
71
54
|
bun ./node_modules/.bin/publish-clean
|
|
72
55
|
```
|
|
73
56
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
its `#!/usr/bin/env node` shebang and runs Node. They succeed, and you get Node's bytes.
|
|
57
|
+
The installed command has a Node shebang. Passing the file directly avoids relying on
|
|
58
|
+
how a package runner selects an interpreter or changes the child tools' environment.
|
|
77
59
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
Either runtime produces valid gzip with identical contents, so the choice is free. The one
|
|
82
|
-
rule is not to switch runtimes _within_ a version: if a release is re-run to repair its
|
|
83
|
-
artifacts, the bytes have to come out the same, and the two encoders do not agree.
|
|
60
|
+
Keep the runtime and its version fixed when rebuilding a release artifact. Node and
|
|
61
|
+
Bun can encode the same archive contents into different gzip bytes, which changes the
|
|
62
|
+
artifact's hash.
|
|
84
63
|
|
|
85
64
|
## Package managers
|
|
86
65
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
|
|
90
|
-
|
|
91
|
-
Started with anything other than pnpm, it prints an advisory on stderr saying so. That is
|
|
92
|
-
a warning, not an error. Nothing behaves differently because of it, and there is no flag
|
|
93
|
-
to silence it.
|
|
66
|
+
The CLI uses pnpm for workspace resolution and `publishConfig` overrides, and npm to upload the
|
|
67
|
+
checked tarball. The [packer comparison](docs/why-pnpm-and-npm.md) explains the trade-offs.
|
|
94
68
|
|
|
95
|
-
|
|
96
|
-
|
|
69
|
+
Starting through another package manager prints an advisory on stderr. It does not change
|
|
70
|
+
the packer or stop publication, and there is no option to suppress it.
|
|
97
71
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
whether that works is the layout your installer left behind, not which installer it was.
|
|
72
|
+
For `workspace:` and `catalog:` specs, pnpm needs the installed dependency in the packing
|
|
73
|
+
package's own `node_modules`. Compatibility depends on your install layout.
|
|
101
74
|
|
|
102
75
|
Bun gives each package its own `node_modules`, so a Bun workspace packs as it stands: no
|
|
103
76
|
`pnpm-workspace.yaml`, no switching package managers. Yarn hoists workspace dependencies
|
|
@@ -106,32 +79,32 @@ all. Both need a `pnpm-workspace.yaml` and one `pnpm install` before packing wor
|
|
|
106
79
|
package with no `workspace:` or `catalog:` specs needs neither, because there's nothing to
|
|
107
80
|
resolve.
|
|
108
81
|
|
|
109
|
-
|
|
110
|
-
on pnpm's own error:
|
|
82
|
+
Install the workspace before packing. An unresolved workspace dependency stops packing:
|
|
111
83
|
|
|
112
84
|
```
|
|
113
85
|
ERR_PNPM_CANNOT_RESOLVE_WORKSPACE_PROTOCOL
|
|
114
86
|
```
|
|
115
87
|
|
|
116
|
-
|
|
117
|
-
uninstallable for everyone never reaches the registry. Run your usual install and pack
|
|
118
|
-
again.
|
|
88
|
+
Install with the layout described above, then retry.
|
|
119
89
|
|
|
120
90
|
## Pick your setup
|
|
121
91
|
|
|
122
92
|
### Publishing a public package from CI
|
|
123
93
|
|
|
124
|
-
|
|
125
|
-
|
|
94
|
+
Configure an npm trusted publisher for your repository and workflow filename, with
|
|
95
|
+
permission for direct `npm publish`. In the publish job, grant `id-token: write` so npm
|
|
96
|
+
can authenticate through GitHub OIDC without an npm token. Run tests in a separate job
|
|
97
|
+
and make the publish job depend on their success.
|
|
126
98
|
|
|
127
99
|
```yaml
|
|
128
|
-
#
|
|
100
|
+
# Inside the publish job, after its required check jobs have passed:
|
|
129
101
|
permissions:
|
|
130
102
|
contents: read
|
|
131
103
|
id-token: write
|
|
132
104
|
steps:
|
|
133
105
|
- uses: actions/checkout@v7
|
|
134
106
|
- uses: pnpm/action-setup@v6
|
|
107
|
+
# Set packageManager in package.json to select your pnpm version.
|
|
135
108
|
- uses: actions/setup-node@v7
|
|
136
109
|
with:
|
|
137
110
|
node-version: "24"
|
|
@@ -141,13 +114,13 @@ steps:
|
|
|
141
114
|
- run: pnpm exec publish-clean -- --access public --tag latest --provenance
|
|
142
115
|
```
|
|
143
116
|
|
|
144
|
-
|
|
145
|
-
|
|
117
|
+
Use `--tag latest` for stable releases and `--tag next` for prereleases. npm defaults
|
|
118
|
+
to `latest`, so omitting the tag can give ordinary installs a prerelease.
|
|
146
119
|
|
|
147
|
-
|
|
148
|
-
case has its own page: [docs/first-publish.md](docs/first-publish.md).
|
|
120
|
+
For a new package name, follow the [first-publish setup](docs/first-publish.md).
|
|
149
121
|
|
|
150
|
-
To
|
|
122
|
+
To block direct publication from your source directory, add this hook. Publishing a
|
|
123
|
+
tarball does not run it:
|
|
151
124
|
|
|
152
125
|
```json
|
|
153
126
|
{
|
|
@@ -159,8 +132,8 @@ To stop a stray `npm publish` from bypassing all of this:
|
|
|
159
132
|
|
|
160
133
|
### Keeping your existing release tool
|
|
161
134
|
|
|
162
|
-
If
|
|
163
|
-
|
|
135
|
+
If your release tool supports a custom upload command, use `publish-clean` there.
|
|
136
|
+
For a preview check only, add:
|
|
164
137
|
|
|
165
138
|
```json
|
|
166
139
|
{
|
|
@@ -170,10 +143,10 @@ If Changesets, semantic-release, release-it or np already owns your releases, us
|
|
|
170
143
|
}
|
|
171
144
|
```
|
|
172
145
|
|
|
173
|
-
It
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
146
|
+
It checks a pnpm-produced preview and exits without publishing. Your release tool still
|
|
147
|
+
creates and uploads its own artifact, which may differ: this gate does not validate those
|
|
148
|
+
uploaded bytes or clean their manifest. To publish the checked bytes, configure that tool
|
|
149
|
+
to invoke `publish-clean` for the upload instead.
|
|
177
150
|
|
|
178
151
|
### Looking at what would be published
|
|
179
152
|
|
|
@@ -181,8 +154,8 @@ publishes its own tarball, so you get the checks and not the cleaned manifest.
|
|
|
181
154
|
pnpm exec publish-clean --dry-run
|
|
182
155
|
```
|
|
183
156
|
|
|
184
|
-
Prints
|
|
185
|
-
|
|
157
|
+
Prints the checked file list and cleaned `package.json`. Add `--tarball-out DIR` to keep
|
|
158
|
+
the tarball; otherwise temporary files are removed.
|
|
186
159
|
|
|
187
160
|
### Publishing a restricted package
|
|
188
161
|
|
|
@@ -190,8 +163,8 @@ tree. Add `--tarball-out DIR` to keep the tarball itself.
|
|
|
190
163
|
publish-clean -- --access restricted --tag latest
|
|
191
164
|
```
|
|
192
165
|
|
|
193
|
-
|
|
194
|
-
|
|
166
|
+
Omit provenance for restricted packages. Leave `private: true` unset: it prohibits
|
|
167
|
+
publication, even to a private registry.
|
|
195
168
|
|
|
196
169
|
### Publishing one package out of a monorepo
|
|
197
170
|
|
|
@@ -204,133 +177,89 @@ publish-clean packages/my-lib -- --access public --tag next
|
|
|
204
177
|
```mermaid
|
|
205
178
|
flowchart TD
|
|
206
179
|
A[Your package directory] -->|pnpm pack| B[Tarball, file set chosen by pnpm]
|
|
207
|
-
B --> C[
|
|
180
|
+
B --> C[Rewrite only package.json inside]
|
|
208
181
|
C --> D[Final tarball]
|
|
209
182
|
D --> E{Checks, all reading this tarball}
|
|
210
183
|
E -->|any fails| F[Exit non-zero, publish nothing]
|
|
211
184
|
E -->|all pass| G[npm publish this same tarball]
|
|
212
185
|
```
|
|
213
186
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
`--dry-run` and `--guard-only` run the whole pipeline and stop before the publish.
|
|
187
|
+
`--dry-run` and `--guard-only` validate the artifact, but skip publication preflight.
|
|
188
|
+
Neither proves that registry access, credentials, provenance requirements or repository
|
|
189
|
+
identity are correct. Pack hooks still run, including any network operations they perform.
|
|
219
190
|
|
|
220
191
|
## Why it works this way
|
|
221
192
|
|
|
222
|
-
### Why
|
|
223
|
-
|
|
224
|
-
pnpm because of workspaces. A dependency written `"@acme/utils": "workspace:*"` has to
|
|
225
|
-
become a real version range before it ships, and pnpm is the only packer that does that
|
|
226
|
-
for every layout it might find, including a Bun one. npm writes `workspace:*` into the
|
|
227
|
-
tarball unchanged and exits 0, publishing a package nobody can install. Bun resolves only
|
|
228
|
-
what Bun installed, and quietly mangles an aliased workspace dependency.
|
|
229
|
-
|
|
230
|
-
npm because of provenance. The signed attestation behind the "Built and signed on GitHub
|
|
231
|
-
Actions" badge is minted by the npm CLI talking to Sigstore, and trusted publishing, which
|
|
232
|
-
removes the long-lived token entirely, is npm's own exchange with the registry. No other
|
|
233
|
-
client does either one. `npm publish` also takes a tarball directly, which is what the
|
|
234
|
-
packing step already produced.
|
|
235
|
-
|
|
236
|
-
The measurements behind both choices, and the one thing packing with pnpm costs you, are
|
|
237
|
-
in [why pnpm packs and npm publishes](docs/why-pnpm-and-npm.md).
|
|
193
|
+
### Why cleaning happens in the tarball
|
|
238
194
|
|
|
239
|
-
|
|
195
|
+
Cleaning stays out of the source tree so an interrupted publish cannot leave your
|
|
196
|
+
`package.json` half-edited. Pack hooks still run in the source directory and may change it.
|
|
240
197
|
|
|
241
|
-
|
|
242
|
-
temp directory. Your working tree is never touched.
|
|
198
|
+
### Why the tarball is edited instead of packed again
|
|
243
199
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
200
|
+
Uploading the checked tarball prevents npm from choosing files again.
|
|
201
|
+
Cleaning removes `files` from its manifest because installation no longer needs that
|
|
202
|
+
packing instruction. Repacking the cleaned directory could then fall back to ignore rules
|
|
203
|
+
and drop files the first pack included.
|
|
248
204
|
|
|
249
|
-
|
|
205
|
+
Only `package/package.json` is replaced. Other archive entries retain their bytes,
|
|
206
|
+
order and metadata, including pnpm's owner `0:0`, fixed timestamps and file modes.
|
|
207
|
+
The reader resolves USTAR and PAX paths before checking files and rejects malformed or
|
|
208
|
+
unsupported path metadata.
|
|
250
209
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
`--tarball-out` for a build attestation, and then published as themselves. What you
|
|
255
|
-
inspect is what ships.
|
|
256
|
-
|
|
257
|
-
So the manifest has to be cleaned inside a tarball that already exists. The obvious way is
|
|
258
|
-
to unpack, edit, and pack again — and it is wrong. `files` is a packing instruction, and
|
|
259
|
-
cleaning removes it, because it is useless to anyone installing the package. A second pack
|
|
260
|
-
then has nothing left to select with, falls back to your `.gitignore`/`.npmignore` for
|
|
261
|
-
exclusion, and quietly drops files the first pack included. A package shipping a
|
|
262
|
-
`.gitignore` that excludes any other shipped file loses it.
|
|
263
|
-
|
|
264
|
-
Editing avoids the question. Only the `package/package.json` member is replaced. Every
|
|
265
|
-
other entry is copied without being decoded, so the file set stays exactly what pnpm chose,
|
|
266
|
-
and entry shapes this tool does not model (pax headers for long paths, prefix splitting)
|
|
267
|
-
pass through untouched. It also keeps pnpm's normalised metadata: owner `0:0`, a fixed
|
|
268
|
-
timestamp, mode 644. A plain `tar` invocation would replace those with whatever the build
|
|
269
|
-
machine happens to have.
|
|
270
|
-
|
|
271
|
-
Lifecycle scripts run once, at the first pack. `pnpm pack` runs your `prepare` and
|
|
272
|
-
`prepack`, which is how build output reaches the package at all. Nothing runs afterwards:
|
|
273
|
-
npm skips `prepack`/`postpack` when it is handed a tarball rather than a directory, so
|
|
274
|
-
nothing can alter the artifact after it was checked.
|
|
210
|
+
`pnpm pack` runs pack hooks, including `prepare` and `prepack`. npm runs no package
|
|
211
|
+
lifecycle scripts when uploading a tarball, so those hooks cannot change the checked
|
|
212
|
+
artifact during upload.
|
|
275
213
|
|
|
276
214
|
## What it checks
|
|
277
215
|
|
|
278
|
-
|
|
216
|
+
Publication stops when:
|
|
279
217
|
|
|
280
218
|
- the package is marked `private: true`
|
|
281
219
|
- the working tree has uncommitted changes (`--no-git-checks` to allow it)
|
|
282
220
|
- the package has no non-empty `files` array (`--skip-file-check` to allow it)
|
|
283
|
-
- the tarball
|
|
284
|
-
allow
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
path that is not in the tarball
|
|
221
|
+
- the tarball contains a recognised test, CI, lockfile or `tsconfig` path
|
|
222
|
+
(`--allow-suspicious` to allow it)
|
|
223
|
+
- a filename matches the protected rules for environment files, npm credentials, Git
|
|
224
|
+
internals, `node_modules` or key files; these checks cannot be disabled
|
|
225
|
+
- a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, or a local
|
|
226
|
+
dependency points outside the shipped files
|
|
227
|
+
- a declared entry point cannot resolve against the shipped files; checks account for
|
|
228
|
+
extension lookup, conditions and fallbacks, and allow unmatched `sideEffects` globs
|
|
292
229
|
- rewriting the manifest changed anything else in the tarball
|
|
293
|
-
-
|
|
230
|
+
- GitHub trusted publishing or provenance is enabled, but the `repository` in your manifest
|
|
294
231
|
is not the repository the workflow is running in
|
|
295
232
|
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
probably should too.
|
|
233
|
+
File guards check paths, not file contents. They cannot detect a credential embedded
|
|
234
|
+
in an otherwise allowed source file. See [the rules](src/artifact.ts).
|
|
299
235
|
|
|
300
236
|
## What the cleaned manifest keeps
|
|
301
237
|
|
|
302
|
-
|
|
238
|
+
The cleaner preserves consumer and registry fields: `name`, `version`, `license`,
|
|
303
239
|
`dependencies`, `peerDependencies` and their meta, `exports`, `main`, `module`, `types`,
|
|
304
|
-
`bin`, `engines`, `os`, `cpu`, `sideEffects
|
|
305
|
-
surface.
|
|
240
|
+
`bin`, `engines`, `os`, `cpu`, `sideEffects` and `publishConfig`, among others.
|
|
306
241
|
|
|
307
|
-
`files`
|
|
308
|
-
exists, nothing re-selects afterwards, and an install extracts every entry unfiltered. npm
|
|
309
|
-
agrees — its registry drops the field from the metadata it serves.
|
|
242
|
+
It removes `files` after packing; installers extract the tarball without using that field.
|
|
310
243
|
|
|
311
|
-
|
|
244
|
+
It also removes `devDependencies`, `workspaces`, `pnpm`, `packageManager`, `overrides`,
|
|
312
245
|
`resolutions`, and the config blocks belonging to test runners, linters, formatters,
|
|
313
|
-
coverage tools, build systems and release tools.
|
|
314
|
-
|
|
315
|
-
|
|
246
|
+
coverage tools, build systems and release tools. When `preinstall`, `install`, `postinstall`,
|
|
247
|
+
`prepare` or `uninstall` exists, the complete scripts block survives: a lifecycle may call
|
|
248
|
+
any helper script. Otherwise the development-only scripts block is removed.
|
|
316
249
|
|
|
317
|
-
|
|
250
|
+
Unknown fields are kept and reported:
|
|
318
251
|
|
|
319
252
|
```
|
|
320
|
-
publish-clean: these manifest fields are not recognised and
|
|
321
|
-
someToolConfig
|
|
253
|
+
publish-clean: these manifest fields are not recognised and are retained as-is:
|
|
254
|
+
"someToolConfig"
|
|
322
255
|
Strip the ones consumers do not read, and acknowledge the ones they do:
|
|
323
256
|
"publish-clean": { "devFields": ["someToolConfig"] }
|
|
324
257
|
"publish-clean": { "keepFields": ["someToolConfig"] }
|
|
325
258
|
```
|
|
326
259
|
|
|
327
|
-
|
|
328
|
-
`
|
|
329
|
-
|
|
330
|
-
hear about it from a stranger's broken build rather than from your own release.
|
|
331
|
-
|
|
332
|
-
Add your own with `devFields`. Better still, run `--dry-run` and read the manifest that
|
|
333
|
-
would ship instead of trusting this list.
|
|
260
|
+
Unknown fields stay because removing an unfamiliar field can break a consumer's build.
|
|
261
|
+
Use `devFields` to remove a field you know is development-only, or `keepFields` to suppress
|
|
262
|
+
its report. Inspect the result with `--dry-run`.
|
|
334
263
|
|
|
335
264
|
## Options and config
|
|
336
265
|
|
|
@@ -338,8 +267,8 @@ would ship instead of trusting this list.
|
|
|
338
267
|
publish-clean [options] [package-dir] [-- npm-publish-args]
|
|
339
268
|
```
|
|
340
269
|
|
|
341
|
-
|
|
342
|
-
|
|
270
|
+
Set project defaults in `package.json`. A CLI registry overrides the configured registry;
|
|
271
|
+
boolean flags enable their setting. Pass per-release npm options, such as dist-tags, after `--`:
|
|
343
272
|
|
|
344
273
|
```json
|
|
345
274
|
{
|
|
@@ -356,8 +285,8 @@ choices like dist-tags on the command line and stable project policy in the mani
|
|
|
356
285
|
|
|
357
286
|
| Flag | `package.json` | What it does |
|
|
358
287
|
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
|
|
359
|
-
| `--dry-run` | - |
|
|
360
|
-
| `--guard-only` | - |
|
|
288
|
+
| `--dry-run` | - | Validate a preview artifact and print its file list and cleaned `package.json`. |
|
|
289
|
+
| `--guard-only` | - | Validate a preview artifact without the file list or manifest output. |
|
|
361
290
|
| `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
|
|
362
291
|
| `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
|
|
363
292
|
| `--skip-file-check` | `skipFileCheck` | Allow a manifest with no `files` array. |
|
|
@@ -368,87 +297,72 @@ choices like dist-tags on the command line and stable project policy in the mani
|
|
|
368
297
|
| `-h`, `--help` | - | Print usage, every flag, and the config keys. |
|
|
369
298
|
| `-v`, `--version` | - | Print the installed version. |
|
|
370
299
|
|
|
371
|
-
Arguments after `--`
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
300
|
+
Arguments after `--` accept publication options only; `--help` lists them. Extra package
|
|
301
|
+
operands, workspace selectors, unknown options and values starting with `-` are rejected
|
|
302
|
+
so npm cannot substitute an unchecked package. For a filename starting with `-`, use `./`.
|
|
303
|
+
Pass the dist-tag explicitly: `--tag latest` for a normal public release.
|
|
375
304
|
|
|
376
|
-
`--tarball-out`
|
|
377
|
-
to a
|
|
378
|
-
every mode, before the publish, so you get the validated artifact even if the upload fails.
|
|
305
|
+
`--tarball-out` saves the checked bytes in every mode, before any upload. You can inspect
|
|
306
|
+
them, attach them to a release or attest them, even if publication fails.
|
|
379
307
|
|
|
380
|
-
`registry`
|
|
381
|
-
|
|
308
|
+
`registry` sets both the general and package-scope destination in the cleaned manifest.
|
|
309
|
+
Registry URLs must not contain usernames or passwords, including scoped destinations in
|
|
310
|
+
`publishConfig`. Configure npm authentication in npm configuration instead.
|
|
382
311
|
|
|
383
|
-
`skipFileCheck`
|
|
384
|
-
|
|
385
|
-
tarball is content nobody meant to ship. Neither touches the leak checks, which have no
|
|
386
|
-
off switch at all.
|
|
312
|
+
`skipFileCheck` waives the manifest's `files` requirement. `allowSuspicious` permits the
|
|
313
|
+
listed development files. Neither disables the protected filename checks.
|
|
387
314
|
|
|
388
|
-
`noGitChecks`
|
|
389
|
-
that is not a git repository at all.
|
|
315
|
+
Use `noGitChecks` for a build directory or another directory outside a Git repository.
|
|
390
316
|
|
|
391
|
-
`devFields` refuses
|
|
392
|
-
|
|
317
|
+
`devFields` refuses known consumer fields such as `exports`, `bin`, `engines` and dependency
|
|
318
|
+
maps to prevent accidental removal.
|
|
393
319
|
|
|
394
|
-
`keepFields`
|
|
395
|
-
|
|
396
|
-
`publisher` in the artifact to work, and no generic publishing tool is ever going to know
|
|
397
|
-
that.
|
|
320
|
+
Use `keepFields` for consumer fields the tool does not recognise, such as a VS Code
|
|
321
|
+
extension's `contributes` and `publisher`. It suppresses reports; it does not restore stripped fields.
|
|
398
322
|
|
|
399
323
|
## What it does not do
|
|
400
324
|
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
release manager and a validator; the next section names them.
|
|
325
|
+
Use your release tool for versions, changelogs, tags and GitHub releases. Configure trusted
|
|
326
|
+
publishing separately. `publish-clean` checks declared paths; it does not execute your
|
|
327
|
+
package or validate its type declarations.
|
|
405
328
|
|
|
406
|
-
|
|
407
|
-
than copying them, so it has nothing to bundle and refuses:
|
|
329
|
+
Bundled `node_modules` are not allowed. pnpm may first reject `bundleDependencies` with:
|
|
408
330
|
|
|
409
331
|
```
|
|
410
332
|
Add "nodeLinker: hoisted" to pnpm-workspace.yaml or delete bundleDependencies
|
|
411
333
|
```
|
|
412
334
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
is loud and tells you the fix.
|
|
335
|
+
A hoisted layout can make pnpm pack them, but the resulting `node_modules` entries still
|
|
336
|
+
fail this tool's file checks. Use another publication path if you need to ship them.
|
|
416
337
|
|
|
417
|
-
##
|
|
338
|
+
## Related tools
|
|
418
339
|
|
|
419
|
-
[`clean-publish`](https://github.com/shashkovdanil/clean-publish)
|
|
420
|
-
|
|
421
|
-
directory, deletes the files and fields it recognises, and publishes that.
|
|
340
|
+
[`clean-publish`](https://github.com/shashkovdanil/clean-publish) cleans a temporary copy
|
|
341
|
+
of the source tree before publishing. `publish-clean` instead cleans a pnpm-produced tarball.
|
|
422
342
|
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
`publish-clean` starts from what `pnpm pack` produced, which is already the exact file
|
|
426
|
-
list your package manager would have shipped, including `files`, `.npmignore`, packlist
|
|
427
|
-
rules and resolved `workspace:` specs. Only the manifest is rewritten after that, and the
|
|
428
|
-
result is validated again before upload. clean-publish does not re-check its output.
|
|
343
|
+
That preserves pnpm's file selection and workspace resolution, and lets the checks read
|
|
344
|
+
the same bytes npm uploads.
|
|
429
345
|
|
|
430
|
-
Release
|
|
431
|
-
[release-please](https://github.com/googleapis/release-please),
|
|
346
|
+
Release tools such as [Changesets](https://github.com/changesets/changesets),
|
|
432
347
|
[semantic-release](https://github.com/semantic-release/semantic-release),
|
|
433
|
-
[release-
|
|
434
|
-
[np](https://github.com/sindresorhus/np)
|
|
435
|
-
|
|
436
|
-
|
|
348
|
+
[release-please](https://github.com/googleapis/release-please),
|
|
349
|
+
[release-it](https://github.com/release-it/release-it) and [np](https://github.com/sindresorhus/np)
|
|
350
|
+
handle release tasks. See [integration](#keeping-your-existing-release-tool) for the
|
|
351
|
+
difference between a preview check and publishing through this CLI.
|
|
437
352
|
|
|
438
353
|
[`publint`](https://publint.dev) and
|
|
439
354
|
[`@arethetypeswrong/cli`](https://github.com/arethetypeswrong/arethetypeswrong.github.io)
|
|
440
|
-
check
|
|
441
|
-
a different question from what is in the tarball. Run them as well.
|
|
355
|
+
check package entry points and TypeScript compatibility. Use them alongside this tool.
|
|
442
356
|
|
|
443
|
-
`npm publish --dry-run`
|
|
444
|
-
|
|
357
|
+
`npm publish --dry-run` previews npm's publication. It does not clean the manifest or apply
|
|
358
|
+
this tool's protected filename rules.
|
|
445
359
|
|
|
446
|
-
[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
|
|
447
|
-
|
|
448
|
-
|
|
360
|
+
[npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) authorises a CI
|
|
361
|
+
workflow to publish. Provenance links a release to its source and build; it does not
|
|
362
|
+
check package contents for you.
|
|
449
363
|
|
|
450
364
|
[`pkg-pr-new`](https://github.com/stackblitz-labs/pkg.pr.new) publishes preview builds
|
|
451
|
-
per commit without
|
|
365
|
+
per commit without publishing a version to npm.
|
|
452
366
|
|
|
453
367
|
Underlying behaviour is defined by [`npm-packlist`](https://github.com/npm/npm-packlist),
|
|
454
368
|
[`npm pack`](https://docs.npmjs.com/cli/v11/commands/npm-pack/),
|
|
@@ -469,3 +383,24 @@ reporting, not public issues: see [SECURITY.md](SECURITY.md).
|
|
|
469
383
|
## License
|
|
470
384
|
|
|
471
385
|
Apache-2.0. Copyright 2026 Anizoptera and Art Shendrik.
|
|
386
|
+
|
|
387
|
+
|
|
388
|
+
## Validate the final artifact
|
|
389
|
+
|
|
390
|
+
Set `publish-clean.validateArtifact` to an executable and its arguments to check the exact cleaned tarball before retention or upload:
|
|
391
|
+
|
|
392
|
+
```json
|
|
393
|
+
{
|
|
394
|
+
"publish-clean": {
|
|
395
|
+
"validateArtifact": ["node", "scripts/check-artifact.mjs"]
|
|
396
|
+
}
|
|
397
|
+
}
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
The command runs once in the source package directory, with the absolute tarball path appended as its last argument. It runs in normal, `--dry-run` and `--guard-only` modes, after built-in artifact checks and before `--tarball-out` copies anything. The configuration is stripped from the published manifest.
|
|
401
|
+
|
|
402
|
+
Use an executable, not a shell command or a Windows `.cmd` shim. Arguments remain literal; pipes, redirection and environment assignments are not interpreted. Relative script paths resolve from the package directory. The executable must be available in PATH or named by a path.
|
|
403
|
+
|
|
404
|
+
The validator must finish successfully and leave the tarball bytes unchanged. A launch failure, nonzero exit, changed or missing artifact stops retention and publication. Successful output is quiet; failure output is reported, with captured output bounded to prevent runaway memory use. Cancellation stops the child process tree before temporary files are removed. The validator is trusted project code, not a sandbox: it must not leave background writers or modify other project files.
|
|
405
|
+
|
|
406
|
+
Inspect the supplied archive directly. Do not invoke `publish-clean` or pack the package again inside the validator; that would recurse or validate different bytes.
|