From 65c890deb4da4a9b114bcf4db6bf6793c3b3637b Mon Sep 17 00:00:00 2001
From: Okiki Ojo <hey@okikio.dev>
Date: Sat, 7 Mar 2026 23:55:55 -0500
Subject: [PATCH] build(npm): clarify packaging choices and ensure clean output
 directory

Signed-off-by: Okiki Ojo <hey@okikio.dev>
---
 scripts/build_npm.ts | 28 ++++++++++++++++++----------
 1 file changed, 18 insertions(+), 10 deletions(-)

diff --git a/scripts/build_npm.ts b/scripts/build_npm.ts
index a75c730..5ee6f0b 100644
--- a/scripts/build_npm.ts
+++ b/scripts/build_npm.ts
@@ -7,15 +7,21 @@
  *
  * Output is written to ./npm/ and is gitignored. The directory is
  * cleared on each run so stale artifacts never bleed through.
+ *
+ * This script is intentionally explicit about packaging choices because npm
+ * publishing is a boundary where accidental config drift is expensive. The
+ * comments below explain why the build opts into, or out of, each dnt feature.
  */
-import { build, emptyDir } from "jsr:@deno/dnt";
-import denoJson from "../deno.json" with { type: "json" };
+import { build, emptyDir } from 'jsr:@deno/dnt';
+import denoJson from '../deno.json' with { type: 'json' };
 
-await emptyDir("./npm");
+// Start from a clean output directory so removed entry points or metadata do
+// not survive from a previous build and confuse package inspection.
+await emptyDir('./npm');
 
 await build({
-  entryPoints: ["./mod.ts"],
-  outDir: "./npm",
+  entryPoints: ['./mod.ts'],
+  outDir: './npm',
 
   // mod.ts uses no Deno-specific globals (no Deno.*, no std/ imports),
   // so no shims are required.
@@ -72,14 +78,16 @@ await build({
     // in April 2025; targeting 20+ keeps the engines field accurate and
     // prevents installation on unsupported runtimes.
     engines: {
-      node: ">=24",
+      node: '>=24',
     },
   },
 
   postBuild() {
-    // Copy the non-code files that should travel with the npm package.
-    Deno.copyFileSync("license", "npm/license");
-    Deno.copyFileSync("readme.md", "npm/readme.md");
-    Deno.copyFileSync("changelog.md", "npm/changelog.md");
+    // dnt only handles code and generated package metadata. The project docs
+    // and license still need to be copied explicitly so the npm tarball tells
+    // the same story as the source repository.
+    Deno.copyFileSync('license', 'npm/license');
+    Deno.copyFileSync('readme.md', 'npm/readme.md');
+    Deno.copyFileSync('changelog.md', 'npm/changelog.md');
   },
 });
-- 
2.51.2