nim-toolchain 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# nim-toolchain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use a pinned native Nim compiler in an npm project. This package provides
+Nim **2.2.12**, its standard library, Nimble, and nimsuggest, using the
+[official Nim downloads](https://nim-lang.org/install.html).
+
+This is an independent npm wrapper maintained with MyNim, not an official
+Nim project package. The npm package version and Nim version are separate.
+
+## Install and compile
+
+Requires Node.js 22 or later and `tar` with support for the platform's archive
+format (`.tar.xz` on Unix, `.zip` on Windows). Linux also needs `xz` when
+required by its `tar`. macOS and Windows 10/11 include a suitable `tar`.
+
+Native compilation also requires a C compiler and the platform SDK: Xcode
+Command Line Tools on macOS, GCC or Clang on Linux, and MinGW or configured
+Visual C++ Build Tools on Windows. This package does not install those tools
+or run Nim's interactive `finish.exe` installer.
+
+```sh
+npm install --save-dev --save-exact nim-toolchain
+npx nim --version
+npx nimble --version
+```
+
+The first command that uses the toolchain downloads the pinned distribution
+from `nim-lang/nightlies` on GitHub and verifies its SHA-256 checksum before
+extraction. Subsequent commands use the cached distribution. No npm install
+scripts are required; `npm install --ignore-scripts` works too.
+
+Create `hello.nim`:
+
+```nim
+echo "Hello from Nim"
+```
+
+Compile and run it:
+
+```sh
+npx nim c -r hello.nim
+```
+
+The executable prints `Hello from Nim`. `npx nim` uses this package after it
+has been installed; the unrelated npm package named `nim` is not required.
+For a one-off command without installing a project dependency, use the
+package's own name:
+
+```sh
+npx nim-toolchain --version
+```
+
+All compiler arguments pass through unchanged. npm scripts can invoke `nim`,
+`nimble`, and `nimsuggest` directly.
+
+## Platforms and cache
+
+| OS | Architectures |
+| --- | --- |
+| macOS | arm64, x64 |
+| Linux with glibc | arm64, x64 |
+| Windows | x64 |
+
+Other platforms, including musl/Alpine Linux and native Windows arm64, fail
+with an unsupported-platform message. System Nim installations are left
+unchanged. Nimble starts with this distribution first on `PATH`; its own
+project dependency resolution still applies.
+
+Downloads require network access on first use. Cache locations are:
+
+- macOS: `~/Library/Caches/nim-toolchain`
+- Linux: `$XDG_CACHE_HOME/nim-toolchain`, or `~/.cache/nim-toolchain`
+- Windows: `%LOCALAPPDATA%\nim-toolchain\Cache`
+
+Set `NIM_TOOLCHAIN_CACHE` to use a different cache directory, including a
+directory restored by CI. **The cache path must not contain spaces or shell
+metacharacters:** the bundled Nimble 0.24.1 does not quote the compiler path
+when checking its version. If your home directory contains spaces, select a
+writable cache path without them. Project paths and compiler arguments may
+contain spaces.
+
+Each distribution has its own directory identified by version, platform, and
+checksum. Concurrent commands install into separate
+temporary directories and share the completed result. Incomplete downloads
+are discarded. A completed cache works without network access.
+
+## Use from another CLI
+
+```js
+import { spawnSync } from 'node:child_process';
+import { getToolchain, nimVersion } from 'nim-toolchain';
+
+const toolchain = await getToolchain();
+console.log(`Using Nim ${nimVersion}`);
+const result = spawnSync(toolchain.nim, ['c', 'hello.nim'], {
+  stdio: 'inherit',
+  env: toolchain.env,
+});
+if (result.error) throw result.error;
+process.exitCode = result.status ?? 1;
+```
+
+`getToolchain({ cacheDir })` can select an explicit cache directory. It returns
+absolute paths for `nim`, `nimble`, and `nimsuggest`, the distribution directory,
+its `binDirectory`, its version, and an environment with that `binDirectory`
+prepended to `PATH`. It rejects on download, verification, extraction, cache-path,
+or platform errors. Public declarations are in [index.d.ts](./index.d.ts).
+
+## Develop and release
+
+From this directory:
+
+```sh
+npm test
+npm run test:smoke
+npm pack --dry-run
+```
+
+Unit tests use local archives and HTTP fixtures. The smoke test downloads the
+real pinned toolchain, installs a packed copy in a temporary npm project with
+install scripts disabled, and compiles a Nim program through both Nim and
+Nimble. It requires the native build prerequisites above.
+
+To update Nim, choose a stable release linked from the official download page
+and update `release.json` with its exact release tag, filenames, and SHA-256
+digests. Verify every supported platform in CI and bump this npm package's
+version before publishing from this directory with `npm publish --access public`.
+
+The wrapper is MIT licensed. Downloaded distributions retain upstream files
+and license notices; see Nim's `copying.txt` in the distribution.

package/bin/nim.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runTool } from '../lib/run.js';
+await runTool('nim');

package/bin/nimble.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runTool } from '../lib/run.js';
+await runTool('nimble');

package/bin/nimsuggest.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runTool } from '../lib/run.js';
+await runTool('nimsuggest');

package/index.d.ts

@@ -0,0 +1,21 @@
+/** The exact upstream Nim version installed by this package. */
+export const nimVersion: string;
+
+/** A verified Nim distribution and environment for running its tools. */
+export interface Toolchain {
+  version: string;
+  directory: string;
+  binDirectory: string;
+  nim: string;
+  nimble: string;
+  nimsuggest: string;
+  env: Record<string, string | undefined>;
+}
+
+/**
+ * Download and verify the pinned Nim distribution if it is not cached.
+ * Throws for unsupported platforms or cache paths, failed downloads, or checksum mismatches.
+ * The default cache is user-owned; NIM_TOOLCHAIN_CACHE overrides its location.
+ * The cache path must not contain spaces or shell metacharacters (a Nimble limitation).
+ */
+export function getToolchain(options?: { cacheDir?: string }): Promise<Toolchain>;

package/index.js

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join, resolve } from 'node:path';
+import { installRelease } from './lib/install.js';
+
+const release = JSON.parse(readFileSync(new URL('./release.json', import.meta.url)));
+
+/** The exact upstream Nim version installed by this package. */
+export const nimVersion = release.version;
+
+function defaultCacheDir() {
+  if (process.env.NIM_TOOLCHAIN_CACHE) return process.env.NIM_TOOLCHAIN_CACHE;
+  if (process.platform === 'darwin') return join(homedir(), 'Library', 'Caches', 'nim-toolchain');
+  if (process.platform === 'win32') {
+    return join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'nim-toolchain', 'Cache');
+  }
+  return join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'nim-toolchain');
+}
+
+/**
+ * Download and verify the pinned Nim distribution if it is not cached.
+ * Returns absolute tool paths and an environment that uses this compiler for
+ * child processes, including compilers launched by Nimble.
+ *
+ * @param {{ cacheDir?: string }} [options] User-owned cache directory.
+ * @throws For unsupported platforms or cache paths, failed downloads, or checksum mismatches.
+ */
+export async function getToolchain({ cacheDir = defaultCacheDir() } = {}) {
+  const platform = `${process.platform}-${process.arch}`;
+  const asset = release.platforms[platform];
+  if (!asset) throw new Error(`Nim ${nimVersion} is not packaged for ${platform}.`);
+  if (process.platform === 'linux' && !process.report.getReport().header.glibcVersionRuntime) {
+    throw new Error('nim-toolchain requires glibc on Linux; use a system Nim installation on musl/Alpine.');
+  }
+  cacheDir = resolve(cacheDir);
+  // Bundled Nimble 0.24.1 interpolates the compiler path into a shell command.
+  // Reject paths it cannot quote safely rather than letting compilation fail later.
+  if (/[\s'"`$;&|<>()*?\[\]{}!]/u.test(cacheDir) || (process.platform !== 'win32' && cacheDir.includes('\\'))) {
+    throw new Error('The bundled Nimble requires a cache path without spaces or shell metacharacters. Set NIM_TOOLCHAIN_CACHE to such a directory.');
+  }
+
+  const directory = await installRelease({
+    cacheDir,
+    version: nimVersion,
+    platform,
+    url: `https://github.com/nim-lang/nightlies/releases/download/${release.tag}/${asset.file}`,
+    sha256: asset.sha256,
+  });
+  const binDirectory = join(directory, 'bin');
+  const extension = process.platform === 'win32' ? '.exe' : '';
+  const env = { ...process.env };
+  const pathKey = Object.keys(env).find(key => key.toUpperCase() === 'PATH') || 'PATH';
+  env[pathKey] = binDirectory + delimiter + (env[pathKey] || '');
+
+  return {
+    version: nimVersion,
+    directory,
+    binDirectory,
+    nim: join(binDirectory, 'nim' + extension),
+    nimble: join(binDirectory, 'nimble' + extension),
+    nimsuggest: join(binDirectory, 'nimsuggest' + extension),
+    env,
+  };
+}

package/lib/install.js

@@ -0,0 +1,79 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { access, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+async function isInstalled(directory, sha256, platform) {
+  try {
+    if (await readFile(join(directory, '.nim-toolchain'), 'utf8') !== sha256) return false;
+    const extension = platform.startsWith('win32-') ? '.exe' : '';
+    for (const tool of ['nim', 'nimble', 'nimsuggest']) {
+      await access(join(directory, 'bin', tool + extension));
+    }
+    await access(join(directory, 'lib', 'system.nim'));
+    await access(join(directory, 'config', 'nim.cfg'));
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+    throw error;
+  }
+}
+
+async function extract(archive, directory) {
+  await new Promise((resolve, reject) => {
+    const child = spawn('tar', ['-xf', archive, '-C', directory], { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', chunk => { stderr += chunk; });
+    child.on('error', error => reject(new Error(`Cannot extract Nim: tar is required (${error.message}).`)));
+    child.on('close', code => {
+      if (code === 0) resolve();
+      else reject(new Error(`Cannot extract Nim: ${stderr.trim() || `tar exited with ${code}`}`));
+    });
+  });
+}
+
+export async function installRelease({ cacheDir, version, platform, url, sha256 }) {
+  // Each process extracts privately; only a complete installation becomes visible.
+  // The digest separates different builds of the same upstream version.
+  const directory = join(cacheDir, `${version}-${platform}-${sha256}`);
+  if (await isInstalled(directory, sha256, platform)) return directory;
+  await mkdir(cacheDir, { recursive: true });
+  const temporary = await mkdtemp(join(cacheDir, '.download-'));
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    if (!response.ok) throw new Error(`Cannot download Nim ${version}: HTTP ${response.status}.`);
+    const archive = join(temporary, url.endsWith('.zip') ? 'nim.zip' : 'nim.tar.xz');
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(archive, { flags: 'wx' }));
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(archive)) hash.update(chunk);
+    const actual = hash.digest('hex');
+    if (actual !== sha256) {
+      throw new Error(`Nim ${version} checksum mismatch: expected ${sha256}, received ${actual}.`);
+    }
+
+    const extracted = join(temporary, 'extracted');
+    await mkdir(extracted);
+    await extract(archive, extracted);
+    const roots = await readdir(extracted, { withFileTypes: true });
+    if (roots.length !== 1 || !roots[0].isDirectory()) {
+      throw new Error(`Nim ${version} archive must contain a single toolchain directory.`);
+    }
+    const source = join(extracted, roots[0].name);
+    await writeFile(join(source, '.nim-toolchain'), sha256);
+    if (!await isInstalled(source, sha256, platform)) {
+      throw new Error(`Nim ${version} archive is missing compiler, tools, standard library, or configuration.`);
+    }
+    try {
+      await rename(source, directory);
+    } catch (error) {
+      // Another process may have installed the same verified release first.
+      if (!await isInstalled(directory, sha256, platform)) throw error;
+    }
+    return directory;
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}

package/lib/run.js

@@ -0,0 +1,33 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { getToolchain } from '../index.js';
+
+export async function runTool(tool) {
+  try {
+    const toolchain = await getToolchain();
+    const child = spawn(toolchain[tool], process.argv.slice(2), {
+      stdio: 'inherit',
+      env: toolchain.env,
+    });
+    const handlers = new Map();
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+      const forward = () => child.kill(signal);
+      handlers.set(signal, forward);
+      process.on(signal, forward);
+    }
+    try {
+      await new Promise((resolve, reject) => {
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+          process.exitCode = code ?? (128 + (constants.signals[signal] || 1));
+          resolve();
+        });
+      });
+    } finally {
+      for (const [signal, handler] of handlers) process.off(signal, handler);
+    }
+  } catch (error) {
+    console.error(`nim-toolchain: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "nim-toolchain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A pinned native Nim compiler, standard library, and Nimble for npm projects",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alec Larson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aleclarson/mynim.git",
+    "directory": "packages/nim-toolchain"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "nim-toolchain": "bin/nim.js",
+    "nim": "bin/nim.js",
+    "nimble": "bin/nimble.js",
+    "nimsuggest": "bin/nimsuggest.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "index.js",
+    "index.d.ts",
+    "release.json"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:smoke": "node test/smoke.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "nim",
+    "nimble",
+    "compiler",
+    "toolchain"
+  ]
+}

package/release.json

@@ -0,0 +1,27 @@
+{
+  "version": "2.2.12",
+  "source": "https://nim-lang.org/install.html",
+  "tag": "2026-09-08-version-2-2-8e8fbf60693418dc95bb0d762fd660231d08a583",
+  "platforms": {
+    "darwin-arm64": {
+      "file": "nim-2.2.12-macosx_arm64.tar.xz",
+      "sha256": "130a43eff76c1c3cc78b89329a7efd892c1f65839dbc6d8e53651f3f77516fe5"
+    },
+    "darwin-x64": {
+      "file": "nim-2.2.12-macosx_x64.tar.xz",
+      "sha256": "a09fa096aeb5f6ef32f8839eced2591e145e526e42f56c79e04a18519b8b132c"
+    },
+    "linux-arm64": {
+      "file": "nim-2.2.12-linux_arm64.tar.xz",
+      "sha256": "3dc04191af72a8310cf1c8ffb6f772cc3716fc5f264bc7c453ab4aecb4085221"
+    },
+    "linux-x64": {
+      "file": "nim-2.2.12-linux_x64.tar.xz",
+      "sha256": "7df1611449a6842af69322aa2c1206942982650a5f6bc0d37bc8ec109932f638"
+    },
+    "win32-x64": {
+      "file": "nim-2.2.12-windows_x64.zip",
+      "sha256": "dafe9c81f8118fac2e07ee24f3649448a590d8b0f3b55d1a97c66f99035cc8e6"
+    }
+  }
+}