@amritk/nish 0.10.0

package/bin/launcher.js

@@ -0,0 +1,186 @@
+/**
+ * The `nish` command: run the native compiler this machine installed, or say
+ * why there is none and stop.
+ *
+ * This is what `bin.nish` points at, and it exists because npm cannot point a
+ * `bin` entry at a dependency that may or may not be installed. The native
+ * compiler ships as `@amritk/nish-<asset>` packages declared as
+ * `optionalDependencies` with `os` and `cpu` set, so npm installs exactly the
+ * one that matches and silently skips the rest (docs/wp12-release.md,
+ * "Which compiler the package ships"). Something still has to look at what
+ * landed and hand over to it, and that is this file.
+ *
+ * **Nothing is ever compiled on a user's machine.** The binary is built,
+ * `--verify`d and smoke-tested per platform by `release.yml` before the
+ * release that carries it exists; installing is a download and an unpack.
+ *
+ * **A platform with no prebuilt binary is now an error rather than a fallback,
+ * and that is a decision rather than an oversight.** Until 0.6.0 this file
+ * imported `dist/index.js` -- the TypeScript compiler built from `src/` -- so
+ * musl, FreeBSD and 32-bit anything got a working compiler that happened to be
+ * slower. `src/` was deleted in R6 (`docs/wp19-stage0-retirement.md`), so there
+ * is no second compiler in the package to reach for, and the honest answer is
+ * the one below: name the platforms a release carries, say there is nothing to
+ * fall back to, and exit non-zero. The alternative -- shipping `self/` and
+ * bootstrapping on the user's machine -- was priced in wp12 and turned down,
+ * and quietly doing nothing was never on the table: a command that exits 0
+ * having compiled nothing is worse than one that refuses.
+ *
+ * `bin/` rather than the old `dist/` for the same reason: the command may not
+ * be a build artifact of the compiler it installs.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { assetFor, noCompilerMessage, platformPackageName } from "./packaging.js";
+
+/** Package root: bin/launcher.js -> `..`, the directory `package.json` sits in. */
+const PKG_ROOT = path.resolve(import.meta.dirname, "..");
+
+/**
+ * Exit 3, the toolchain code.
+ *
+ * **It is deliberately the same 3 a missing `clang` answers, and that is worth
+ * defending because a wrapper cannot tell the two apart by status alone.** The
+ * table in docs/wp12-release.md's "Exit codes and failure modes" reads
+ * "toolchain: the C toolchain, or the prebuilt compiler itself, could not be
+ * run", which is one band for one shape of failure: nothing is wrong with the
+ * program, there is no source position, and what could not be run is a
+ * *program* rather than the input. A fourth code would put the launcher in the
+ * exit-status contract that `tests/nish/cli.ts` pins for the compiler, for a
+ * situation the compiler cannot be in. What tells them apart is the `code`
+ * field under `--json` and the first line otherwise, which is why the refusal
+ * below is machine-readable. `scripts/postinstall.mjs`'s generated shim answers
+ * 3 for its own version of this, so all three spell one situation the same way.
+ */
+const NO_COMPILER = 3;
+
+/** This package's own name, or `null` when its `package.json` cannot be read. */
+const packageName = () => {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+    return typeof pkg.name === "string" ? pkg.name : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Whether this invocation asked for machine-readable output.
+ *
+ * Read off the raw argv rather than parsed, because the launcher does not parse
+ * the command line and must not start: every other flag is the compiler's
+ * business. `--json` is the one thing it has to notice, since a refusal is a
+ * failure the `--json` contract covers (AGENTS.md, "Machine-readable
+ * surfaces").
+ */
+const wantsJson = () => process.argv.slice(2).includes("--json");
+
+/**
+ * Write and exit, without losing what was written.
+ *
+ * `process.exit` does not wait for a pending write, and stdout/stderr are
+ * asynchronous when they are pipes -- which is what they are whenever anything
+ * captures this command's output, and the case where the message matters most.
+ * `process.exitCode` plus a natural exit flushes, so that is what this does;
+ * there is nothing after it to run.
+ */
+const writeAndExit = (stream, text, status) => {
+  stream.write(text);
+  process.exitCode = status;
+};
+
+/**
+ * Where the native compiler for this machine is, or `null` when this machine
+ * has none installed.
+ *
+ * Resolution goes through the platform package's `package.json` rather than
+ * its binary, because a package may expose its own files however it likes but
+ * `./package.json` is the one export every package in this project declares.
+ * From there the layout is the release tarball's, unchanged: `bin/nish` beside
+ * `runtime/`, `scripts/` and `std/`, which is what lets the binary find
+ * `build.sh`, the C runtime and the standard library one level up from itself
+ * exactly as it does when unpacked by hand.
+ */
+const nativeCompiler = (asset) => {
+  const name = packageName();
+  if (name === null) return null;
+  try {
+    const manifest = createRequire(import.meta.url).resolve(`${platformPackageName(name, asset)}/package.json`);
+    const binary = path.join(path.dirname(manifest), "bin", "nish");
+    return fs.existsSync(binary) ? binary : null;
+  } catch {
+    // Not installed. On a supported platform that is a partial install; on an
+    // unsupported one npm skipped the entry on purpose. `refuse` tells the two
+    // apart, because the advice differs.
+    return null;
+  }
+};
+
+/**
+ * Say why there is no compiler to run, and stop.
+ *
+ * Under `--json` that is one object on stdout and **nothing on stderr**, which
+ * is the shape `self/compile.ts`'s own `reportToolchainFailure` uses for the
+ * same code: stdout carries objects and nothing else, so a tool reading it does
+ * not have to strip a human report out of the stream. Otherwise it is the
+ * report on stderr. Either way the status is the same.
+ */
+const refuse = (unstartable) => {
+  const why = noCompilerMessage({
+    platform: process.platform,
+    arch: process.arch,
+    // The name comes from this package's own `package.json` or not at all. A
+    // literal here would be the scope spelled a second time, against
+    // packaging.js's own rule, and a *wrong* package name is worse advice than
+    // none: it sends the user to install something that does not exist.
+    packageName: packageName(),
+    unstartable,
+  });
+  if (wantsJson()) {
+    writeAndExit(
+      process.stdout,
+      `${JSON.stringify({ severity: "error", code: why.code, message: why.summary })}\n`,
+      NO_COMPILER
+    );
+  } else {
+    writeAndExit(process.stderr, why.report, NO_COMPILER);
+  }
+};
+
+const asset = assetFor(process.platform, process.arch);
+// No binary for this machine, and none coming: musl, FreeBSD, 32-bit anything.
+// `refuse` sets an exit code rather than exiting, so each of these returns
+// before the next line runs: the sequence below is written as a chain for that
+// reason and `process.exitCode` is what carries the status out.
+if (asset === null) {
+  refuse(null);
+} else {
+  const binary = nativeCompiler(asset);
+  if (binary === null) {
+    // A binary exists for this platform and this install does not have it.
+    refuse(null);
+  } else {
+    handOver(binary);
+  }
+}
+
+/** Run the native compiler and give the caller back exactly what it answered. */
+function handOver(binary) {
+  const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+  if (result.error !== undefined && result.error !== null) {
+    // Installed and will not start -- a broken or partial install rather than an
+    // unsupported platform. There is nothing to fall back to, so this is a
+    // refusal with the reason in it rather than a warning above a slower compile.
+    refuse({ binary, reason: result.error.message });
+    } else if (result.signal !== null) {
+    // Re-raise rather than translating to an exit code, so that a crash or an
+    // interrupt reaches the shell as the signal it was. `process.exitCode`
+    // cannot express one, and a wrapper that turned SIGINT into exit 130 would
+    // make `nish` the one command in a pipeline that did.
+    process.kill(process.pid, result.signal);
+  } else {
+    process.exitCode = result.status ?? 0;
+  }
+}

package/bin/nish

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// The `nish` command, before `scripts/postinstall.mjs` has had a look at it.
+//
+// This file is deliberately tiny and deliberately not the whole story. On a
+// machine that installed one of the prebuilt `@amritk/nish-<asset>` packages,
+// postinstall replaces this file with a one-line `/bin/sh` exec of that
+// package's native compiler, so nothing node-shaped is left in the path --
+// measured at 3.2 ms against 94 ms for this shim, which is almost entirely
+// node's own startup (docs/wp12-release.md, "What the launcher costs").
+//
+// It execs the binary in its own package rather than copying it here, because
+// npm links the command through a symlink and the native compiler resolves
+// `build.sh` and `runtime/` from argv[0] without following one. That section
+// has the failure a copy produces.
+//
+// It has to keep working anyway, because the swap is a postinstall and
+// `npm ci --ignore-scripts` is a normal thing for CI to do, as is a registry
+// proxy or a sandbox that disables scripts outright. So this is the path that
+// is always correct and sometimes slower, and the swap is the optimisation on
+// top of it. Everything it delegates to is in `./launcher.js`, beside this
+// file rather than in `dist/`: the command may not be a build artifact of the
+// compiler it installs, and since 0.6.0 there is no `dist/` to build it into.
+import "./launcher.js";

package/bin/packaging.js

@@ -0,0 +1,220 @@
+/**
+ * Which prebuilt binary this machine wants, and what the package holding it is
+ * called.
+ *
+ * `npm install -g @amritk/nish` is a download, not a build: the native
+ * compiler is already built, verified and smoke-tested per platform by
+ * `release.yml`, and it reaches a user as an `optionalDependencies` entry that
+ * npm installs only where `os` and `cpu` match -- the esbuild pattern. This
+ * module is the one place the three spellings of a platform are converted
+ * between, so the launcher, the package generator and the tests cannot drift:
+ *
+ *   node          `process.platform` / `process.arch`      darwin / arm64
+ *   this project  the `asset` in .github/seed-targets.json  aarch64-darwin
+ *   npm           `os` / `cpu` in a package.json            darwin / arm64
+ *
+ * The middle one is the odd spelling and it is not this module's to change:
+ * `asset` is the target triple with the vendor and the ABI dropped, which is
+ * what the release assets, the seed protocol and `bootstrap.sh` already call a
+ * platform. So the rule is a translation between node's two-word name and that
+ * one, and `tests/run.js` checks it against `seed-targets.json` rather than
+ * trusting the two lists to stay equal.
+ *
+ * **This is plain JavaScript under `bin/`, and that is deliberate.** It used
+ * to be `src/packaging.ts`, compiled into `dist/` by `tsc` -- which made the
+ * command a build artifact of the compiler it is supposed to install. `bin/`
+ * is what the tarball carries and what `bin.nish` points into, so the launcher
+ * and its platform table now live where they ship, need no build step, and
+ * survived the deletion of `src/` (`docs/wp19-stage0-retirement.md` R6). The
+ * types they lose are not much of a loss for two string maps; what they gain is
+ * that `npm pack` ships the same bytes this repository runs.
+ */
+
+/**
+ * The architecture half of an `asset`, keyed by node's `process.arch`.
+ *
+ * Only the architectures a release actually attaches are here. An arch that is
+ * missing is not an error -- it means no prebuilt binary exists for this
+ * machine, which the launcher answers by saying so and stopping.
+ */
+const ARCH_BY_CPU = {
+  x64: "x86_64",
+  arm64: "aarch64",
+};
+
+/**
+ * The operating-system half. It is an identity map today, because node's
+ * `linux` and `darwin` are already what the triple calls them, and it exists
+ * so that the one platform where that stops being true -- a `win32` whose
+ * triple says `windows` -- is a line here rather than a special case at the
+ * call site.
+ */
+const OS_BY_PLATFORM = {
+  linux: "linux",
+  darwin: "darwin",
+};
+
+/**
+ * Every asset a release actually attaches, sorted, in `seed-targets.json`'s
+ * spelling. This is the list the refusal *prints*.
+ *
+ * **A literal list rather than the cross product of the two maps above**, which
+ * is what it was first written as and which is wrong in a way that only shows up
+ * later: the maps multiply out to this list only because the support matrix
+ * happens to be full. Add `riscv64: "riscv64"` for linux alone -- one platform,
+ * not four -- and a cross product advertises `riscv64-darwin` to a user, and
+ * fails the check that compares this against `.github/seed-targets.json` for a
+ * launcher that was behaving correctly. The authority is that file; `tests/run.js`
+ * compares the two, so a literal is exactly as gated as a derivation and says
+ * only what is true.
+ */
+export const SUPPORTED_ASSETS = ["aarch64-darwin", "aarch64-linux", "x86_64-darwin", "x86_64-linux"];
+
+/**
+ * The `asset` for a node platform/arch pair, or `null` when this project
+ * attaches no binary for it.
+ *
+ * `null` is a supported answer rather than a crash: Alpine on musl, a FreeBSD,
+ * a linux/riscv64 all land here. What it is no longer is a *quiet* answer --
+ * there is no compiler in the package to fall back to since 0.6.0, so the
+ * launcher turns this `null` into a diagnostic naming the four platforms and
+ * exits non-zero (`docs/wp12-release.md`, "Which compiler the package ships").
+ */
+export const assetFor = (platform, arch) => {
+  const os = OS_BY_PLATFORM[platform];
+  const cpu = ARCH_BY_CPU[arch];
+  if (os === undefined || cpu === undefined) return null;
+  return `${cpu}-${os}`;
+};
+
+/** The inverse, for the generator and the tests: an `asset` back to npm's pair. */
+export const targetForAsset = (asset) => {
+  const dash = asset.indexOf("-");
+  if (dash < 0) return null;
+  const arch = asset.slice(0, dash);
+  const os = asset.slice(dash + 1);
+  const cpu = Object.keys(ARCH_BY_CPU).find((key) => ARCH_BY_CPU[key] === arch);
+  const platform = Object.keys(OS_BY_PLATFORM).find((key) => OS_BY_PLATFORM[key] === os);
+  if (cpu === undefined || platform === undefined) return null;
+  return { asset, os: platform, cpu };
+};
+
+/**
+ * The package holding the binary for one asset, derived from the main
+ * package's own name: `@amritk/nish` + `x86_64-linux` -> `@amritk/nish-x86_64-linux`.
+ *
+ * Derived rather than written out so that the scope is spelled once. The
+ * registry name was settled late (`nish` belongs to somebody else, so this one
+ * is scoped -- docs/wp12-release.md "The npm name"), and a list of five literal
+ * names would be five places to edit if it ever moves again.
+ */
+export const platformPackageName = (packageName, asset) => `${packageName}-${asset}`;
+
+/**
+ * The diagnostic code every refusal here carries: `NL0002`, the toolchain code.
+ *
+ * Not a new code, and that is the point. `self/codes.ts` defines `NL0002` as
+ * "the toolchain `--link` needs could not be used (exit 3)", and a prebuilt
+ * compiler that is absent or will not start is the same class of failure seen
+ * one step earlier: no source position, nothing wrong with the program, and the
+ * thing that could not be run is a binary rather than the input. Reusing it
+ * keeps the launcher out of the diagnostic registry entirely -- a code minted
+ * here would be one `self/codes.ts` mirrors for a message the compiler can
+ * never print, and `tests/diagnostic_coverage.js` would then want a case
+ * provoking a rule that does not exist.
+ */
+export const NO_COMPILER_CODE = "NL0002";
+
+/**
+ * Why there is no compiler to run, and what to do about it: the one-line
+ * `message` a `--json` object carries, and the report a person reads.
+ *
+ * **Both, from one function, because the contract is that they say the same
+ * thing.** `AGENTS.md` promises that a failure with no source position is still
+ * one JSON line under `--json` and that "you never have to read stderr to find
+ * out why a run failed" -- so the refusal cannot be prose only, and the first
+ * version of this file made it prose only, which broke that contract on a path
+ * a user reaches with `--no-optional` on a fully supported platform.
+ *
+ * A pure function rather than `process.stderr.write` calls in the launcher, for
+ * one reason: the branch a user on musl or FreeBSD hits is the branch no machine
+ * in CI can reach, because every runner this project uses is one of the four
+ * supported platforms. Written like this, `tests/run.js` can ask for that exact
+ * message on any host and assert what it says, while the branch the harness
+ * *can* reach is asserted end to end on the installed command. A diagnostic
+ * nothing can test is how the advice in it goes stale.
+ *
+ * Three situations, and they get different advice because the remedy differs:
+ *
+ *   - `unsupported`: this project publishes no binary for the machine. Nothing
+ *     about the install is wrong and reinstalling will not help, so the advice
+ *     is the bootstrap, and INSTALL.md carries the part that needs more than
+ *     four lines -- including that on musl no released binary may run at all.
+ *   - `missing`: a binary exists for this platform and the install does not
+ *     have it. Reinstalling is the remedy.
+ *   - `unstartable`: it is installed and will not run. A broken or partly
+ *     written install, named as one rather than reported as an unsupported
+ *     platform.
+ *
+ * Every branch names the four platforms, because a user who has just been
+ * refused wants to know whether the list is the whole list. It is.
+ */
+export const noCompilerMessage = ({ platform, arch, packageName, unstartable = null }) => {
+  const asset = assetFor(platform, arch);
+  const published = SUPPORTED_ASSETS.join("  ");
+  const preamble =
+    "  This package installs a prebuilt native compiler. One is published for:\n" +
+    `    ${published}\n\n` +
+    "  There is no compiler inside the package to fall back to, and nothing is\n" +
+    "  compiled on your machine on any path.\n";
+  if (asset === null) {
+    return {
+      code: NO_COMPILER_CODE,
+      summary:
+        `no prebuilt compiler for ${platform}/${arch}; one is published for ${published}, ` +
+        "and there is none inside the package to fall back to. Build one from a released " +
+        "`nish` that runs here: NISH_BOOTSTRAP=<nish> scripts/bootstrap.sh in a checkout " +
+        "(docs/INSTALL.md)",
+      report:
+        `nish: no prebuilt compiler for ${platform}/${arch}\n\n${preamble}\n` +
+        "  To get a compiler for this machine, build one from a released `nish` in a\n" +
+        "  checkout of the repository:\n" +
+        "    NISH_BOOTSTRAP=<a released nish that runs here> scripts/bootstrap.sh\n" +
+        "  docs/INSTALL.md has the detail, including what to do when no released\n" +
+        "  binary runs on this platform at all.\n",
+    };
+  }
+  if (unstartable !== null) {
+    return {
+      code: NO_COMPILER_CODE,
+      summary:
+        `${unstartable.binary} could not be started (${unstartable.reason}); that is a broken ` +
+        "or partly written install rather than an unsupported platform. Reinstall the " +
+        "package, or run `npm rebuild` if the tree moved",
+      report:
+        `nish: ${unstartable.binary} could not be started (${unstartable.reason})\n\n${preamble}\n` +
+        "  That is a broken or partly written install rather than an unsupported\n" +
+        "  platform. Reinstall the package, or run `npm rebuild` if the tree moved.\n",
+    };
+  }
+  // A `packageName` of `null` means this package's own `package.json` could not
+  // be read, which is a broken install and not the moment to guess: naming the
+  // wrong package sends the user to install something that does not exist, so
+  // the sentence loses the name instead of inventing one.
+  const named = packageName === null ? null : platformPackageName(packageName, asset);
+  const pkg = named === null ? `the platform package for ${asset}` : named;
+  return {
+    code: NO_COMPILER_CODE,
+    summary:
+      `the prebuilt compiler for ${asset} is not installed; its package is ${pkg}, which npm ` +
+      "installs automatically for this platform. Reinstall the package, or install the pair " +
+      "by hand (docs/INSTALL.md)",
+    report:
+      `nish: the prebuilt compiler for ${asset} is not installed\n\n${preamble}\n` +
+      `  Its package is ${pkg}, which npm installs\n` +
+      "  automatically for this platform. An install that skipped it is usually\n" +
+      "  `--no-optional`, a lockfile without the platform packages, or a registry that\n" +
+      "  does not carry them yet. Reinstall the package, or install the pair by hand as\n" +
+      "  docs/INSTALL.md shows.\n",
+  };
+};