build: stage beside dist/, not inside it

The staging directory was dist/.build-XXXXXX. A build that is killed cannot remove it, the next build removed
only its own, and "files": ["dist"] put the leftover into the npm tarball. .gitignore hid it from git status and
the freshness test skipped every name starting with ".build-", so nothing reported it.

The staging directory is now .dist-staging beside the output (.<name>-staging for --out <dir>) and is cleared at
the start of each build. The freshness test no longer skips anything: a stray file under dist/ fails it.

Checked in a scratch copy: a build stopped with SIGKILL after 1.5 s leaves .dist-staging/ and an unchanged dist/;
npm pack lists 36 files, none from the staging directory; the next build removes it. New test for the same on a
temporary package. npm test: 28 pass in 8.2-9.5 s.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.gitignore

@@ -1,4 +1,4 @@
 node_modules/
 .env
-# the staging directory of a build that was killed (scripts/build.mjs removes it otherwise)
+# the staging directory of a build that was killed (scripts/build.mjs removes it on the next run)
-dist/.build-*/
+/.dist-staging/

scripts/build.mjs

@@ -4,13 +4,14 @@
 //
 // Two compiler runs over src/: CommonJS with its declarations (cjs/, types/), then ES modules with theirs (esm/).
 // TypeScript reads a .d.ts as CommonJS or as an ES module by the package.json above it, so each build needs its own
-// set: the one in types/ would tell an ES module consumer that a default import works. Both runs write to a staging
+// set: the one in types/ would tell an ES module consumer that a default import works.
-// directory that replaces the three directories only after both passed, so a failed build leaves the tracked dist/
+//
-// as it was. Files of sources that no longer exist go with the old directories.
+// Both runs write to a staging directory that replaces the three directories only after both passed, so a failed
+// build leaves the tracked dist/ as it was. Files of sources that no longer exist go with the old directories.
 import { spawnSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -33,12 +34,15 @@ let out;
 let staging;
 try {
   out = outputDirectory(process.argv.slice(2));
-  mkdirSync(out, { recursive: true });
+  // Beside the output, not in it: the package ships all of dist/, and a build that is killed cannot remove its
-  staging = mkdtempSync(join(out, ".build-"));
+  // staging directory - the next build does. Same parent directory, so the renames below stay on one filesystem.
+  staging = join(dirname(out), `.${basename(out)}-staging`);
+  rmSync(staging, { recursive: true, force: true });
   compile("tsconfig.cjs.json", ["--outDir", join(staging, "cjs"), "--declarationDir", join(staging, "types")]);
   compile("tsconfig.esm.json", ["--outDir", join(staging, "esm")]);
   // The package is "type": "commonjs"; this marks the .js files under esm/ as ES modules.
   writeFileSync(join(staging, "esm", "package.json"), JSON.stringify({ type: "module" }, null, 2) + "\n");
+  mkdirSync(out, { recursive: true });
   for (const part of ["cjs", "esm", "types"]) {
     rmSync(join(out, part), { recursive: true, force: true });
     renameSync(join(staging, part), join(out, part));

test/build.test.js

@@ -44,6 +44,22 @@ function build(dir, ...args) {
   return spawnSync(process.execPath, [path.join(dir, "scripts", "build.mjs"), ...args], { encoding: "utf8" });
 }
 
+test("a build replaces dist/ whole and clears the staging directory a killed build left beside it", (t) => {
+  const dir = scratchPackage(t, "export const port = 1883;\n");
+  fs.mkdirSync(path.join(dir, ".dist-staging", "cjs"), { recursive: true });
+  fs.writeFileSync(path.join(dir, ".dist-staging", "cjs", "Killed.js"), "");
+
+  const run = build(dir);
+  assert.equal(run.status, 0, run.stdout + run.stderr);
+  const inputs = /^(scripts|src|tsconfig)/;
+  assert.deepEqual(Object.keys(snapshot(dir)).filter((name) => !inputs.test(name)).sort(), [
+    "dist/",
+    "dist/cjs/", "dist/cjs/index.js",
+    "dist/esm/", "dist/esm/index.d.ts", "dist/esm/index.js", "dist/esm/package.json",
+    "dist/types/", "dist/types/index.d.ts",
+  ]);
+});
+
 test("a type error in src/: the build exits 1 and dist/ is as the earlier build left it", (t) => {
   const dir = scratchPackage(t, "export const port: number = \"1883\";\n");
   const before = snapshot(dir);

test/packaging.test.js

@@ -13,10 +13,9 @@ const pkg = require("alex2node/package.json");
 const ROOT = path.join(__dirname, "..");
 const DIST = path.join(ROOT, "dist");
 
-// Every file under dir, relative to it, sorted. A staging directory left by a killed build is not part of dist/.
+// Every file under dir, relative to it, sorted.
 function files(dir, prefix = "") {
   return fs.readdirSync(path.join(dir, prefix), { withFileTypes: true })
-    .filter((entry) => !entry.name.startsWith(".build-"))
     .flatMap((entry) => (entry.isDirectory() ? files(dir, path.join(prefix, entry.name)) : [path.join(prefix, entry.name)]))
     .sort();
 }