@amritk/nish 0.10.0

package/scripts/ci-profile.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * Where a CI job's wall clock actually goes, per check.
+ *
+ *   node scripts/ci-profile.mjs                          profile `node tests/run.js`
+ *   node scripts/ci-profile.mjs --top 60                 more rows in each table
+ *   node scripts/ci-profile.mjs --json                    the same numbers, machine-readable
+ *   node scripts/ci-profile.mjs -- node tests/run.js --seed <nish>
+ *   node scripts/ci-profile.mjs -- npm run test:nish
+ *
+ * Why this exists. `tests/run.js` is one process printing about nineteen
+ * hundred `PASS` lines, and a slow run says only that the total grew. Every
+ * attempt to find the slow part by hand ran into the trap that a filtered run
+ * is not a measurement (`.claude/testing.md`: a filtered count means nothing
+ * until `rm -rf build/test`, and fifteen `fs.existsSync` guards drop checks
+ * silently rather than skipping them). So this profiles the *unfiltered* run
+ * instead, from the outside, and attributes time to the checks that were
+ * actually printed. It needs no change to the suite and cannot alter what the
+ * suite proves.
+ *
+ * **How to read the numbers, including the one way they mislead.** A check's
+ * cost here is the gap between the previous printed line and its own, so the
+ * work is attributed to the line printed *after* it finished. That is the right
+ * answer for a check that does its work and then reports, which is every check
+ * in this suite. It is the wrong answer in one case worth naming: because
+ * `tests/run.js` drives 234 `spawnSync` calls, the event loop is blocked for
+ * the whole of each one and queued writes flush in bursts when it unblocks. So
+ * a *gap* is real, and the line it lands on is real, but the ordering of the
+ * lines inside one burst is not something to read a per-line cost out of. Look
+ * at the expensive rows, not at the cheap ones.
+ *
+ * The totals are wall clock on the machine this runs on. A `ubuntu-latest`
+ * runner measured about 1.34x this box on the same suite, so the shape
+ * transfers and the absolute seconds do not.
+ */
+import { spawn } from "node:child_process";
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes("--json");
+const topAt = argv.indexOf("--top");
+const TOP = topAt >= 0 && Number.isFinite(Number(argv[topAt + 1])) ? Number(argv[topAt + 1]) : 40;
+
+/**
+ * Everything after `--` is the command to profile. The default is the suite as
+ * CI runs it, minus the build: `npm test` would rebuild `dist/` first, and a
+ * `tsc` run is not what this is measuring.
+ */
+const dashdash = argv.indexOf("--");
+const command = dashdash >= 0 && argv.length > dashdash + 1 ? argv.slice(dashdash + 1) : ["node", "tests/run.js"];
+
+/**
+ * One row per line the child printed, with `dt` the gap since the line before
+ * it. `text` keeps the line as it was printed so that a reader can find the
+ * check in the log, and `t` is kept as well as `dt` because "which minute of
+ * the run was this" is how a reader locates a slow block.
+ */
+const rows = [];
+const t0 = process.hrtime.bigint();
+let last = 0;
+let buffered = "";
+
+const takeLine = (line) => {
+  const t = Number(process.hrtime.bigint() - t0) / 1e6;
+  rows.push({ t, dt: t - last, text: line });
+  last = t;
+};
+
+const onData = (data) => {
+  buffered += data;
+  let i;
+  while ((i = buffered.indexOf("\n")) >= 0) {
+    takeLine(buffered.slice(0, i));
+    buffered = buffered.slice(i + 1);
+  }
+};
+
+/**
+ * A heartbeat on stderr, because the tables below cannot be printed until the
+ * child has exited and `npm test` takes eleven minutes. It goes to stderr so
+ * that `--json` on stdout stays machine-readable, and it names the last check
+ * seen rather than only a count: that is what says whether a long silence is
+ * the oracles working or the run wedged.
+ */
+const heartbeat = setInterval(() => {
+  const latest = rows.length > 0 ? rows[rows.length - 1].text.slice(0, 72) : "nothing printed yet";
+  const elapsed = (Number(process.hrtime.bigint() - t0) / 1e9).toFixed(0);
+  process.stderr.write(`[ci-profile] ${elapsed}s, ${rows.length} lines: ${latest}\n`);
+}, 30_000);
+heartbeat.unref();
+
+const child = spawn(command[0], command.slice(1), { stdio: ["ignore", "pipe", "pipe"] });
+child.stdout.setEncoding("utf8");
+child.stderr.setEncoding("utf8");
+child.stdout.on("data", onData);
+child.stderr.on("data", onData);
+
+const status = await new Promise((resolve) => {
+  child.on("close", (code) => resolve(code ?? 1));
+  child.on("error", (err) => {
+    console.error(`could not run ${command.join(" ")}: ${err.message}`);
+    resolve(1);
+  });
+});
+clearInterval(heartbeat);
+if (buffered.length > 0) takeLine(buffered);
+
+/**
+ * A check's name up to its first colon, which is how this suite names a family:
+ * `link/argv_import: llvm-as accepts args.ll` and its six siblings are one
+ * fixture compiled once, and the family is what a reader can act on. A line
+ * with no colon is grouped under its first forty characters, which is enough to
+ * keep the oracles — each of which prints one long line — apart.
+ */
+const familyOf = (text) => {
+  const body = text.replace(/^(PASS|FAIL|SKIP)\s+/, "");
+  const colon = body.indexOf(":");
+  return colon > 0 ? body.slice(0, colon) : body.slice(0, 40);
+};
+
+const families = new Map();
+for (const row of rows) {
+  const key = familyOf(row.text);
+  const seen = families.get(key) ?? { ms: 0, lines: 0 };
+  seen.ms += row.dt;
+  seen.lines += 1;
+  families.set(key, seen);
+}
+
+const total = rows.length > 0 ? rows[rows.length - 1].t : 0;
+const byCost = [...rows].sort((a, b) => b.dt - a.dt).slice(0, TOP);
+const byFamily = [...families].sort((a, b) => b[1].ms - a[1].ms).slice(0, TOP);
+
+if (asJson) {
+  console.log(
+    JSON.stringify(
+      {
+        command,
+        status,
+        totalMs: Math.round(total),
+        lines: rows.length,
+        checks: byCost.map((r) => ({ ms: Math.round(r.dt), atMs: Math.round(r.t), text: r.text })),
+        families: byFamily.map(([name, f]) => ({ name, ms: Math.round(f.ms), lines: f.lines })),
+      },
+      null,
+      2
+    )
+  );
+  process.exit(status);
+}
+
+const secs = (ms) => `${(ms / 1000).toFixed(1)}s`.padStart(8);
+
+console.log(`\n${command.join(" ")}`);
+console.log(`exit ${status} — ${secs(total).trim()} of wall clock over ${rows.length} printed lines\n`);
+
+/**
+ * The run's own verdict, echoed verbatim.
+ *
+ * A profile that swallowed this would be worse than useless here, because exit
+ * 0 is not the whole answer: `tests/run.js` reports a *skip count* beside the
+ * passes, and a green run with more skips than the last one proved less while
+ * looking the same (`.claude/orientation.md` calls reading the count rather than
+ * the exit status the thing to do). So the summary is printed before the
+ * timings, where it cannot be missed.
+ */
+const verdict = rows.filter((r) => r.text.trim().length > 0).slice(-3);
+if (verdict.length > 0) {
+  console.log("=== what the run itself reported ===");
+  for (const row of verdict) console.log(`  ${row.text}`);
+  console.log("");
+}
+
+console.log(`=== the ${byCost.length} most expensive checks (cost = the gap before the line was printed) ===`);
+for (const row of byCost) console.log(`${secs(row.dt)}  at ${secs(row.t)}  ${row.text.slice(0, 104)}`);
+
+console.log(`\n=== the ${byFamily.length} most expensive families (cumulative) ===`);
+for (const [name, f] of byFamily) console.log(`${secs(f.ms)}  ${String(f.lines).padStart(5)} line(s)  ${name.slice(0, 84)}`);
+
+/**
+ * The share the expensive tail accounts for, because "the top ten are 70% of
+ * the run" is the sentence that decides whether to optimise a check or the
+ * shape of the job around it.
+ */
+const topTen = [...rows].sort((a, b) => b.dt - a.dt).slice(0, 10).reduce((sum, r) => sum + r.dt, 0);
+console.log(`\nthe ten most expensive checks are ${((topTen / total) * 100).toFixed(0)}% of the run.`);
+
+process.exit(status);

package/scripts/codes-registry.js

@@ -0,0 +1,73 @@
+/**
+ * The diagnostic-code registry, read back out of a `codes.ts`.
+ *
+ * `self/codes.ts` holds the table -- a fragment line, then the `NL####` line
+ * that names its rule. Three places in this repository read it back:
+ * `scripts/gen-diagnostic-codes.mjs`, which checks the registry's shape, its
+ * order and that no number is used twice; `tests/diagnostic_coverage.js`,
+ * which asks which codes the suite reaches; and the `codes:` checks in
+ * `tests/run.js`. This module is that parse, once, so the copies cannot drift
+ * apart again ([issue #96](https://github.com/amritk/nish/issues/96)).
+ *
+ * It lives here rather than under `tests/` for two reasons. The format was
+ * written by `rows()` in the generator next door until the registry was
+ * frozen and kept by hand (R6), and #96 was the writer and the readers
+ * drifting apart -- WP22 stage C changed what the emitter wrote and no reader
+ * followed -- so the reader belongs beside the checker. And `scripts/` ships in
+ * the npm tarball while `tests/` does not, so a shared module under `tests/`
+ * would leave the shipped checker importing a path the package cannot
+ * resolve, which `tests/run.js` refuses
+ * (`npm pack ships no script whose imports it cannot resolve`).
+ *
+ * Two properties are the whole point of having it, and both are here because
+ * they have failed:
+ *
+ *   - **The indentation is not part of the contract.** `self/codes.ts` lost a
+ *     level when WP22 stage C rewrote its tables as arrows with concise
+ *     bodies, and every reader keyed on four literal spaces then read it as
+ *     *empty* rather than as changed. `^\s+` is what a pair is recognised by.
+ *   - **Nothing is an empty registry.** A reader that answers `[]` for a file
+ *     whose shape has moved makes "every code is covered" and "there are no
+ *     codes" the same answer, which is what let the first instance of this
+ *     survive unnoticed. This one raises instead.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const root = path.resolve(import.meta.dirname, "..");
+
+/**
+ * One entry of the emitted table: the quoted fragment on its own line, then
+ * the code on the next. Anchored to the line rather than to a column, for the
+ * reason in the header.
+ */
+const PAIR = /^\s+("(?:[^"\\]|\\.)*"),\n\s+"(NL\d{4})",$/gm;
+
+/**
+ * Every `{ fragment, code }` of one registry file, in the order the file holds
+ * them -- which is the order the compilers match in, longest fragment first,
+ * so a caller comparing two registries is comparing their behaviour and not
+ * just their contents.
+ *
+ * Pairs rather than a `Map` because the three callers key it three different
+ * ways, and because a `Map` would quietly swallow a duplicated fragment that a
+ * caller may want to see.
+ *
+ * Throws when it parses nothing: an unreadable registry is a broken one, and
+ * the one thing it may not do is pass for an empty one. `label` is what that
+ * message names the text by.
+ */
+export const parseCodesRegistry = (text, label) => {
+  const pairs = [];
+  for (const m of text.matchAll(PAIR)) {
+    pairs.push({ fragment: JSON.parse(m[1]), code: m[2] });
+  }
+  if (pairs.length === 0) {
+    throw new Error(`${label}: no diagnostic codes parsed -- the registry's shape has moved`);
+  }
+  return pairs;
+};
+
+/** The same, for a registry on disk. The three callers all read a file. */
+export const readCodesRegistry = (file) =>
+  parseCodesRegistry(fs.readFileSync(file, "utf8"), path.relative(root, file));

package/scripts/gen-diagnostic-codes.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * Check the stable diagnostic-code registry: the `code` field of `--json`.
+ *
+ *   node scripts/gen-diagnostic-codes.mjs --check    exit 1 if the registry is malformed
+ *   node scripts/gen-diagnostic-codes.mjs            the same, then the next free code per band
+ *   node scripts/gen-diagnostic-codes.mjs --check F  check the registry in file F instead
+ *
+ * The third form is for `tests/run.js`, which hands it a copy of the registry
+ * with one line broken to show that each rule below is really enforced.
+ *
+ * **The registry is kept by hand now.** It used to be generated: this script
+ * scanned `src/` for every diagnostic message, cut each at its interpolations,
+ * and wrote the same table into `src/codes.ts` and `self/codes.ts`. That scan
+ * read stage0's source, and stage0 is deleted (wp19 §5 R6), so the generator
+ * was frozen with the table it last wrote and `self/codes.ts` became the
+ * registry. A new diagnostic gets its code by hand: append a fragment and the
+ * next free number in its band (the second mode above prints those), at the
+ * position the ordering rule below puts it. `tests/diagnostic_coverage.js`
+ * is what notices a diagnostic that has no code, by counting `NL0000`.
+ *
+ * What `--check` still holds, because each is what makes a code worth keying
+ * on:
+ *
+ *   - **Every number is well-formed and in its band.** `NL1xxx` Phase 0,
+ *     `NL2xxx` the checker, `NL3xxx` the driver, `NL4xxx` the interop
+ *     sidecars, `NL9xxx` a WP15 section 8 performance warning. Band 0 is not
+ *     in the tables: `NL0000` (no rule matched), `NL0001` (a syntax error),
+ *     `NL0002` (the toolchain) and `NL0003` (an internal error) are constants.
+ *     A performance fragment is in `performanceRules` and nowhere else.
+ *   - **Nothing is used twice.** A number handed out once is never handed to a
+ *     different rule, and a retired rule keeps its entry -- it matches nothing,
+ *     so carrying it costs a string -- precisely so that its number stays
+ *     reserved. Two entries for one fragment would make the second dead.
+ *   - **Longest fragment first**, ties in `localeCompare` order, the order the
+ *     generator wrote: the compilers take the first fragment the message
+ *     contains, so a specific rule has to come before a general one it
+ *     contains ("Cannot assign to `length` of " before "Cannot assign ").
+ *   - **No fragment too short to identify a rule** (ten characters, trimmed),
+ *     which would match half the suite.
+ *   - **Every string in a table is half of a pair.** `codeFor` in
+ *     `self/codes.ts` reads each table as one flat array and steps through it
+ *     by two, so a fragment added without its code line -- or a code without
+ *     its fragment -- shifts every pairing after it, and from there on
+ *     messages get their neighbour's code. The pair reader cannot see that:
+ *     it matches a fragment line followed by a code line, and a stray line is
+ *     simply not a match. So each table's strings are counted on their own
+ *     and have to come to twice its pairs ([#107](https://github.com/amritk/nish/issues/107)).
+ *   - **The `NL9xxx` codes run from `NL9001` with no gap**, one per WP15
+ *     section 8 rule, so a missing number is a rule that lost its code.
+ *   - **`RULE_COUNT` is the number of entries.**
+ *
+ * A fragment is the longest literal run of its message's template -- the rule
+ * in words, with every interpolated name, type and count removed -- matched as
+ * a substring. Cutting at the interpolations is also what keeps the project's
+ * name out of the table: "... is forbidden in ${LANGUAGE}" contributes the run
+ * before the name, never the name, so `branding.ts` stays the only place it is
+ * spelled (rule 5 in `.claude/orientation.md`). Keep to that when adding one.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCodesRegistry } from "./codes-registry.js";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REGISTRY = process.argv.slice(2).find((arg) => !arg.startsWith("--")) ?? path.join(ROOT, "self", "codes.ts");
+
+/** The bands a table entry may use. Band 0 is constants, never a table row. */
+const BANDS = new Set(["1", "2", "3", "4", "9"]);
+
+/** Shorter than this, a fragment would match half the suite. */
+const MIN_FRAGMENT = 10;
+
+/**
+ * The text of one table in `self/codes.ts`: from its `name = (): string[] => [`
+ * to the `];` that closes it. Parsed per table, because the table a fragment
+ * sits in is part of what it means -- a performance rule is matched only
+ * against a performance message.
+ */
+const tableText = (text, name) => {
+  const open = text.indexOf(`export const ${name} = (): string[] => [`);
+  if (open < 0) return null;
+  const close = text.indexOf("\n];", open);
+  return close < 0 ? null : text.slice(open, close + 1);
+};
+
+/**
+ * How many strings one table holds: every literal after the line that opens
+ * it. That is what `codeFor` steps through two at a time, so it is counted on
+ * its own rather than read off the pairs -- a stray literal is exactly what
+ * the pair reader skips.
+ */
+const STRING = /"(?:[^"\\]|\\.)*"/g;
+const literalCount = (body) => body.slice(body.indexOf("\n")).match(STRING)?.length ?? 0;
+
+/** The order the compilers rely on: longest fragment first, then `localeCompare`. */
+const inOrder = (a, b) => b.fragment.length - a.fragment.length || a.fragment.localeCompare(b.fragment);
+
+/** Every rule of `self/codes.ts` it breaks, as a line each; empty when it holds. */
+const problems = (text) => {
+  const found = [];
+  const tables = [];
+  for (const [name, perf] of [
+    ["diagnosticRules", false],
+    ["performanceRules", true],
+  ]) {
+    const body = tableText(text, name);
+    if (body === null) {
+      found.push(`self/codes.ts has no \`${name}\` table`);
+      continue;
+    }
+    try {
+      const pairs = parseCodesRegistry(body, `self/codes.ts ${name}`);
+      const literals = literalCount(body);
+      if (literals !== 2 * pairs.length) {
+        found.push(
+          `\`${name}\` holds ${literals} strings and ${pairs.length} fragment/code pairs: a string ` +
+            "without its other half shifts every later pairing `codeFor` makes"
+        );
+      }
+      tables.push({ name, perf, pairs });
+    } catch (err) {
+      found.push(err.message);
+    }
+  }
+  const all = tables.flatMap((t) => t.pairs);
+
+  // The tables are the whole registry: a pair the reader finds outside them is
+  // one the compilers never match, and one of theirs the reader misses is one
+  // `tests/diagnostic_coverage.js` never asks about.
+  let whole = [];
+  try {
+    whole = parseCodesRegistry(text, "self/codes.ts");
+  } catch (err) {
+    found.push(err.message);
+  }
+  if (whole.length !== all.length) {
+    found.push(`self/codes.ts holds ${whole.length} pairs, ${all.length} of them inside the two tables`);
+  }
+
+  for (const { name, perf, pairs } of tables) {
+    for (let i = 0; i < pairs.length; i++) {
+      const { fragment, code } = pairs[i];
+      const band = code[2];
+      if (!BANDS.has(band)) found.push(`${code} is not in a table band (1, 2, 3, 4 or 9): ${JSON.stringify(fragment)}`);
+      if (perf !== (band === "9")) {
+        found.push(`${code} is in \`${name}\`, which holds ${perf ? "only" : "no"} NL9xxx codes`);
+      }
+      if (fragment.trim().length < MIN_FRAGMENT) {
+        found.push(`${code}'s fragment ${JSON.stringify(fragment)} is under ${MIN_FRAGMENT} characters`);
+      }
+      if (i > 0 && inOrder(pairs[i - 1], pairs[i]) > 0) {
+        found.push(`${code} is out of order in \`${name}\`: it has to come before ${pairs[i - 1].code}`);
+      }
+    }
+  }
+
+  const perfCodes = tables
+    .filter((t) => t.perf)
+    .flatMap((t) => t.pairs.map((p) => Number(p.code.slice(3))))
+    .sort((a, b) => a - b);
+  const gap = perfCodes.findIndex((n, i) => n !== i + 1);
+  if (gap >= 0) {
+    found.push(`\`performanceRules\` has no NL${9000 + gap + 1} in its place: its codes run from NL9001 with no gap`);
+  }
+
+  const seen = (key) => {
+    const counts = new Map();
+    for (const pair of all) counts.set(pair[key], (counts.get(pair[key]) ?? 0) + 1);
+    return [...counts].filter(([, n]) => n > 1).map(([value]) => value);
+  };
+  for (const code of seen("code")) found.push(`${code} names two rules`);
+  for (const fragment of seen("fragment")) found.push(`${JSON.stringify(fragment)} has two entries`);
+
+  const count = /export const RULE_COUNT: i32 = (\d+);/.exec(text);
+  if (count === null) found.push("self/codes.ts has no `RULE_COUNT`");
+  else if (Number(count[1]) !== all.length) {
+    found.push(`RULE_COUNT is ${count[1]} and the tables hold ${all.length} rules`);
+  }
+
+  return { found, all };
+};
+
+/** The next number nobody has held, per band -- what a hand-added rule takes. */
+const nextFree = (pairs) => {
+  const highest = new Map();
+  for (const { code } of pairs) {
+    const band = code[2];
+    highest.set(band, Math.max(highest.get(band) ?? 0, Number(code.slice(3))));
+  }
+  return [...BANDS].map((band) => `NL${band}${String((highest.get(band) ?? 0) + 1).padStart(3, "0")}`);
+};
+
+const { found, all } = problems(fs.readFileSync(REGISTRY, "utf8"));
+for (const problem of found) console.error(`error: ${problem}`);
+if (found.length === 0 && !process.argv.includes("--check")) {
+  console.log(`self/codes.ts: ${all.length} rules, well-formed; next free: ${nextFree(all).join(" ")}`);
+}
+process.exit(found.length > 0 ? 1 : 0);

package/scripts/gen-pow5-tables.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Regenerate the two power-of-five tables `runtime/runtime.c` uses for Ryu.
+
+    python3 scripts/gen-pow5-tables.py
+
+Prints the C to stdout; paste it over the `NISH_POW5_INV_SPLIT` and
+`NISH_POW5_SPLIT` definitions. The point of having this in the tree is that
+the ~10 KB of constants in the runtime are *derived*, with exact integer
+arithmetic, rather than transcribed from somewhere -- so a reader can check
+them rather than trust them. See docs/wp15-performance.md section 7a.
+"""
+INV_BITCOUNT = 125
+BITCOUNT = 125
+M = (1 << 64) - 1
+
+def pow5bits(i):
+    return (5 ** i).bit_length()
+
+inv = []
+for i in range(292):
+    p = 5 ** i
+    j = p.bit_length() - 1 + INV_BITCOUNT
+    v = (1 << j) // p + 1
+    assert v >> 128 == 0, i
+    inv.append((v & M, v >> 64))
+
+spl = []
+for i in range(326):
+    p = 5 ** i
+    j = p.bit_length() - BITCOUNT
+    v = p << -j if j < 0 else p >> j
+    assert v >> 128 == 0, i
+    spl.append((v & M, v >> 64))
+
+def emit(name, rows):
+    out = [f"static const uint64_t {name}[{len(rows)}][2] = {{"]
+    for lo, hi in rows:
+        out.append(f"  {{ {lo}u, {hi}u }},")
+    out.append("};")
+    return "\n".join(out)
+
+print("/* Generated by scripts/gen-pow5-tables.py; do not hand-edit. */")
+print(emit("NISH_POW5_INV_SPLIT", inv))
+print()
+print(emit("NISH_POW5_SPLIT", spl))

package/scripts/nish-compiler.sh

@@ -0,0 +1,17 @@
+# Sourced, not run: how a shell script turns a compiler path into a command.
+#
+#   . scripts/nish-compiler.sh
+#   nish_compiler "${NISH:-build/nish}"
+#   "${compiler[@]}" program.ts -o out.ll
+#
+# A Node entry point (.js, .mjs, .cjs) is run under node and anything else --
+# a native `nish` -- directly. That is the rule `NISH_BOOTSTRAP` follows in
+# scripts/bootstrap.sh and tests/self/seed.js follows as `NODE_ENTRY`, so one
+# path names a compiler the same way to every tool. Bash, because the answer is
+# an array: a compiler path with a space in it stays one word.
+nish_compiler() {
+  case "$1" in
+    *.js | *.mjs | *.cjs) compiler=(node "$1") ;;
+    *) compiler=("$1") ;;
+  esac
+}

package/scripts/platform-package.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Turn a staged release directory into a publishable platform package.
+ *
+ *   node scripts/platform-package.mjs <stage-dir> <asset> [--version <v>]
+ *
+ * `release.yml`'s `binaries` job already stages exactly what one of these
+ * needs, because the release tarball and the npm package want the same thing:
+ * `bin/nish` beside the `runtime/` and `scripts/` it resolves one level up
+ * from itself. So this script adds a `package.json` to that directory and
+ * changes nothing else — `npm publish <stage-dir>` then uploads the same bytes
+ * the tarball carries, built and smoke-tested by the steps above it.
+ *
+ * The package declares `os` and `cpu`, which is the whole mechanism: it is an
+ * `optionalDependencies` entry of the main package, so npm installs the one
+ * that matches this machine and skips the others without failing. Nothing here
+ * is compiled on the way in.
+ *
+ * It deliberately declares no `bin`. The `nish` command belongs to the main
+ * package's launcher, which is the only thing that knows which platform's
+ * binary to hand over to -- and, since 0.6.0, the only thing that knows how to
+ * say so when none was installed; two packages claiming one command name would
+ * leave which binary wins up to npm's link order.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { targetForAsset } from "../bin/packaging.js";
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const i = args.indexOf(name);
+  return i < 0 ? null : args[i + 1];
+};
+const positional = args.filter((a, i) => !a.startsWith("--") && !(args[i - 1] ?? "").startsWith("--"));
+const [stageDir, asset] = positional;
+
+if (stageDir === undefined || asset === undefined) {
+  console.error("usage: platform-package.mjs <stage-dir> <asset> [--version <v>]");
+  process.exit(2);
+}
+
+const root = path.resolve(import.meta.dirname, "..");
+const main = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+const version = flag("--version") ?? main.version;
+
+const target = targetForAsset(asset);
+if (target === null) {
+  console.error(`platform-package.mjs: ${asset} is not a platform this project builds for`);
+  process.exit(1);
+}
+
+const binary = path.join(stageDir, "bin", "nish");
+if (!fs.existsSync(binary)) {
+  console.error(`platform-package.mjs: ${binary} does not exist; stage the binary before packaging it`);
+  process.exit(1);
+}
+
+const pretty = { linux: "Linux", darwin: "macOS" }[target.os] ?? target.os;
+const chip = { x64: "x86_64", arm64: "ARM64" }[target.cpu] ?? target.cpu;
+
+const manifest = {
+  name: `${main.name}-${asset}`,
+  version,
+  description: `The ${main.name} native compiler for ${pretty} on ${chip}`,
+  license: main.license,
+  os: [target.os],
+  cpu: [target.cpu],
+  // `./package.json` is how the launcher finds this package: it resolves the
+  // manifest and joins `bin/nish` to its directory. Everything else is read by
+  // the binary itself, relative to its own path, never through a specifier.
+  exports: { "./package.json": "./package.json" },
+  // `std` is in this list for the reason `runtime` is, and it was missing until
+  // 2026-09-20: the compiler resolves a `nish/<module>` specifier against its
+  // own package root, so a platform package without it answers every one of
+  // them with ``Module `nish/text` is not part of the standard library``, while
+  // naming `text` among the modules it has. The message is the static list of
+  // module names; what is absent is the file. Nothing caught it because every
+  // program the release smoke-tests imports by relative path or not at all,
+  // and because the pack-and-install round trip in `tests/run.js` packs the
+  // MAIN package, which has carried `std` in its own `files` all along --
+  // so the fallback to `dist/` worked and the path a user actually gets did
+  // not. See docs/wp12-release.md and wp19 §5a.
+  files: ["bin", "runtime", "scripts", "std", "LICENSE", "INSTALL.md"],
+  repository: main.repository,
+  bugs: main.bugs,
+  homepage: main.homepage,
+};
+
+const out = path.join(stageDir, "package.json");
+fs.writeFileSync(out, `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(`${manifest.name}@${version} (os ${target.os}, cpu ${target.cpu}) -> ${out}`);