xbintsc 0.5.32 → 0.5.37

package/runtime/xt_typed_array/elements.inc

@@ -58,6 +58,19 @@ const char *xt_typed_array_name_of(int kind) {
   return xt_ta_names[kind];
 }
 
+/* Public wrappers for extensions (ext_gui's audio decoder reads a Float32Array's
+ * bytes). `.buffer`/`.byteOffset` are accessors on the typed-array prototypes,
+ * so a raw `xt_object_get_cstr` cannot reach them. */
+int xt_is_typed_array(xt_value value) { return xt_typed_array_kind_of(value) >= 0; }
+
+xt_value xt_typed_array_backing_buffer(xt_value value) {
+  return xt_typed_array_kind_of(value) >= 0 ? xt_typed_array_buffer_of(value) : XT_UNDEFINED;
+}
+
+uint32_t xt_typed_array_view_offset(xt_value value) {
+  return xt_typed_array_kind_of(value) >= 0 ? xt_typed_array_byte_offset_of(value) : 0;
+}
+
 /* -- buffer-backed views -------------------------------------------------- */
 
 /* The backing ArrayBuffer and byte offset live under private symbols, so a

package/scripts/build-media.ts

@@ -65,7 +65,6 @@ const ffmpegInstall = join(ffmpegBuild, "dist");
 const objDir = join(root, "build", "media-obj");
 const outDir = join(runtimeDir, "lib", platformSlug());
 const output = join(outDir, isWindows ? "media.lib" : "media.a");
-const object = join(objDir, isWindows ? "media.obj" : "media.o");
 
 const FFMPEG_VERSION = process.env.FFMPEG_VERSION || "7.1";
 const FFMPEG_URL = `https://ffmpeg.org/releases/ffmpeg-${FFMPEG_VERSION}.tar.xz`;
@@ -478,28 +477,37 @@ if (!ffmpegInstalled()) {
  * because the *source* root contains a file literally named `version` that
  * would shadow the C++ standard header for any `.cpp` that includes it. */
 mkdirSync(objDir, { recursive: true });
-const playerSource = join(sourceDir, "media.cpp");
-console.log("xbintsc: compiling media.cpp");
+/* Two translation units: the file-oriented player and the in-memory decoder
+ * `decodeAudioData` uses. Both are merged into the archive; the bridge object
+ * references every entry point, so each member is extracted on demand. */
+const playerSources = ["media.cpp", "decode_audio.cpp"];
+const playerObjects: string[] = [];
 const cxxFlags = ["-std=c++17", "-O2", "-Wall", "-Wextra", "-I", runtimeDir, "-I", join(ffmpegInstall, "include")];
 /* The engine and the player are C++ with the static CRT (`libcpmt`), matching
  * FFmpeg's clang-cl objects and the xbintsc runtime; see `scripts/build-gui.ts`. */
 if (isWindows) cxxFlags.push("-Xclang", "--dependent-lib=libcpmt");
 else cxxFlags.push("-fPIC");
-run(clangxx, [...cxxFlags, "-c", playerSource, "-o", object]);
+for (const name of playerSources) {
+  const source = join(sourceDir, name);
+  const compiled = join(objDir, isWindows ? name.replace(/\.cpp$/, ".obj") : name.replace(/\.cpp$/, ".o"));
+  console.log(`xbintsc: compiling ${name}`);
+  run(clangxx, [...cxxFlags, "-c", source, "-o", compiled]);
+  playerObjects.push(compiled);
+}
 
 /* -- 4. merge into the archive -------------------------------------------- */
 
 mkdirSync(outDir, { recursive: true });
 rmSync(output, { force: true });
 if (process.platform === "darwin") {
-  run("libtool", ["-static", "-o", output, object, ...ffmpegStaticLibraries()!], { quietStderr: true });
+  run("libtool", ["-static", "-o", output, ...playerObjects, ...ffmpegStaticLibraries()!], { quietStderr: true });
 } else {
   /* `ar -M` (GNU/LLVM) merges archives through an MRI script. Windows paths are
    * normalised to `/` so the MRI parser does not read `\` as an escape. */
   const mri = (path: string): string => path.replace(/\\/g, "/");
   const script = [
     `create ${mri(output)}`,
-    `addmod ${mri(object)}`,
+    ...playerObjects.map((object) => `addmod ${mri(object)}`),
     ...ffmpegStaticLibraries()!.map((library) => `addlib ${mri(library)}`),
     "save",
     "end",

package/scripts/build-runtime.ts

@@ -5,13 +5,19 @@
  *   runtime/lib/<os>-<arch>/core.a       compiled from RUNTIME_SOURCES
  *   runtime/lib/<os>-<arch>/ext_node.a   compiled from nodeExtension.runtimeSources()
  *
+ * On Windows the same archives are written as MSVC-compatible COFF libraries
+ * (`core.lib`, `ext_node.lib`): the objects are compiled by the MSVC-targeting
+ * clang the driver uses and merged by `llvm-ar`, exactly like `gui.lib` and
+ * `media.lib`.
+ *
  * The driver prefers these archives (see `src/driver/runtime-lib.ts`) and falls
  * back to compiling the C sources on demand when they are missing. Run this in
- * CI (or locally) after the runtime sources change.
+ * CI (or locally) after the runtime sources change; `scripts/package-platform.ts`
+ * then places the result in the optional `@xbintsc/<os>-<arch>` npm package.
  *
  * Environment:
  *   xbintsc_CLANG  C compiler override (otherwise the resolved toolchain is used)
- *   xbintsc_AR     archiver override (otherwise `llvm-ar`, then `ar`)
+ *   xbintsc_AR     archiver override (otherwise `llvm-ar`, then `ar` on POSIX)
  */
 
 import { mkdirSync, rmSync } from "node:fs";
@@ -28,15 +34,8 @@ const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const runtimeDir = join(root, "runtime");
 const outDir = join(runtimeDir, "lib", platformSlug());
 const objDir = join(root, "build", "runtime-obj");
-
-if (process.platform === "win32") {
-  // The driver links with the MSVC ABI on Windows, where the prebuilt archives
-  // are unnecessary: `build` compiles the runtime C sources on demand with the
-  // user's clang. (Producing MSVC-compatible COFF `.lib` archives is possible
-  // but not worth the extra step.)
-  console.log("xbintsc: skipping runtime archives on Windows; the driver compiles the C sources on demand");
-  process.exit(0);
-}
+const isWindows = process.platform === "win32";
+const archiveSuffix = isWindows ? ".lib" : ".a";
 
 // Use the same toolchain the driver will.
 const toolchain = resolveToolchain();
@@ -51,18 +50,24 @@ function isRunnable(candidate: string): boolean {
 
 function findArchiver(clangPath: string): string {
   const dir = dirname(clangPath);
-  const exe = process.platform === "win32" ? ".exe" : "";
+  const exe = isWindows ? ".exe" : "";
   const candidates = [
     process.env.xbintsc_AR,
     // A clang install usually ships `llvm-ar` next to the driver.
     dir === "." ? undefined : join(dir, `llvm-ar${exe}`),
     "llvm-ar",
-    "ar",
+    // On Windows only LLVM's archiver is known to write the COFF flavour the
+    // MSVC linker accepts; never fall back to a GNU `ar`.
+    isWindows ? undefined : "ar",
   ].filter((candidate): candidate is string => Boolean(candidate));
   for (const candidate of candidates) {
     if (isRunnable(candidate)) return candidate;
   }
-  console.error("xbintsc: no archiver found; set xbintsc_AR to llvm-ar or ar");
+  console.error(
+    isWindows
+      ? "xbintsc: no archiver found; install llvm-ar or set xbintsc_AR to it"
+      : "xbintsc: no archiver found; set xbintsc_AR to llvm-ar or ar",
+  );
   process.exit(1);
 }
 
@@ -101,9 +106,9 @@ console.log(`xbintsc: runtime toolchain ${clang} (${toolchain.source})`);
 const coreObjects = compile(RUNTIME_SOURCES.map((source) => join(runtimeDir, source)), "core");
 
 const ar = findArchiver(clang);
-archive("core.a", coreObjects, ar);
+archive(`core${archiveSuffix}`, coreObjects, ar);
 
 const nodeSources = nodeExtension.runtimeSources?.() ?? [];
 if (nodeSources.length > 0) {
-  archive("ext_node.a", compile(nodeSources, "node"), ar);
+  archive(`ext_node${archiveSuffix}`, compile(nodeSources, "node"), ar);
 }

package/scripts/check-version.ts

@@ -1,18 +1,25 @@
 #!/usr/bin/env node
 /**
- * Verify that `COMPILER_VERSION` (reported by `xbintsc version` / `doctor` and
- * embedded in the incremental cache key) matches the version in `package.json`
- * (which names the release archives).
+ * Verify the release bookkeeping that must agree before a tag is pushed:
  *
- * Release automation runs this before tagging. A mismatch means an upgraded
- * compiler can reuse binaries produced by the previous one while presenting the
- * wrong version to bug reports.
+ *   1. `COMPILER_VERSION` (reported by `xbintsc version` / `doctor` and embedded
+ *      in the incremental cache key) matches the version in `package.json`;
+ *   2. every `@xbintsc/<os>-<arch>` optional dependency is either the current
+ *      version (a release checkout) or the published `0.0.0` placeholder (the
+ *      committed state; release automation rewrites it before `npm publish`).
+ *
+ * A mismatch means an upgraded compiler can reuse binaries produced by the
+ * previous one while presenting the wrong version to bug reports, or that an
+ * install would ask npm for a platform package that does not exist.
  */
 
 import { readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+/** The version of the empty `@xbintsc/*` packages created before a release. */
+export const PLATFORM_PLACEHOLDER_VERSION = "0.0.0";
+
 /** Read the version literal from the compiler source. */
 export function compilerVersionOf(root: string): string {
   const text = readFileSync(join(root, "src", "driver", "version.ts"), "utf8");
@@ -39,14 +46,37 @@ export function checkCompilerVersion(root: string): string | undefined {
   );
 }
 
+/**
+ * Returns a message when a platform optional dependency names a version that is
+ * neither the release version nor the placeholder, or `undefined` when valid.
+ */
+export function checkPlatformVersions(root: string): string | undefined {
+  const parsed = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+    version: string;
+    optionalDependencies?: Record<string, string>;
+  };
+  for (const [name, spec] of Object.entries(parsed.optionalDependencies ?? {})) {
+    if (!name.startsWith("@xbintsc/")) continue;
+    if (spec === parsed.version || spec === PLATFORM_PLACEHOLDER_VERSION) continue;
+    return (
+      `optional dependency ${name} is "${spec}", but package.json is "${parsed.version}".\n` +
+      `Use "${PLATFORM_PLACEHOLDER_VERSION}" in the committed manifest (release automation rewrites it) ` +
+      `or "${parsed.version}" in a release checkout.`
+    );
+  }
+  return undefined;
+}
+
 const invokedDirectly =
   process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
 
 if (invokedDirectly) {
   const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-  const mismatch = checkCompilerVersion(root);
-  if (mismatch) {
-    process.stderr.write(`xbintsc: version mismatch\n${mismatch}\n`);
+  const problems = [checkCompilerVersion(root), checkPlatformVersions(root)].filter(
+    (problem): problem is string => problem !== undefined,
+  );
+  if (problems.length > 0) {
+    process.stderr.write(`xbintsc: version mismatch\n${problems.join("\n")}\n`);
     process.exit(1);
   }
   process.stdout.write(`xbintsc: version ${compilerVersionOf(root)} matches package.json\n`);

package/scripts/package-platform.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Assemble the optional `@xbintsc/<os>-<arch>` npm package for the current host.
+ *
+ * The package carries the prebuilt archives in the same layout the compiler
+ * already searches:
+ *
+ *   package/runtime/lib/<os>-<arch>/{core,ext_node}.{a,lib}
+ *   package/runtime/lib/<os>-<arch>/gui.{a,lib}       (when the release ships it)
+ *   package/runtime/lib/<os>-<arch>/media.{a,lib}     (when the release ships it)
+ *
+ * `xbintsc` lists these packages in `optionalDependencies`, so npm installs the
+ * one matching the host and the driver links its archives instead of compiling
+ * the C runtime. Release automation publishes the tarball produced here; see
+ * `.github/workflows/release.yml`.
+ *
+ * Output: `dist/npm-platform/xbintsc-<os>-<arch>-<version>.tgz`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { platformSlug } from "../src/driver/paths.js";
+
+export interface PackageRepository {
+  readonly type: string;
+  readonly url: string;
+}
+
+export interface PlatformPackageOptions {
+  readonly version: string;
+  readonly slug: string;
+  readonly repository?: PackageRepository;
+}
+
+export interface PlatformPackageManifest {
+  readonly name: string;
+  readonly version: string;
+  readonly description: string;
+  readonly license: string;
+  readonly repository?: PackageRepository;
+  readonly os: readonly string[];
+  readonly cpu: readonly string[];
+  readonly files: readonly string[];
+  readonly publishConfig: { readonly access: "public" };
+}
+
+/** Every host a release publishes a platform package for. */
+export const PLATFORM_SLUGS = [
+  "linux-x64",
+  "linux-arm64",
+  "darwin-x64",
+  "darwin-arm64",
+  "win32-x64",
+  "win32-arm64",
+] as const;
+
+/** npm name of the platform package, e.g. `@xbintsc/linux-x64`. */
+export function platformPackageName(slug: string): string {
+  return `@xbintsc/${slug}`;
+}
+
+/**
+ * File name `npm pack` gives the platform package, e.g.
+ * `xbintsc-linux-x64-1.2.3.tgz` (npm drops the scope from the file name).
+ */
+export function platformPackageFileName(slug: string, version: string): string {
+  return `xbintsc-${slug}-${version}.tgz`;
+}
+
+/** Split `linux-x64` into its npm `os` and `cpu` constraints. */
+function splitSlug(slug: string): { os: string; arch: string } {
+  const dash = slug.lastIndexOf("-");
+  if (dash <= 0 || dash === slug.length - 1) {
+    throw new Error(`invalid platform slug "${slug}" (expected <os>-<arch>)`);
+  }
+  return { os: slug.slice(0, dash), arch: slug.slice(dash + 1) };
+}
+
+/** Archives every platform package must contain. */
+export function requiredArchives(slug: string): string[] {
+  const suffix = slug.startsWith("win32-") ? ".lib" : ".a";
+  return [`core${suffix}`, `ext_node${suffix}`];
+}
+
+/** The package manifest written into the staging tree and packed by npm. */
+export function platformPackageManifest(options: PlatformPackageOptions): PlatformPackageManifest {
+  const { os, arch } = splitSlug(options.slug);
+  const name = platformPackageName(options.slug);
+  return {
+    name,
+    version: options.version,
+    description: `Prebuilt xbintsc C runtime archives for ${options.slug}. Installed automatically by xbintsc.`,
+    license: "MIT",
+    ...(options.repository ? { repository: options.repository } : {}),
+    os: [os],
+    cpu: [arch],
+    files: ["runtime"],
+    publishConfig: { access: "public" },
+  };
+}
+
+/** Run npm through the same CLI that invoked this script, when available. */
+function runNpm(args: readonly string[], cwd: string): { stdout: string } {
+  const execPath = process.env.npm_execpath;
+  const useCli = execPath !== undefined && /\.(cjs|mjs|js)$/.test(execPath);
+  const command = useCli ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
+  const commandArgs = useCli ? [execPath, ...args] : [...args];
+  const result = spawnSync(command, commandArgs, {
+    cwd,
+    encoding: "utf8",
+    shell: !useCli && process.platform === "win32",
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`npm ${args.join(" ")} failed (${result.status}):\n${result.stderr}`);
+  }
+  return { stdout: result.stdout };
+}
+
+/**
+ * Copy the host's archives into a staging tree, write the manifest and run
+ * `npm pack`. Returns the absolute path of the produced `.tgz`.
+ */
+export function packagePlatform(root: string, slug: string = platformSlug()): string {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+    version: string;
+    repository?: PackageRepository;
+  };
+  const libDir = join(root, "runtime", "lib", slug);
+  const missing = requiredArchives(slug).filter((name) => !existsSync(join(libDir, name)));
+  if (missing.length > 0) {
+    throw new Error(`missing ${missing.join(", ")} in ${libDir}; run \`npm run runtime\` first`);
+  }
+
+  const stageRoot = join(root, "build", "npm-platform-stage");
+  const stage = join(stageRoot, "package");
+  rmSync(stageRoot, { recursive: true, force: true });
+  mkdirSync(stage, { recursive: true });
+  cpSync(libDir, join(stage, "runtime", "lib", slug), { recursive: true });
+
+  const manifest = platformPackageManifest({
+    version: pkg.version,
+    slug,
+    ...(pkg.repository ? { repository: pkg.repository } : {}),
+  });
+  writeFileSync(join(stage, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+  writeFileSync(
+    join(stage, "README.md"),
+    `# ${manifest.name}\n\n` +
+      `Prebuilt xbintsc runtime archives for \`${slug}\`.\n\n` +
+      `This package is installed automatically as an optional dependency of\n` +
+      `[\`xbintsc\`](https://www.npmjs.com/package/xbintsc) and is not meant to be\n` +
+      `used on its own. The compiler links \`runtime/lib/${slug}/\` from this\n` +
+      `package instead of compiling its C runtime on the first build.\n`,
+  );
+  const license = join(root, "LICENSE");
+  if (existsSync(license)) cpSync(license, join(stage, "LICENSE"));
+
+  const outDir = join(root, "dist", "npm-platform");
+  rmSync(outDir, { recursive: true, force: true });
+  mkdirSync(outDir, { recursive: true });
+  const packed = JSON.parse(runNpm(["pack", "--json", "--pack-destination", outDir], stage).stdout) as Array<{
+    filename?: string;
+  }>;
+  const filename = packed[0]?.filename;
+  if (!filename) throw new Error("npm pack did not report a tarball name");
+  return join(outDir, filename);
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  try {
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    console.log(`xbintsc: wrote ${packagePlatform(root)}`);
+  } catch (error) {
+    console.error(`xbintsc: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}

package/scripts/set-platform-version.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * Point `optionalDependencies` at the version being released.
+ *
+ * The repository keeps every `@xbintsc/<os>-<arch>` entry on the `0.0.0`
+ * placeholder: those packages exist on npm (an empty first publish), while a
+ * release version does not exist until this workflow publishes it. Committing a
+ * not-yet-published version would make `npm ci` resolve a missing tarball.
+ *
+ * Release automation runs this after the platform tarballs have been validated
+ * and published, immediately before `npm publish`, so the published `xbintsc`
+ * manifest depends on the platform packages built from the same commit.
+ *
+ * Usage: `npm run platform-versions -- --version <x.y.z>` (defaults to the
+ * version in package.json).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/** Rewrite every platform optional dependency; returns the names changed. */
+export function setPlatformVersions(root: string, version: string): string[] {
+  const manifestPath = join(root, "package.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    optionalDependencies?: Record<string, string>;
+  };
+  const dependencies = manifest.optionalDependencies;
+  if (!dependencies) throw new Error("package.json has no optionalDependencies");
+  const changed: string[] = [];
+  for (const name of Object.keys(dependencies)) {
+    if (!name.startsWith("@xbintsc/")) continue;
+    if (dependencies[name] === version) continue;
+    dependencies[name] = version;
+    changed.push(name);
+  }
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return changed;
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  try {
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    const flag = process.argv.indexOf("--version");
+    const version =
+      flag >= 0 && process.argv[flag + 1] !== undefined
+        ? process.argv[flag + 1]!
+        : (JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { version: string }).version;
+    const changed = setPlatformVersions(root, version);
+    console.log(
+      changed.length > 0
+        ? `xbintsc: platform optionalDependencies -> ${version} (${changed.length} packages)`
+        : `xbintsc: platform optionalDependencies already at ${version}`,
+    );
+  } catch (error) {
+    console.error(`xbintsc: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}

package/scripts/verify-platform-package.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * Verify the `@xbintsc/<os>-<arch>` npm tarballs staged for a release.
+ *
+ * `release.yml` publishes one platform package per host before `xbintsc` and
+ * then points the main manifest's `optionalDependencies` at exactly those
+ * versions, so every tarball has to prove it was packed from this release: its
+ * manifest must name `@xbintsc/<slug>@<version>` and it must carry the runtime
+ * archives the driver links (`core` and `ext_node`, see `requiredArchives`).
+ *
+ * This runs in Node on purpose. The check used to be a shell pipeline,
+ * `tar -tf x.tgz | grep -q <pattern>`, under `set -o pipefail`: `grep -q` closes
+ * the pipe on its first match, so `tar` — still decompressing the tens of
+ * megabytes that follow `core.a` — dies of SIGPIPE, and the pipeline reports a
+ * perfectly good tarball as "has no core runtime archive". Reading the gzip
+ * stream here has no such race, needs no external `tar` and behaves the same on
+ * every host.
+ *
+ * Usage: `npm run verify:platform -- --dir platform-packages [--version x.y.z]`
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { gunzipSync } from "node:zlib";
+import {
+  PLATFORM_SLUGS,
+  platformPackageFileName,
+  platformPackageName,
+  requiredArchives,
+} from "./package-platform.js";
+
+/** One member of a tar archive; `data` is a view into the decompressed stream. */
+export interface TarEntry {
+  readonly path: string;
+  readonly data: Buffer;
+}
+
+const BLOCK = 512;
+
+/** Read a header field, stopping at its NUL padding. */
+function readString(block: Buffer, offset: number, length: number): string {
+  const field = block.subarray(offset, offset + length);
+  const end = field.indexOf(0);
+  return field.subarray(0, end === -1 ? field.length : end).toString("utf8");
+}
+
+/** Decode a numeric header field (octal, or base-256 for very large values). */
+function readNumber(block: Buffer, offset: number, length: number): number {
+  if ((block[offset]! & 0x80) !== 0) {
+    let value = block[offset]! & 0x7f;
+    for (let index = 1; index < length; index += 1) value = value * 256 + block[offset + index]!;
+    return value;
+  }
+  const text = readString(block, offset, length).trim();
+  return text === "" ? 0 : Number.parseInt(text, 8);
+}
+
+/** The `path=` record of a pax extended header, when it carries one. */
+function paxPath(data: Buffer): string | undefined {
+  // Records are `<byte length> <key>=<value>\n`; only the path matters here.
+  const match = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(data.toString("utf8"));
+  return match?.[1];
+}
+
+/** List the regular files of a gzip-compressed tar archive, in archive order. */
+export function tarballEntries(tgz: Buffer, source = "tarball"): TarEntry[] {
+  let tar: Buffer;
+  try {
+    tar = gunzipSync(tgz);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`${source} is not a gzip-compressed tar archive (${reason})`);
+  }
+  const entries: TarEntry[] = [];
+  let offset = 0;
+  let override: string | undefined;
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK);
+    if (header.every((byte) => byte === 0)) break;
+    const size = readNumber(header, 124, 12);
+    const type = header[156] === 0 ? "0" : String.fromCharCode(header[156]!);
+    const dataStart = offset + BLOCK;
+    if (dataStart + size > tar.length) throw new Error(`${source} is truncated`);
+    const data = tar.subarray(dataStart, dataStart + size);
+    offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+
+    // A long path arrives in its own preceding header: GNU `L` stores it
+    // verbatim, pax `x` records it as `path=`. `K` only renames a link target.
+    if (type === "L") {
+      override = readString(data, 0, data.length);
+      continue;
+    }
+    if (type === "x") {
+      override = paxPath(data) ?? override;
+      continue;
+    }
+    if (type === "K") continue;
+
+    const prefix = readString(header, 345, 155);
+    const name = readString(header, 0, 100);
+    const path = override ?? (prefix === "" ? name : `${prefix}/${name}`);
+    override = undefined;
+    // Only regular files can be the archives checked below; directories and
+    // links are skipped instead of being reported by their trailing slash.
+    if (type === "0" || type === "7") entries.push({ path, data });
+  }
+  return entries;
+}
+
+/** Read the manifest out of an already-parsed platform tarball. */
+function manifestOf(entries: readonly TarEntry[], source: string): { name?: string; version?: string } {
+  const manifest = entries.find((entry) => entry.path === "package/package.json");
+  if (!manifest) throw new Error(`${source} has no package/package.json`);
+  try {
+    return JSON.parse(manifest.data.toString("utf8")) as { name?: string; version?: string };
+  } catch {
+    throw new Error(`${source} has an unreadable package/package.json`);
+  }
+}
+
+/**
+ * Check one platform tarball's manifest identity and runtime archives.
+ * `source` names the tarball in error messages (its path, or a fixture name).
+ */
+export function verifyPlatformEntries(
+  entries: readonly TarEntry[],
+  slug: string,
+  version: string,
+  source = "platform package",
+): void {
+  const parsed = manifestOf(entries, source);
+  const expectedName = platformPackageName(slug);
+  if (parsed.name !== expectedName || parsed.version !== version) {
+    throw new Error(`${source} contains ${parsed.name}@${parsed.version}, expected ${expectedName}@${version}`);
+  }
+
+  const paths = new Set(entries.map((entry) => entry.path));
+  for (const archive of requiredArchives(slug)) {
+    const expected = `package/runtime/lib/${slug}/${archive}`;
+    if (paths.has(expected)) continue;
+    // Keep the historical wording: `core.a`/`core.lib` is "the core archive".
+    const label = archive.replace(/\.(a|lib)$/, "");
+    throw new Error(`${source} has no ${label} runtime archive (expected ${expected})`);
+  }
+}
+
+/** Read `tgzPath` and verify it as the platform package for `slug`/`version`. */
+export function verifyPlatformPackage(tgzPath: string, slug: string, version: string): TarEntry[] {
+  const entries = tarballEntries(readFileSync(tgzPath), tgzPath);
+  verifyPlatformEntries(entries, slug, version, tgzPath);
+  return entries;
+}
+
+/** Value of `--name <value>`, or `undefined` when the flag is absent. */
+function argument(name: string): string | undefined {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : undefined;
+}
+
+const invokedDirectly =
+  process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (invokedDirectly) {
+  try {
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    const dir = argument("--dir") ?? join(root, "platform-packages");
+    const version =
+      argument("--version") ??
+      (JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { version: string }).version;
+    for (const slug of PLATFORM_SLUGS) {
+      const file = join(dir, platformPackageFileName(slug, version));
+      if (!existsSync(file)) throw new Error(`Missing npm platform package ${file}.`);
+      const entries = verifyPlatformPackage(file, slug, version);
+      console.log(`xbintsc: ${basename(file)} carries ${entries.length} files`);
+    }
+    console.log(`xbintsc: verified ${PLATFORM_SLUGS.length} platform packages at ${version}`);
+  } catch (error) {
+    console.error(`xbintsc: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}

package/src/cli/main.ts

@@ -20,7 +20,7 @@ import { formatDiagnostic, type Diagnostic } from "../diagnostics/diagnostic.js"
 import { SourceFile } from "../diagnostics/source.js";
 import { build, compileEntry, COMPILER_VERSION, type EmitKind, type PhaseTiming } from "../driver/compiler.js";
 import { findRuntimeDir, platformSlug } from "../driver/paths.js";
-import { runtimeLibDir } from "../driver/runtime-lib.js";
+import { findRuntimeLibrary, runtimeLibDir } from "../driver/runtime-lib.js";
 import { resolveToolchain, type ResolvedToolchain } from "../driver/toolchain-provider.js";
 import { MINIMUM_CLANG_MAJOR, probeClang, realRunner, ToolchainError } from "../driver/toolchain.js";
 import {
@@ -290,6 +290,10 @@ function doctor(io: CliIo): number {
 
   try {
     io.stdout(`runtime lib: ${runtimeLibDir()}\n`);
+    const archives = ["core", "ext_node", "gui", "media"].filter((name) => findRuntimeLibrary(name) !== undefined);
+    io.stdout(
+      `archives   : ${archives.length > 0 ? archives.join(", ") : "none (C runtime compiled on demand)"}\n`,
+    );
   } catch {
     io.stdout("runtime lib: unavailable\n");
   }