npm: render a README into each platform package

The platform sub-packages had no README, so npmjs.com showed an empty
page. Add a template with {{SCOPE}}/{{PKG}}/{{OS}}/{{CPU}} placeholders
and render it in build-platform-packages.mjs so every generated package
ships a README pointing users at the main @zerops/zcli package.

Author: l-hellmann

tools/npm/scripts/build-platform-packages.mjs

@@ -11,13 +11,25 @@
 // Each generated package carries os/cpu fields so the package manager (npm, and Bun,
 // which honors them) installs only the one matching the host.
 
-import { mkdirSync, copyFileSync, writeFileSync, chmodSync, existsSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, copyFileSync, writeFileSync, readFileSync, chmodSync, existsSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
 const { SCOPE, PLATFORMS } = require("../lib/platforms.js");
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const README_TEMPLATE = readFileSync(join(__dirname, "platform-package.README.md.tmpl"), "utf8");
+
+function renderReadme({ pkg, os, cpu }) {
+  return README_TEMPLATE
+    .replaceAll("{{SCOPE}}", SCOPE)
+    .replaceAll("{{PKG}}", pkg)
+    .replaceAll("{{OS}}", os)
+    .replaceAll("{{CPU}}", cpu);
+}
+
 function parseArgs(argv) {
   const args = {};
   for (let i = 0; i < argv.length; i += 2) {
@@ -63,6 +75,7 @@ for (const p of PLATFORMS) {
     files: ["bin/"],
   };
   writeFileSync(join(pkgDir, "package.json"), JSON.stringify(pkgJson, null, 2) + "\n");
+  writeFileSync(join(pkgDir, "README.md"), renderReadme(p));
 
   console.log(`built ${SCOPE}/${p.pkg}@${version} (${p.os}/${p.cpu}) -> ${dest}`);
 }

tools/npm/scripts/platform-package.README.md.tmpl

@@ -0,0 +1,11 @@
+# {{SCOPE}}/{{PKG}}
+
+Prebuilt `zcli` binary for **{{OS}}/{{CPU}}**.
+
+This package is an internal platform-specific dependency of [`{{SCOPE}}/zcli`](https://www.npmjs.com/package/{{SCOPE}}/zcli). You should not install it directly — install the main package instead, and npm will pull in the right platform binary via `optionalDependencies`:
+
+```sh
+npm i -g {{SCOPE}}/zcli
+```
+
+For docs, source, and issues see the [zeropsio/zcli](https://github.com/zeropsio/zcli) repository.