@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.
Files changed (3) hide show
  1. package/README.md +28 -16
  2. package/dist/cli.js +250 -128
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -7,7 +7,7 @@ dependencies. No deps, one JS file.
7
7
  [![npm version](https://img.shields.io/npm/v/@anizoptera/publish-clean?label=npm)](https://www.npmjs.com/package/@anizoptera/publish-clean)
8
8
  [![Signed provenance](https://img.shields.io/badge/provenance-signed-2ea44f?logo=npm&logoColor=white)](https://www.npmjs.com/package/@anizoptera/publish-clean#provenance)
9
9
  [![CI](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml/badge.svg?branch=main)](https://github.com/Anizoptera/publish-clean/actions/workflows/check.yml)
10
- [![Node >=22.14](https://img.shields.io/badge/node-%3E%3D22.14-339933?logo=node.js&logoColor=white)](package.json)
10
+ [![Node >=22](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](package.json)
11
11
  [![Runtime deps](https://img.shields.io/badge/runtime_deps-0-2ea44f)](package.json)
12
12
  [![License](https://img.shields.io/github/license/Anizoptera/publish-clean)](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
- Also needs `tar` and Node.js 22.14+. Below 22.14 npm cannot mint provenance.
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`, `npm` and `tar` through the
54
- tools you already have. For something that sits on your publish path and handles your
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 | `package.json` | What it does |
330
- | ------------------- | --------------- | ------------------------------------------------------------------------------------------ |
331
- | `--dry-run` | - | Run everything up to the publish, then print the file list and the cleaned `package.json`. |
332
- | `--guard-only` | - | Run everything up to the publish and exit, printing nothing. |
333
- | `--tarball-out DIR` | - | Copy the final tarball into `DIR` before publishing. |
334
- | `--registry URL` | `registry` | Set `publishConfig.registry` on the cleaned manifest, and publish to it. |
335
- | `--skip-file-check` | `skipFileCheck` | Drop the suspicious-file check and the required `files` array. |
336
- | `--no-git-checks` | `noGitChecks` | Allow publishing from a dirty working tree. |
337
- | - | `devFields` | Extra manifest fields to strip. |
338
- | - | `keepFields` | Fields that belong in the published package, so stop reporting them. |
339
- | `-h`, `--help` | - | Print usage. |
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` does not touch the leak checks.
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
- return isObject(config) ? config : {};
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
- if (!Array.isArray(config.devFields)) return [];
351
- let fields = config.devFields.filter((field) => typeof field == "string"), unsafe = fields.filter((field) => RUNTIME_MANIFEST_FIELDS.has(field));
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 Array.isArray(config.keepFields) ? config.keepFields.filter((field) => typeof field == "string") : [];
501
+ return stringList(config, "keepFields");
368
502
  }
369
503
  //#endregion
370
504
  //#region src/tarball.ts
371
505
  /**
372
- * Replaces the manifest inside a packed tarball without repacking it.
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, GNU long
383
- * names — survive untouched. Only walking is universal: an entry's length is always its
384
- * header block plus its size rounded up to a block, whatever the type.
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
- * Returns the gzipped tarball with `package/package.json` replaced by `manifest`.
557
+ * Decodes a gzipped tarball into its entries, refusing every shape whose meaning this tool
558
+ * cannot state unambiguously.
417
559
  *
418
- * Refuses anything it cannot rewrite unambiguously. Duplicate manifest entries are a refusal
419
- * rather than a last-one-wins guess, because extractors disagree about which survives and the
420
- * published manifest would then depend on the extractor rather than on this tool.
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 replaceTarballManifest(archive, manifest) {
423
- let tar = gunzipSync(archive), parts = [], replaced = !1;
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), name = field(header, 0, 100);
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
- parts.push(tar.subarray(offset));
573
+ tail = tar.subarray(offset);
428
574
  break;
429
575
  }
430
- let size = entrySize(header), end = offset + 512 + 512 * Math.ceil(size / 512), type = field(header, 156, 1);
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(tar.subarray(offset + 512, offset + 512 + size)), name === MANIFEST_PATH) {
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
- let body = Buffer.from(manifest, "utf8");
436
- parts.push(reheader(header, body.length), body, Buffer.alloc(512 * Math.ceil(body.length / 512) - body.length)), replaced = !0;
437
- } else parts.push(tar.subarray(offset, end));
438
- offset = end;
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 (!replaced) throw new PublishCleanError(`Tarball does not contain ${MANIFEST_PATH}.`);
441
- return gzipSync(Buffer.concat(parts));
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
- //#endregion
506
- //#region src/cli.ts
507
- const TOOL_PROBE_TIMEOUT_MS = 1e4;
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
- throw error instanceof PublishCleanError ? error : new PublishCleanError("Unable to verify source git status.", { cause: error });
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
- * The file list every content guard judges, read out of the archive by `tar` rather than from
641
- * an extracted copy: this is the same enumeration a consumer's installer sees, and it needs no
642
- * filesystem to exist.
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 listTarballFiles(tarball, cwd) {
650
- return run("tar", ["tzf", tarball], cwd).trim().split("\n").filter(Boolean).map((file) => file.replaceAll(path.sep, "/")).map((file) => file.startsWith("package/") ? file.slice(8) : file).filter((file) => file.length > 0 && !file.endsWith("/")).sort();
761
+ async function readTarball(tarball) {
762
+ return readArchive(await readFile(tarball));
651
763
  }
652
- function readTarballJson(tarball, file, cwd) {
764
+ function manifestOf(archive, label) {
653
765
  let parsed;
654
766
  try {
655
- parsed = JSON.parse(run("tar", [
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 read JSON from ${path.basename(tarball)}: ${file}`, { cause });
769
+ throw new PublishCleanError(`Unable to parse package.json inside ${label}.`, { cause });
662
770
  }
663
- if (!isObject(parsed)) throw new PublishCleanError(`${file} in ${path.basename(tarball)} must contain a JSON object.`);
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"), requireTool("tar"), warnIfNonPnpmLifecycle();
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(readTarballJson(tarball, "package.json", root), extraDevFields), registry), unrecognized = unrecognizedFieldsReport(cleanedPkg, keepFields);
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, replaceTarballManifest(await readFile(tarball), stringifyJson(cleanedPkg)));
703
- let finalFiles = listTarballFiles(finalTarball, root);
704
- assertSameEntries(listTarballFiles(tarball, root), finalFiles), validatePackedFiles(finalFiles, skipFileCheck), assertDeclaredFiles(cleanedPkg, finalFiles);
705
- let shippedPkg = readTarballJson(finalTarball, "package.json", root);
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] [--guard-only] [--no-git-checks] [--registry URL] [--skip-file-check] [--tarball-out DIR] [package-dir] [-- npm-publish-args]");
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.5.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.14.0"
45
+ "node": ">=22.0.0"
46
46
  }
47
47
  }