@anizoptera/publish-clean 0.5.0 → 0.7.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 +28 -16
- package/dist/cli.js +250 -128
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@ dependencies. No deps, one JS file.
|
|
|
7
7
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean)
|
|
8
8
|
[](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
|
|
9
9
|
[](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml)
|
|
10
|
-
[](package.json)
|
|
11
11
|
[](package.json)
|
|
12
12
|
[](LICENSE)
|
|
13
13
|
|
|
@@ -47,11 +47,14 @@ choices are argued, with measurements, in
|
|
|
47
47
|
**Whatever you start it with, `pnpm` prepares the package and `npm` uploads it, so both
|
|
48
48
|
must be on `PATH`.** A Bun, npm or Yarn project needs pnpm installed too, including in CI.
|
|
49
49
|
|
|
50
|
-
|
|
50
|
+
Node.js 22+ runs it. npm provenance additionally needs 22.14+, because below that npm
|
|
51
|
+
cannot mint it.
|
|
51
52
|
|
|
52
53
|
That installs one package and nothing else. `publish-clean` has zero runtime
|
|
53
|
-
dependencies: it is a single file that talks to `pnpm
|
|
54
|
-
|
|
54
|
+
dependencies: it is a single file that talks to `pnpm` and `npm`, and reads and rewrites
|
|
55
|
+
the tarball itself, so there is nothing else to have on the machine.
|
|
56
|
+
|
|
57
|
+
For something that sits on your publish path and handles your
|
|
55
58
|
registry credentials, that matters. A publishing tool with a dependency tree is a
|
|
56
59
|
supply-chain risk of its own, and this one has no transitive code to audit.
|
|
57
60
|
|
|
@@ -256,6 +259,9 @@ nothing can alter the artifact after it was checked.
|
|
|
256
259
|
- the package is marked `private: true`
|
|
257
260
|
- the working tree has uncommitted changes (`--no-git-checks` to allow it)
|
|
258
261
|
- the package has no non-empty `files` array (`--skip-file-check` to allow it)
|
|
262
|
+
- the tarball holds tests, CI config, a lockfile or a `tsconfig` (`--allow-suspicious` to
|
|
263
|
+
allow it — a separate switch from the one above, so waiving a manifest convention never
|
|
264
|
+
silently disarms the artifact scan)
|
|
259
265
|
- the tarball holds something that should never ship: a `.env`, an `.npmrc`, `.git`,
|
|
260
266
|
`node_modules`, or a private key. This one has no off switch, by any flag or config key
|
|
261
267
|
- a dependency is still written as `catalog:`, `workspace:`, `link:` or `portal:`, which
|
|
@@ -319,6 +325,7 @@ choices like dist-tags on the command line and stable project policy in the mani
|
|
|
319
325
|
"publish-clean": {
|
|
320
326
|
"registry": "https://registry.npmjs.org",
|
|
321
327
|
"skipFileCheck": false,
|
|
328
|
+
"allowSuspicious": false,
|
|
322
329
|
"noGitChecks": false,
|
|
323
330
|
"devFields": ["customBuildOnlyField"],
|
|
324
331
|
"keepFields": ["contributes"]
|
|
@@ -326,17 +333,19 @@ choices like dist-tags on the command line and stable project policy in the mani
|
|
|
326
333
|
}
|
|
327
334
|
```
|
|
328
335
|
|
|
329
|
-
| Flag
|
|
330
|
-
|
|
|
331
|
-
| `--dry-run`
|
|
332
|
-
| `--guard-only`
|
|
333
|
-
| `--tarball-out DIR`
|
|
334
|
-
| `--registry URL`
|
|
335
|
-
| `--skip-file-check`
|
|
336
|
-
| `--
|
|
337
|
-
| -
|
|
338
|
-
| -
|
|
339
|
-
|
|
|
336
|
+
| Flag | `package.json` | What it does |
|
|
337
|
+
| -------------------- | ----------------- | ------------------------------------------------------------------------------------------ |
|
|
338
|
+
| `--dry-run` | - | Run everything up to the publish, then print the file list and the cleaned `package.json`. |
|
|
339
|
+
| `--guard-only` | - | Run everything up to the publish and exit, printing nothing. |
|
|
340
|
+
| `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
|
|
341
|
+
| `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
|
|
342
|
+
| `--skip-file-check` | `skipFileCheck` | Allow a manifest with no `files` array. |
|
|
343
|
+
| `--allow-suspicious` | `allowSuspicious` | Allow tests, CI config, lockfiles or `tsconfig` in the artifact. |
|
|
344
|
+
| `--no-git-checks` | `noGitChecks` | Allow publishing from a dirty working tree. |
|
|
345
|
+
| - | `devFields` | Extra manifest fields to strip. |
|
|
346
|
+
| - | `keepFields` | Fields that belong in the published package, so stop reporting them. |
|
|
347
|
+
| `-h`, `--help` | - | Print usage, every flag, and the config keys. |
|
|
348
|
+
| `-v`, `--version` | - | Print the installed version. |
|
|
340
349
|
|
|
341
350
|
Arguments after `--` go to `npm publish`. Pass the dist-tag explicitly: `--tag latest` for
|
|
342
351
|
a normal public release.
|
|
@@ -350,7 +359,10 @@ every mode, before the publish, so you get the validated artifact even if the up
|
|
|
350
359
|
`registry` pins where the package goes, so it cannot end up on whatever registry the
|
|
351
360
|
machine happens to be pointed at.
|
|
352
361
|
|
|
353
|
-
`skipFileCheck`
|
|
362
|
+
`skipFileCheck` and `allowSuspicious` are deliberately two switches. A missing `files`
|
|
363
|
+
array is a manifest convention some packages do not follow; tests or a lockfile in the
|
|
364
|
+
tarball is content nobody meant to ship. Neither touches the leak checks, which have no
|
|
365
|
+
off switch at all.
|
|
354
366
|
|
|
355
367
|
`noGitChecks` is what you need when you publish from a build directory, or from a checkout
|
|
356
368
|
that is not a git repository at all.
|
package/dist/cli.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import { execFileSync } from "node:child_process";
|
|
3
2
|
import { readFileSync } from "node:fs";
|
|
4
3
|
import { copyFile, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
|
|
5
4
|
import { tmpdir } from "node:os";
|
|
6
5
|
import path from "node:path";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
7
|
import { parseArgs } from "node:util";
|
|
8
|
+
import { execFileSync } from "node:child_process";
|
|
8
9
|
import { gunzipSync, gzipSync } from "node:zlib";
|
|
9
10
|
//#region src/error.ts
|
|
10
11
|
/**
|
|
@@ -170,6 +171,111 @@ function assertDeclaredFiles(pkg, published) {
|
|
|
170
171
|
if (missing.length > 0) throw new PublishCleanError(`Manifest declares files missing from packed artifact:\n${missing.map((item) => item.path).join("\n")}`);
|
|
171
172
|
}
|
|
172
173
|
//#endregion
|
|
174
|
+
//#region src/command.ts
|
|
175
|
+
/**
|
|
176
|
+
* Runs the external tools this CLI depends on: `pnpm`, `npm` and `git`.
|
|
177
|
+
*
|
|
178
|
+
* Never `{ shell: true }`. It space-joins the argument vector with no escaping at all, which
|
|
179
|
+
* Node runtime-deprecated in v24 as shell injection (DEP0190) — and this tool forwards
|
|
180
|
+
* arguments a caller wrote after `--` straight into `npm publish`, so that vector is
|
|
181
|
+
* attacker-shaped by design. Every spawn here passes an argument vector, never a command line.
|
|
182
|
+
*/
|
|
183
|
+
/**
|
|
184
|
+
* The probe below is bounded because a wedged shim would otherwise hang the publish with no
|
|
185
|
+
* end: `execFileSync` blocks this thread, so no timer here could ever interrupt it. The bound
|
|
186
|
+
* belongs on the spawn itself. It stays generous because the only job is to separate a tool
|
|
187
|
+
* that answers from one that never will.
|
|
188
|
+
*/
|
|
189
|
+
const TOOL_PROBE_TIMEOUT_MS = 1e4;
|
|
190
|
+
/**
|
|
191
|
+
* Windows cannot launch `pnpm` or `npm` directly: both are `.cmd` shims there, and Node's own
|
|
192
|
+
* documentation states a `.cmd` "cannot be launched using child_process.execFile()" — so the
|
|
193
|
+
* spawn fails as ENOENT and the probe below would report a working package manager as missing.
|
|
194
|
+
* Of the three routes Node names, this is the one that adds no parsing of our own: cmd.exe runs
|
|
195
|
+
* the shim AND does the PATH/PATHEXT lookup, so no name resolution belongs here either.
|
|
196
|
+
*
|
|
197
|
+
* `/d` skips registry AutoRun commands, which would otherwise execute inside a publish. Neither
|
|
198
|
+
* `/s` nor `windowsVerbatimArguments` is used: without them Node applies its ordinary C-runtime
|
|
199
|
+
* quoting to every argument, exactly as on any other platform, and there is no second escaping
|
|
200
|
+
* layer to get wrong. The one residual is cmd's `%VAR%` expansion inside an argument, which no
|
|
201
|
+
* argument this tool generates contains; a caller writing one after `--` gets it expanded.
|
|
202
|
+
*/
|
|
203
|
+
function spawnArgs(command, args) {
|
|
204
|
+
return process.platform === "win32" ? ["cmd.exe", [
|
|
205
|
+
"/d",
|
|
206
|
+
"/c",
|
|
207
|
+
command,
|
|
208
|
+
...args
|
|
209
|
+
]] : [command, [...args]];
|
|
210
|
+
}
|
|
211
|
+
function run(command, args, cwd) {
|
|
212
|
+
return execFileSync(...spawnArgs(command, args), {
|
|
213
|
+
cwd,
|
|
214
|
+
encoding: "utf8",
|
|
215
|
+
stdio: [
|
|
216
|
+
"ignore",
|
|
217
|
+
"pipe",
|
|
218
|
+
"pipe"
|
|
219
|
+
]
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* Runs a command with its streams attached to this process instead of captured.
|
|
224
|
+
*
|
|
225
|
+
* Reserved for `npm publish`. Every other command here is run for its output or its
|
|
226
|
+
* effect, but the publish is the one irreversible step, and npm's output is the only
|
|
227
|
+
* receipt the operator gets: the version that went out, the tarball size, the integrity
|
|
228
|
+
* hash, and the registry's own wording when it refuses. `run` would swallow all of it on
|
|
229
|
+
* success and hold the failure text until the process exits, which in CI means a log
|
|
230
|
+
* that says nothing about the one action that cannot be undone.
|
|
231
|
+
*/
|
|
232
|
+
function runAttached(command, args, cwd) {
|
|
233
|
+
execFileSync(...spawnArgs(command, args), {
|
|
234
|
+
cwd,
|
|
235
|
+
stdio: [
|
|
236
|
+
"ignore",
|
|
237
|
+
"inherit",
|
|
238
|
+
"inherit"
|
|
239
|
+
]
|
|
240
|
+
});
|
|
241
|
+
}
|
|
242
|
+
/** Child output survives only on the thrown error, and is lost unless read off it here. */
|
|
243
|
+
function outputFromError(error, key) {
|
|
244
|
+
if (!isObject(error)) return "";
|
|
245
|
+
let output = error[key];
|
|
246
|
+
return typeof output == "string" ? output.trim() : output instanceof Uint8Array ? Buffer.from(output).toString("utf8").trim() : "";
|
|
247
|
+
}
|
|
248
|
+
/**
|
|
249
|
+
* A required tool can fail three ways, and each one asks something different of the
|
|
250
|
+
* reader, so the probe reports what it observed instead of assuming the common case.
|
|
251
|
+
* A version-manager shim (asdf, mise, volta, corepack) resolves in PATH and still refuses
|
|
252
|
+
* to run when no version is pinned; calling that absence sends the reader to verify the
|
|
253
|
+
* one thing already correct, and `which pnpm` then agrees with them and not with us. The
|
|
254
|
+
* shim's own message names the fix, so it is forwarded rather than replaced.
|
|
255
|
+
*/
|
|
256
|
+
function toolFailureReason(cause) {
|
|
257
|
+
if (isObject(cause)) {
|
|
258
|
+
if (cause.code === "ENOENT") return "is not available in PATH";
|
|
259
|
+
if (cause.code === "ETIMEDOUT") return `did not answer --version within ${TOOL_PROBE_TIMEOUT_MS}ms`;
|
|
260
|
+
}
|
|
261
|
+
let stderr = outputFromError(cause, "stderr");
|
|
262
|
+
return `failed to run${stderr ? `: ${stderr}` : ""}`;
|
|
263
|
+
}
|
|
264
|
+
function requireTool(name) {
|
|
265
|
+
try {
|
|
266
|
+
execFileSync(...spawnArgs(name, ["--version"]), {
|
|
267
|
+
stdio: [
|
|
268
|
+
"ignore",
|
|
269
|
+
"ignore",
|
|
270
|
+
"pipe"
|
|
271
|
+
],
|
|
272
|
+
timeout: TOOL_PROBE_TIMEOUT_MS
|
|
273
|
+
});
|
|
274
|
+
} catch (cause) {
|
|
275
|
+
throw new PublishCleanError(`Required tool "${name}" ${toolFailureReason(cause)}.`, { cause });
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
//#endregion
|
|
173
279
|
//#region src/manifest.ts
|
|
174
280
|
/**
|
|
175
281
|
* What the published `package.json` carries: which fields survive cleaning, which are refused,
|
|
@@ -342,13 +448,41 @@ function assertPublicPackage(pkg) {
|
|
|
342
448
|
function assertFilesField(pkg, skip) {
|
|
343
449
|
if (!skip && (!Array.isArray(pkg.files) || pkg.files.length === 0)) throw new PublishCleanError("Package manifest must define a non-empty \"files\" array.");
|
|
344
450
|
}
|
|
451
|
+
/**
|
|
452
|
+
* Every key this tool reads out of the manifest's `publish-clean` block. Naming them is what
|
|
453
|
+
* makes a typo an error instead of a silent no-op — and a silent no-op here is not cosmetic:
|
|
454
|
+
* `devFeilds` publishes the field the author meant to strip, and nothing in the output says so.
|
|
455
|
+
*/
|
|
456
|
+
const CONFIG_KEYS = /* @__PURE__ */ new Set([
|
|
457
|
+
"allowSuspicious",
|
|
458
|
+
"devFields",
|
|
459
|
+
"keepFields",
|
|
460
|
+
"noGitChecks",
|
|
461
|
+
"registry",
|
|
462
|
+
"skipFileCheck"
|
|
463
|
+
]);
|
|
345
464
|
function packageConfig(pkg) {
|
|
346
465
|
let config = pkg["publish-clean"];
|
|
347
|
-
|
|
466
|
+
if (!isObject(config)) return {};
|
|
467
|
+
let unknown = Object.keys(config).filter((key) => !CONFIG_KEYS.has(key));
|
|
468
|
+
if (unknown.length > 0) throw new PublishCleanError(`Unknown "publish-clean" manifest options:\n${unknown.join("\n")}\nValid options: ${[...CONFIG_KEYS].join(", ")}`);
|
|
469
|
+
return config;
|
|
470
|
+
}
|
|
471
|
+
/**
|
|
472
|
+
* Reads a string-list option, refusing anything else outright rather than filtering it out.
|
|
473
|
+
* A number or a nested object in this list is a mistake in the manifest, and skipping it
|
|
474
|
+
* silently means the author's intent is lost with no signal anywhere.
|
|
475
|
+
*/
|
|
476
|
+
function stringList(config, key) {
|
|
477
|
+
let value = config[key];
|
|
478
|
+
if (value === void 0) return [];
|
|
479
|
+
if (!Array.isArray(value) || value.some((entry) => typeof entry != "string")) throw new PublishCleanError(`publish-clean.${key} must be an array of strings.`);
|
|
480
|
+
return value;
|
|
348
481
|
}
|
|
349
482
|
function customDevFields(config) {
|
|
350
|
-
|
|
351
|
-
|
|
483
|
+
let fields = stringList(config, "devFields"), kept = new Set(stringList(config, "keepFields")), contradictory = fields.filter((field) => kept.has(field));
|
|
484
|
+
if (contradictory.length > 0) throw new PublishCleanError(`These fields are listed as both devFields and keepFields, which asks to strip and to publish the same key:\n${contradictory.join("\n")}`);
|
|
485
|
+
let unsafe = fields.filter((field) => RUNTIME_MANIFEST_FIELDS.has(field));
|
|
352
486
|
if (unsafe.length > 0) throw new PublishCleanError(`publish-clean.devFields cannot remove runtime/public manifest fields:\n${unsafe.join("\n")}`);
|
|
353
487
|
return fields;
|
|
354
488
|
}
|
|
@@ -364,12 +498,13 @@ function customDevFields(config) {
|
|
|
364
498
|
* next one, including a real leak.
|
|
365
499
|
*/
|
|
366
500
|
function keptFields(config) {
|
|
367
|
-
return
|
|
501
|
+
return stringList(config, "keepFields");
|
|
368
502
|
}
|
|
369
503
|
//#endregion
|
|
370
504
|
//#region src/tarball.ts
|
|
371
505
|
/**
|
|
372
|
-
*
|
|
506
|
+
* Reads and rewrites a packed npm tarball. The only place this tool decodes or authors
|
|
507
|
+
* archive bytes, and the only reader every guard consults.
|
|
373
508
|
*
|
|
374
509
|
* The pipeline packs once, with pnpm, because that packer decides the file set. Cleaning the
|
|
375
510
|
* manifest by unpacking and packing again hands that decision to a second packer, which
|
|
@@ -379,9 +514,15 @@ function keptFields(config) {
|
|
|
379
514
|
* into.
|
|
380
515
|
*
|
|
381
516
|
* Every entry other than the manifest is copied as opaque bytes and never decoded, so entry
|
|
382
|
-
* shapes this code does not model — pax extended headers, ustar prefix splitting
|
|
383
|
-
*
|
|
384
|
-
*
|
|
517
|
+
* shapes this code does not model — pax extended headers, ustar prefix splitting — survive
|
|
518
|
+
* untouched. Only walking is universal: an entry's length is always its header block plus its
|
|
519
|
+
* size rounded up to a block, whatever the type.
|
|
520
|
+
*
|
|
521
|
+
* Reading here rather than through the `tar` binary is what makes the whole tool depend on
|
|
522
|
+
* nothing but Node: one archive is decompressed once and answers every question about it
|
|
523
|
+
* (file list, manifest bytes, rewrite), instead of one spawn and one decompression per
|
|
524
|
+
* question. It is also the stricter reader — `tar tzf` prints one name per line, so a path
|
|
525
|
+
* containing a newline arrives as two entries there and as itself here.
|
|
385
526
|
*/
|
|
386
527
|
const MANIFEST_PATH = "package/package.json", PAX_TYPES = /* @__PURE__ */ new Set(["x", "g"]);
|
|
387
528
|
function field(block, offset, length) {
|
|
@@ -413,32 +554,72 @@ function reheader(original, size) {
|
|
|
413
554
|
return header.write(sum.toString(8).padStart(6, "0") + "\0 ", 148, 8, "ascii"), header;
|
|
414
555
|
}
|
|
415
556
|
/**
|
|
416
|
-
*
|
|
557
|
+
* Decodes a gzipped tarball into its entries, refusing every shape whose meaning this tool
|
|
558
|
+
* cannot state unambiguously.
|
|
417
559
|
*
|
|
418
|
-
*
|
|
419
|
-
*
|
|
420
|
-
*
|
|
560
|
+
* A duplicate manifest is a refusal rather than a last-one-wins guess, because extractors
|
|
561
|
+
* disagree about which survives and the published manifest would then depend on the extractor
|
|
562
|
+
* rather than on this tool. A short final block is a truncation: an archive that ends
|
|
563
|
+
* mid-entry would otherwise read as a valid one that simply stops, which is exactly how a
|
|
564
|
+
* partial write becomes a published package.
|
|
421
565
|
*/
|
|
422
|
-
function
|
|
423
|
-
let tar = gunzipSync(
|
|
566
|
+
function readArchive(gzipped) {
|
|
567
|
+
let tar = gunzipSync(gzipped), entries = [], tail = null;
|
|
424
568
|
for (let offset = 0; offset < tar.length;) {
|
|
425
|
-
let header = tar.subarray(offset, offset + 512)
|
|
569
|
+
let header = tar.subarray(offset, offset + 512);
|
|
570
|
+
if (header.length < 512) throw new PublishCleanError("Tarball ends mid-header; the archive is truncated.");
|
|
571
|
+
let name = field(header, 0, 100);
|
|
426
572
|
if (name === "") {
|
|
427
|
-
|
|
573
|
+
tail = tar.subarray(offset);
|
|
428
574
|
break;
|
|
429
575
|
}
|
|
430
|
-
let size = entrySize(header), end = offset + 512 + 512 * Math.ceil(size / 512)
|
|
576
|
+
let size = entrySize(header), end = offset + 512 + 512 * Math.ceil(size / 512);
|
|
577
|
+
if (end > tar.length) throw new PublishCleanError(`Tarball entry ${name} runs past the end of the archive.`);
|
|
578
|
+
let type = field(header, 156, 1), body = tar.subarray(offset + 512, offset + 512 + size);
|
|
431
579
|
if (type === "L") throw new PublishCleanError("Tarball uses GNU long-name entries, which this tool refuses.");
|
|
432
|
-
if (PAX_TYPES.has(type) && assertNoManifestOverride(
|
|
433
|
-
if (replaced) throw new PublishCleanError(`Tarball contains ${MANIFEST_PATH} more than once.`);
|
|
580
|
+
if (PAX_TYPES.has(type) && assertNoManifestOverride(body), name === MANIFEST_PATH) {
|
|
434
581
|
if (type !== "0" && type !== "") throw new PublishCleanError(`${MANIFEST_PATH} is not a regular file in the tarball.`);
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
582
|
+
if (entries.some((entry) => entry.name === MANIFEST_PATH)) throw new PublishCleanError(`Tarball contains ${MANIFEST_PATH} more than once.`);
|
|
583
|
+
}
|
|
584
|
+
entries.push({
|
|
585
|
+
name,
|
|
586
|
+
type,
|
|
587
|
+
header,
|
|
588
|
+
body,
|
|
589
|
+
raw: tar.subarray(offset, end)
|
|
590
|
+
}), offset = end;
|
|
439
591
|
}
|
|
440
|
-
if (
|
|
441
|
-
return
|
|
592
|
+
if (tail === null) throw new PublishCleanError("Tarball has no end-of-archive marker; the archive is truncated.");
|
|
593
|
+
return {
|
|
594
|
+
entries,
|
|
595
|
+
tail
|
|
596
|
+
};
|
|
597
|
+
}
|
|
598
|
+
/**
|
|
599
|
+
* The paths a consumer's installer writes, with the `package/` prefix stripped — the list every
|
|
600
|
+
* content guard judges. Directories and pax headers are dropped: neither is a file anyone
|
|
601
|
+
* imports, and a pax header's own name (`PaxHeader`) names no file at all.
|
|
602
|
+
*/
|
|
603
|
+
function packageFiles(archive) {
|
|
604
|
+
return archive.entries.filter((entry) => entry.type !== "5" && !PAX_TYPES.has(entry.type)).map((entry) => entry.name.startsWith("package/") ? entry.name.slice(8) : entry.name).filter((name) => name.length > 0 && !name.endsWith("/")).sort();
|
|
605
|
+
}
|
|
606
|
+
function manifestEntry(archive) {
|
|
607
|
+
let entry = archive.entries.find((candidate) => candidate.name === MANIFEST_PATH);
|
|
608
|
+
if (!entry) throw new PublishCleanError(`Tarball does not contain ${MANIFEST_PATH}.`);
|
|
609
|
+
return entry;
|
|
610
|
+
}
|
|
611
|
+
/** The manifest exactly as the archive carries it, for parsing by the caller. */
|
|
612
|
+
function manifestText(archive) {
|
|
613
|
+
return manifestEntry(archive).body.toString("utf8");
|
|
614
|
+
}
|
|
615
|
+
/** Returns the gzipped tarball with `package/package.json` replaced by `manifest`. */
|
|
616
|
+
function replaceManifest(archive, manifest) {
|
|
617
|
+
let target = manifestEntry(archive), body = Buffer.from(manifest, "utf8"), parts = archive.entries.map((entry) => entry === target ? Buffer.concat([
|
|
618
|
+
reheader(entry.header, body.length),
|
|
619
|
+
body,
|
|
620
|
+
Buffer.alloc(512 * Math.ceil(body.length / 512) - body.length)
|
|
621
|
+
]) : entry.raw);
|
|
622
|
+
return parts.push(archive.tail), gzipSync(Buffer.concat(parts), { level: 9 });
|
|
442
623
|
}
|
|
443
624
|
//#endregion
|
|
444
625
|
//#region src/trusted-publish.ts
|
|
@@ -502,9 +683,15 @@ function assertRepositoryForTrustedPublish(pkg, publishArgs, env) {
|
|
|
502
683
|
if (!repoUrl) throw new PublishCleanError("GitHub trusted publishing requires package.json repository.url to match GITHUB_REPOSITORY.");
|
|
503
684
|
if (githubRepositorySlug(repoUrl) !== env.GITHUB_REPOSITORY) throw new PublishCleanError(`package.json repository.url must match GITHUB_REPOSITORY (${env.GITHUB_REPOSITORY}); found ${repoUrl}.`);
|
|
504
685
|
}
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
686
|
+
/**
|
|
687
|
+
* Read from the installed manifest rather than baked in at build time, so the number cannot
|
|
688
|
+
* drift from the package a user actually has — which is the only reason anyone asks a tool
|
|
689
|
+
* for its version.
|
|
690
|
+
*/
|
|
691
|
+
function ownVersion() {
|
|
692
|
+
let manifest = readJson(fileURLToPath(new URL("../package.json", import.meta.url)));
|
|
693
|
+
return typeof manifest.version == "string" ? manifest.version : "unknown";
|
|
694
|
+
}
|
|
508
695
|
function readJson(file) {
|
|
509
696
|
let parsed;
|
|
510
697
|
try {
|
|
@@ -515,78 +702,6 @@ function readJson(file) {
|
|
|
515
702
|
if (!isObject(parsed)) throw new PublishCleanError(`${file} must contain a JSON object.`);
|
|
516
703
|
return parsed;
|
|
517
704
|
}
|
|
518
|
-
function run(command, args, cwd) {
|
|
519
|
-
return execFileSync(command, [...args], {
|
|
520
|
-
cwd,
|
|
521
|
-
encoding: "utf8",
|
|
522
|
-
stdio: [
|
|
523
|
-
"ignore",
|
|
524
|
-
"pipe",
|
|
525
|
-
"pipe"
|
|
526
|
-
]
|
|
527
|
-
});
|
|
528
|
-
}
|
|
529
|
-
function outputFromError(error, key) {
|
|
530
|
-
if (!isObject(error)) return "";
|
|
531
|
-
let output = error[key];
|
|
532
|
-
return typeof output == "string" ? output.trim() : output instanceof Uint8Array ? Buffer.from(output).toString("utf8").trim() : "";
|
|
533
|
-
}
|
|
534
|
-
/**
|
|
535
|
-
* Runs a command with its streams attached to this process instead of captured.
|
|
536
|
-
*
|
|
537
|
-
* Reserved for `npm publish`. Every other command here is run for its output or its
|
|
538
|
-
* effect, but the publish is the one irreversible step, and npm's output is the only
|
|
539
|
-
* receipt the operator gets: the version that went out, the tarball size, the integrity
|
|
540
|
-
* hash, and the registry's own wording when it refuses. `run` would swallow all of it on
|
|
541
|
-
* success and hold the failure text until the process exits, which in CI means a log
|
|
542
|
-
* that says nothing about the one action that cannot be undone.
|
|
543
|
-
*/
|
|
544
|
-
function runAttached(command, args, cwd) {
|
|
545
|
-
execFileSync(command, [...args], {
|
|
546
|
-
cwd,
|
|
547
|
-
stdio: [
|
|
548
|
-
"ignore",
|
|
549
|
-
"inherit",
|
|
550
|
-
"inherit"
|
|
551
|
-
]
|
|
552
|
-
});
|
|
553
|
-
}
|
|
554
|
-
/**
|
|
555
|
-
* A required tool can fail three ways, and each one asks something different of the
|
|
556
|
-
* reader, so the probe reports what it observed instead of assuming the common case.
|
|
557
|
-
* A version-manager shim (asdf, mise, volta, corepack) resolves in PATH and still refuses
|
|
558
|
-
* to run when no version is pinned; calling that absence sends the reader to verify the
|
|
559
|
-
* one thing already correct, and `which pnpm` then agrees with them and not with us. The
|
|
560
|
-
* shim's own message names the fix, so it is forwarded rather than replaced.
|
|
561
|
-
*/
|
|
562
|
-
function toolFailureReason(cause) {
|
|
563
|
-
if (isObject(cause)) {
|
|
564
|
-
if (cause.code === "ENOENT") return "is not available in PATH";
|
|
565
|
-
if (cause.code === "ETIMEDOUT") return `did not answer --version within ${TOOL_PROBE_TIMEOUT_MS}ms`;
|
|
566
|
-
}
|
|
567
|
-
let stderr = outputFromError(cause, "stderr");
|
|
568
|
-
return `is present but failed to run${stderr ? `: ${stderr}` : ""}`;
|
|
569
|
-
}
|
|
570
|
-
/**
|
|
571
|
-
* The probe is bounded because a wedged shim would otherwise hang the publish with no end:
|
|
572
|
-
* `execFileSync` blocks this thread, so no timer here could ever interrupt it. The bound
|
|
573
|
-
* belongs on the spawn itself. It stays generous because the only job is to separate a
|
|
574
|
-
* tool that answers from one that never will.
|
|
575
|
-
*/
|
|
576
|
-
function requireTool(name) {
|
|
577
|
-
try {
|
|
578
|
-
execFileSync(name, ["--version"], {
|
|
579
|
-
stdio: [
|
|
580
|
-
"ignore",
|
|
581
|
-
"ignore",
|
|
582
|
-
"pipe"
|
|
583
|
-
],
|
|
584
|
-
timeout: TOOL_PROBE_TIMEOUT_MS
|
|
585
|
-
});
|
|
586
|
-
} catch (cause) {
|
|
587
|
-
throw new PublishCleanError(`Required tool "${name}" ${toolFailureReason(cause)}.`, { cause });
|
|
588
|
-
}
|
|
589
|
-
}
|
|
590
705
|
function npmVersion() {
|
|
591
706
|
let raw = run("npm", ["--version"], process.cwd()).trim(), parts = raw.split(".").map((part) => Number.parseInt(part, 10));
|
|
592
707
|
if (parts.length < 3 || parts.some((part) => Number.isNaN(part))) throw new PublishCleanError(`Unable to parse npm version: ${raw}`);
|
|
@@ -633,34 +748,27 @@ function assertCleanGit(packageDir, skip) {
|
|
|
633
748
|
], packageDir).trim();
|
|
634
749
|
if (output) throw new PublishCleanError(`Source package has uncommitted changes:\n${output}`);
|
|
635
750
|
} catch (error) {
|
|
636
|
-
|
|
751
|
+
if (error instanceof PublishCleanError) throw error;
|
|
752
|
+
let stderr = outputFromError(error, "stderr");
|
|
753
|
+
throw new PublishCleanError(`Unable to verify source git status${stderr ? `: ${stderr}` : ""}.\nPass --no-git-checks to publish without this check.`, { cause: error });
|
|
637
754
|
}
|
|
638
755
|
}
|
|
639
756
|
/**
|
|
640
|
-
*
|
|
641
|
-
*
|
|
642
|
-
*
|
|
643
|
-
*
|
|
644
|
-
* `tar tzf` prints one name per line, so a filename containing a newline would arrive as two
|
|
645
|
-
* entries. That is safe in the only direction that matters, because every guard here fails
|
|
646
|
-
* closed: splitting a name can only add entries to a leak scan that refuses on any match, and a
|
|
647
|
-
* declared path whose name was split is then absent and refused as missing.
|
|
757
|
+
* Reads an archive from disk, so every judgement is made about bytes that exist as a file
|
|
758
|
+
* rather than about a buffer this process is holding. The final artifact is read back this
|
|
759
|
+
* way after it is written, which also proves the write itself landed whole.
|
|
648
760
|
*/
|
|
649
|
-
function
|
|
650
|
-
return
|
|
761
|
+
async function readTarball(tarball) {
|
|
762
|
+
return readArchive(await readFile(tarball));
|
|
651
763
|
}
|
|
652
|
-
function
|
|
764
|
+
function manifestOf(archive, label) {
|
|
653
765
|
let parsed;
|
|
654
766
|
try {
|
|
655
|
-
parsed = JSON.parse(
|
|
656
|
-
"xOzf",
|
|
657
|
-
tarball,
|
|
658
|
-
`package/${file}`
|
|
659
|
-
], cwd));
|
|
767
|
+
parsed = JSON.parse(manifestText(archive));
|
|
660
768
|
} catch (cause) {
|
|
661
|
-
throw new PublishCleanError(`Unable to
|
|
769
|
+
throw new PublishCleanError(`Unable to parse package.json inside ${label}.`, { cause });
|
|
662
770
|
}
|
|
663
|
-
if (!isObject(parsed)) throw new PublishCleanError(
|
|
771
|
+
if (!isObject(parsed)) throw new PublishCleanError(`package.json inside ${label} must contain a JSON object.`);
|
|
664
772
|
return parsed;
|
|
665
773
|
}
|
|
666
774
|
/**
|
|
@@ -682,10 +790,10 @@ async function soleTarball(packRoot) {
|
|
|
682
790
|
return path.join(packRoot, tarball);
|
|
683
791
|
}
|
|
684
792
|
async function packAndClean(packageDir, opts) {
|
|
685
|
-
requireTool("pnpm"), requireTool("npm"),
|
|
793
|
+
requireTool("pnpm"), requireTool("npm"), warnIfNonPnpmLifecycle();
|
|
686
794
|
let sourcePkg = readJson(path.join(packageDir, "package.json"));
|
|
687
795
|
!opts.guardOnly && !opts.dryRun && assertTrustedPublishingRuntime(sourcePkg, opts.publishArgs);
|
|
688
|
-
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);
|
|
796
|
+
let config = packageConfig(sourcePkg), skipFileCheck = opts.skipFileCheck || config.skipFileCheck === !0, allowSuspicious = opts.allowSuspicious || config.allowSuspicious === !0, noGitChecks = opts.noGitChecks || config.noGitChecks === !0, registry = opts.registry ?? (typeof config.registry == "string" ? config.registry : null), extraDevFields = customDevFields(config), keepFields = keptFields(config);
|
|
689
797
|
assertPublicPackage(sourcePkg), assertCleanGit(packageDir, noGitChecks), assertFilesField(sourcePkg, skipFileCheck);
|
|
690
798
|
let root = await mkdtemp(path.join(tmpdir(), "publish-clean-"));
|
|
691
799
|
try {
|
|
@@ -694,15 +802,15 @@ async function packAndClean(packageDir, opts) {
|
|
|
694
802
|
"--pack-destination",
|
|
695
803
|
root
|
|
696
804
|
], packageDir);
|
|
697
|
-
let tarball = await soleTarball(root), cleanedPkg = withRegistry(stripManifest(
|
|
805
|
+
let tarball = await soleTarball(root), packed = await readTarball(tarball), cleanedPkg = withRegistry(stripManifest(manifestOf(packed, "the packed tarball"), extraDevFields), registry), unrecognized = unrecognizedFieldsReport(cleanedPkg, keepFields);
|
|
698
806
|
unrecognized && console.warn(unrecognized);
|
|
699
807
|
let publishRoot = path.join(root, "publish");
|
|
700
808
|
await mkdir(publishRoot);
|
|
701
809
|
let finalTarball = path.join(publishRoot, path.basename(tarball));
|
|
702
|
-
await writeFile(finalTarball,
|
|
703
|
-
let
|
|
704
|
-
assertSameEntries(
|
|
705
|
-
let shippedPkg =
|
|
810
|
+
await writeFile(finalTarball, replaceManifest(packed, stringifyJson(cleanedPkg)));
|
|
811
|
+
let published = await readTarball(finalTarball), finalFiles = packageFiles(published);
|
|
812
|
+
assertSameEntries(packageFiles(packed), finalFiles), validatePackedFiles(finalFiles, allowSuspicious), assertDeclaredFiles(cleanedPkg, finalFiles);
|
|
813
|
+
let shippedPkg = manifestOf(published, "the published tarball");
|
|
706
814
|
if (assertNoMonorepoProtocols(shippedPkg), assertNoLostConsumerFields(sourcePkg, shippedPkg, extraDevFields), stableJson(shippedPkg) !== stableJson(cleanedPkg)) throw new PublishCleanError("Rewritten tarball manifest differs from the cleaned manifest.");
|
|
707
815
|
if (opts.tarballOut !== null) {
|
|
708
816
|
await mkdir(opts.tarballOut, { recursive: !0 });
|
|
@@ -739,6 +847,10 @@ async function main() {
|
|
|
739
847
|
args: cliArgs,
|
|
740
848
|
allowPositionals: !0,
|
|
741
849
|
options: {
|
|
850
|
+
"allow-suspicious": {
|
|
851
|
+
type: "boolean",
|
|
852
|
+
default: !1
|
|
853
|
+
},
|
|
742
854
|
"dry-run": {
|
|
743
855
|
type: "boolean",
|
|
744
856
|
default: !1
|
|
@@ -767,16 +879,26 @@ async function main() {
|
|
|
767
879
|
"tarball-out": {
|
|
768
880
|
type: "string",
|
|
769
881
|
default: void 0
|
|
882
|
+
},
|
|
883
|
+
version: {
|
|
884
|
+
type: "boolean",
|
|
885
|
+
short: "v",
|
|
886
|
+
default: !1
|
|
770
887
|
}
|
|
771
888
|
},
|
|
772
889
|
strict: !0
|
|
773
890
|
});
|
|
891
|
+
if (parsed.values.version) {
|
|
892
|
+
console.log(ownVersion());
|
|
893
|
+
return;
|
|
894
|
+
}
|
|
774
895
|
if (parsed.values.help) {
|
|
775
|
-
console.log("publish-clean [--dry-run
|
|
896
|
+
console.log("publish-clean [options] [package-dir] [-- npm publish args]\n\nPacks with pnpm, strips developer-only fields from the packed manifest, validates the\nartifact, and publishes that exact tarball with npm. Arguments after `--` go to\n`npm publish` untouched (e.g. --access public --tag next --provenance).\n\nOptions:\n --dry-run Pack, clean and validate; print the file list and manifest, publish nothing.\n --guard-only Same checks, no output and no publish. For a pre-publish gate.\n --tarball-out DIR Also write the validated tarball into DIR, for attestation or release upload.\n --registry URL Publish to URL, and record it in the artifact's publishConfig.\n --no-git-checks Publish from a working tree with uncommitted changes.\n --skip-file-check Allow a manifest with no \"files\" array.\n --allow-suspicious Allow tests, CI config, lockfiles or tsconfig in the published artifact.\n -h, --help Show this help.\n -v, --version Show the publish-clean version.\n\nManifest configuration, under a \"publish-clean\" key in package.json:\n devFields string[] Extra fields to strip. Refused for fields consumers resolve.\n keepFields string[] Fields to acknowledge, so they stop being reported as unrecognised.\n registry string Default for --registry.\n noGitChecks boolean Default for --no-git-checks.\n skipFileCheck boolean Default for --skip-file-check.\n allowSuspicious boolean Default for --allow-suspicious.\n\nRequires pnpm and npm on PATH. npm provenance additionally requires Node.js 22.14+ and\nnpm 11.5.1+, and only a cloud CI runner can produce it.");
|
|
776
897
|
return;
|
|
777
898
|
}
|
|
778
899
|
if (parsed.positionals.length > 1) throw new PublishCleanError(`Unexpected positional arguments before --:\n${parsed.positionals.slice(1).join("\n")}`);
|
|
779
900
|
await packAndClean(path.resolve(String(parsed.positionals[0] ?? ".")), {
|
|
901
|
+
allowSuspicious: parsed.values["allow-suspicious"] === !0,
|
|
780
902
|
dryRun: parsed.values["dry-run"] === !0,
|
|
781
903
|
guardOnly: parsed.values["guard-only"] === !0,
|
|
782
904
|
noGitChecks: parsed.values["no-git-checks"] === !0,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@anizoptera/publish-clean",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Pre-publish npm package cleaner that strips common useless noise and crap from package.json; prevents accidental publication of unwanted things and unresolved dependencies. No deps, one JS file.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"bun",
|
|
@@ -42,6 +42,6 @@
|
|
|
42
42
|
"provenance": true
|
|
43
43
|
},
|
|
44
44
|
"engines": {
|
|
45
|
-
"node": ">=22.
|
|
45
|
+
"node": ">=22.0.0"
|
|
46
46
|
}
|
|
47
47
|
}
|