clojurific 0.0.0-stage → 0.12.2

package/LICENSE.html

@@ -0,0 +1,261 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+<title>Eclipse Public License - Version 1.0</title>
+<style type="text/css">
+  body {
+    size: 8.5in 11.0in;
+    margin: 0.25in 0.5in 0.25in 0.5in;
+    tab-interval: 0.5in;
+    }
+  p {  	
+    margin-left: auto;
+    margin-top:  0.5em;
+    margin-bottom: 0.5em;
+    }
+  p.list {
+  	margin-left: 0.5in;
+    margin-top:  0.05em;
+    margin-bottom: 0.05em;
+    }
+  </style>
+
+</head>
+
+<body lang="EN-US">
+
+<p align=center><b>Eclipse Public License - v 1.0</b></p>
+
+<p>THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
+PUBLIC LICENSE (&quot;AGREEMENT&quot;). ANY USE, REPRODUCTION OR
+DISTRIBUTION OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS
+AGREEMENT.</p>
+
+<p><b>1. DEFINITIONS</b></p>
+
+<p>&quot;Contribution&quot; means:</p>
+
+<p class="list">a) in the case of the initial Contributor, the initial
+code and documentation distributed under this Agreement, and</p>
+<p class="list">b) in the case of each subsequent Contributor:</p>
+<p class="list">i) changes to the Program, and</p>
+<p class="list">ii) additions to the Program;</p>
+<p class="list">where such changes and/or additions to the Program
+originate from and are distributed by that particular Contributor. A
+Contribution 'originates' from a Contributor if it was added to the
+Program by such Contributor itself or anyone acting on such
+Contributor's behalf. Contributions do not include additions to the
+Program which: (i) are separate modules of software distributed in
+conjunction with the Program under their own license agreement, and (ii)
+are not derivative works of the Program.</p>
+
+<p>&quot;Contributor&quot; means any person or entity that distributes
+the Program.</p>
+
+<p>&quot;Licensed Patents&quot; mean patent claims licensable by a
+Contributor which are necessarily infringed by the use or sale of its
+Contribution alone or when combined with the Program.</p>
+
+<p>&quot;Program&quot; means the Contributions distributed in accordance
+with this Agreement.</p>
+
+<p>&quot;Recipient&quot; means anyone who receives the Program under
+this Agreement, including all Contributors.</p>
+
+<p><b>2. GRANT OF RIGHTS</b></p>
+
+<p class="list">a) Subject to the terms of this Agreement, each
+Contributor hereby grants Recipient a non-exclusive, worldwide,
+royalty-free copyright license to reproduce, prepare derivative works
+of, publicly display, publicly perform, distribute and sublicense the
+Contribution of such Contributor, if any, and such derivative works, in
+source code and object code form.</p>
+
+<p class="list">b) Subject to the terms of this Agreement, each
+Contributor hereby grants Recipient a non-exclusive, worldwide,
+royalty-free patent license under Licensed Patents to make, use, sell,
+offer to sell, import and otherwise transfer the Contribution of such
+Contributor, if any, in source code and object code form. This patent
+license shall apply to the combination of the Contribution and the
+Program if, at the time the Contribution is added by the Contributor,
+such addition of the Contribution causes such combination to be covered
+by the Licensed Patents. The patent license shall not apply to any other
+combinations which include the Contribution. No hardware per se is
+licensed hereunder.</p>
+
+<p class="list">c) Recipient understands that although each Contributor
+grants the licenses to its Contributions set forth herein, no assurances
+are provided by any Contributor that the Program does not infringe the
+patent or other intellectual property rights of any other entity. Each
+Contributor disclaims any liability to Recipient for claims brought by
+any other entity based on infringement of intellectual property rights
+or otherwise. As a condition to exercising the rights and licenses
+granted hereunder, each Recipient hereby assumes sole responsibility to
+secure any other intellectual property rights needed, if any. For
+example, if a third party patent license is required to allow Recipient
+to distribute the Program, it is Recipient's responsibility to acquire
+that license before distributing the Program.</p>
+
+<p class="list">d) Each Contributor represents that to its knowledge it
+has sufficient copyright rights in its Contribution, if any, to grant
+the copyright license set forth in this Agreement.</p>
+
+<p><b>3. REQUIREMENTS</b></p>
+
+<p>A Contributor may choose to distribute the Program in object code
+form under its own license agreement, provided that:</p>
+
+<p class="list">a) it complies with the terms and conditions of this
+Agreement; and</p>
+
+<p class="list">b) its license agreement:</p>
+
+<p class="list">i) effectively disclaims on behalf of all Contributors
+all warranties and conditions, express and implied, including warranties
+or conditions of title and non-infringement, and implied warranties or
+conditions of merchantability and fitness for a particular purpose;</p>
+
+<p class="list">ii) effectively excludes on behalf of all Contributors
+all liability for damages, including direct, indirect, special,
+incidental and consequential damages, such as lost profits;</p>
+
+<p class="list">iii) states that any provisions which differ from this
+Agreement are offered by that Contributor alone and not by any other
+party; and</p>
+
+<p class="list">iv) states that source code for the Program is available
+from such Contributor, and informs licensees how to obtain it in a
+reasonable manner on or through a medium customarily used for software
+exchange.</p>
+
+<p>When the Program is made available in source code form:</p>
+
+<p class="list">a) it must be made available under this Agreement; and</p>
+
+<p class="list">b) a copy of this Agreement must be included with each
+copy of the Program.</p>
+
+<p>Contributors may not remove or alter any copyright notices contained
+within the Program.</p>
+
+<p>Each Contributor must identify itself as the originator of its
+Contribution, if any, in a manner that reasonably allows subsequent
+Recipients to identify the originator of the Contribution.</p>
+
+<p><b>4. COMMERCIAL DISTRIBUTION</b></p>
+
+<p>Commercial distributors of software may accept certain
+responsibilities with respect to end users, business partners and the
+like. While this license is intended to facilitate the commercial use of
+the Program, the Contributor who includes the Program in a commercial
+product offering should do so in a manner which does not create
+potential liability for other Contributors. Therefore, if a Contributor
+includes the Program in a commercial product offering, such Contributor
+(&quot;Commercial Contributor&quot;) hereby agrees to defend and
+indemnify every other Contributor (&quot;Indemnified Contributor&quot;)
+against any losses, damages and costs (collectively &quot;Losses&quot;)
+arising from claims, lawsuits and other legal actions brought by a third
+party against the Indemnified Contributor to the extent caused by the
+acts or omissions of such Commercial Contributor in connection with its
+distribution of the Program in a commercial product offering. The
+obligations in this section do not apply to any claims or Losses
+relating to any actual or alleged intellectual property infringement. In
+order to qualify, an Indemnified Contributor must: a) promptly notify
+the Commercial Contributor in writing of such claim, and b) allow the
+Commercial Contributor to control, and cooperate with the Commercial
+Contributor in, the defense and any related settlement negotiations. The
+Indemnified Contributor may participate in any such claim at its own
+expense.</p>
+
+<p>For example, a Contributor might include the Program in a commercial
+product offering, Product X. That Contributor is then a Commercial
+Contributor. If that Commercial Contributor then makes performance
+claims, or offers warranties related to Product X, those performance
+claims and warranties are such Commercial Contributor's responsibility
+alone. Under this section, the Commercial Contributor would have to
+defend claims against the other Contributors related to those
+performance claims and warranties, and if a court requires any other
+Contributor to pay any damages as a result, the Commercial Contributor
+must pay those damages.</p>
+
+<p><b>5. NO WARRANTY</b></p>
+
+<p>EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS
+PROVIDED ON AN &quot;AS IS&quot; BASIS, WITHOUT WARRANTIES OR CONDITIONS
+OF ANY KIND, EITHER EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION,
+ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY
+OR FITNESS FOR A PARTICULAR PURPOSE. Each Recipient is solely
+responsible for determining the appropriateness of using and
+distributing the Program and assumes all risks associated with its
+exercise of rights under this Agreement , including but not limited to
+the risks and costs of program errors, compliance with applicable laws,
+damage to or loss of data, programs or equipment, and unavailability or
+interruption of operations.</p>
+
+<p><b>6. DISCLAIMER OF LIABILITY</b></p>
+
+<p>EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT
+NOR ANY CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING
+WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR
+DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED
+HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.</p>
+
+<p><b>7. GENERAL</b></p>
+
+<p>If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement, and without further action
+by the parties hereto, such provision shall be reformed to the minimum
+extent necessary to make such provision valid and enforceable.</p>
+
+<p>If Recipient institutes patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that the
+Program itself (excluding combinations of the Program with other
+software or hardware) infringes such Recipient's patent(s), then such
+Recipient's rights granted under Section 2(b) shall terminate as of the
+date such litigation is filed.</p>
+
+<p>All Recipient's rights under this Agreement shall terminate if it
+fails to comply with any of the material terms or conditions of this
+Agreement and does not cure such failure in a reasonable period of time
+after becoming aware of such noncompliance. If all Recipient's rights
+under this Agreement terminate, Recipient agrees to cease use and
+distribution of the Program as soon as reasonably practicable. However,
+Recipient's obligations under this Agreement and any licenses granted by
+Recipient relating to the Program shall continue and survive.</p>
+
+<p>Everyone is permitted to copy and distribute copies of this
+Agreement, but in order to avoid inconsistency the Agreement is
+copyrighted and may only be modified in the following manner. The
+Agreement Steward reserves the right to publish new versions (including
+revisions) of this Agreement from time to time. No one other than the
+Agreement Steward has the right to modify this Agreement. The Eclipse
+Foundation is the initial Agreement Steward. The Eclipse Foundation may
+assign the responsibility to serve as the Agreement Steward to a
+suitable separate entity. Each new version of the Agreement will be
+given a distinguishing version number. The Program (including
+Contributions) may always be distributed subject to the version of the
+Agreement under which it was received. In addition, after a new version
+of the Agreement is published, Contributor may elect to distribute the
+Program (including its Contributions) under the new version. Except as
+expressly stated in Sections 2(a) and 2(b) above, Recipient receives no
+rights or licenses to the intellectual property of any Contributor under
+this Agreement, whether expressly, by implication, estoppel or
+otherwise. All rights in the Program not expressly granted under this
+Agreement are reserved.</p>
+
+<p>This Agreement is governed by the laws of the State of New York and
+the intellectual property laws of the United States of America. No party
+to this Agreement will bring a legal action under this Agreement more
+than one year after the cause of action arose. Each party waives its
+rights to a jury trial in any resulting litigation.</p>
+
+</body>
+
+</html>

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# clojurific
 
-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.
+ClojureScript compiled to ES modules, bundled by Vite.
+
+[Clojurific](https://github.com/WhimsicalCode/clojurific) is a fork of
+ClojureScript whose `:module-format :esm` compiles every namespace to an ES
+module, leaving bundling, minification, npm packages and TypeScript to Vite,
+without the Google Closure Compiler. This package has the `cljf` command, a
+Vite plugin with hot reloading, and a Karma adapter; `cljf` gets the compiler,
+`com.whimsical/clojurific`, from Clojars. It needs
+Node.js 20 or later and Java 17 or later, not the Clojure CLI.
+
+Status: experimental. Versions are `0.<minor>.<release>`: `<minor>` is the
+ClojureScript 1.x release it's compatible with (12 for 1.12.x), `<release>`
+counts Clojurific's releases, starting from 1.
+
+## Usage
+
+Dependencies and source paths come from the project's `deps.edn`:
+
+```clojure
+{:paths ["src"]
+ :deps {reagent/reagent {:mvn/version "2.0.1"}}}
+```
+
+```js
+// vite.config.mjs
+import cljs from 'clojurific/vite';
+
+export default {
+  plugins: [cljs({ outputDir: 'target/cljs' })],
+};
+```
+
+```html
+<!-- index.html -->
+<!doctype html>
+<div id="app"></div>
+<script type="module" src="/src/my/app.cljs"></script>
+```
+
+`npx vite` serves the page and hot reloads changed namespaces, `npx vite build`
+bundles it into `dist/`. JavaScript can import namespaces too:
+`import './my/app.cljs'`. The project's `package.json` needs `"type":
+"module"`.
+
+or with the command line:
+
+```sh
+npx cljf build '{:main my.app :output-dir "out"}'
+npx cljf -A:test watch @cljs.edn
+npx cljf classpath
+```
+
+`cljf` resolves `deps.edn` with tools.deps, adds the compiler, and removes
+stock ClojureScript (`org.clojure/clojurescript`) that libraries depend on.
+Dependencies are downloaded into `~/.m2/repository`, which the Clojure CLI
+shares, and the classpath is cached in `.cljf/` until `deps.edn` changes.
+
+## Java
+
+`cljf` uses `CLJF_JAVA`, `JAVA_HOME` or `java` on `PATH`. Without Java 17 or
+later it explains how to install one, or downloads Eclipse Temurin into its
+own cache:
+
+```sh
+npx cljf setup-java
+```
+
+`CLJF_INSTALL_JDK=1` does that without asking, i.e. in CI.
+
+## Configuration
+
+| Variable | |
+|---|---|
+| `CLJF_JAVA` | the `java` binary to use |
+| `CLJF_INSTALL_JDK=1` | install Java with `setup-java` when there's none |
+| `CLJF_MAVEN_REPO` | a Maven Central mirror to download the dependency resolver from; other dependencies use `:mvn/repos` |
+| `CLJF_CACHE_DIR` | where `setup-java` installs Java |
+
+See [ESM.md](https://github.com/WhimsicalCode/clojurific/blob/main/ESM.md) for
+compiler options, the Vite plugin's options, the REPL and how the launcher
+works.
+
+## License
+
+Eclipse Public License 1.0, like ClojureScript.

package/cljf/bootstrap.js

@@ -0,0 +1,69 @@
+// The resolver's classpath: tools.deps resolves the project's dependencies,
+// but can't download itself. Its jars are listed in resolver.lock.json with
+// their SHA-256, and downloaded into the local Maven repository, where the
+// Clojure CLI's are reused.
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LauncherError } from './errors.js';
+import { download, sha256File } from './files.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export const resolverDir = path.join(here, 'resolver');
+
+export function readLock(file = path.join(here, 'resolver.lock.json')) {
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+async function inParallel(items, limit, f) {
+  const queue = [...items];
+  const errors = [];
+  await Promise.all(Array.from({ length: Math.min(limit, queue.length) }, async () => {
+    for (let item = queue.shift(); item !== undefined; item = queue.shift()) {
+      try {
+        await f(item);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+  }));
+  return errors;
+}
+
+/**
+ * Downloads the lock's jars missing from localRepo (or not matching their
+ * SHA-256) from repository, Maven Central or CLJF_MAVEN_REPO. Returns the
+ * jars' paths.
+ */
+export async function bootstrapResolver({
+  lock = readLock(),
+  localRepo,
+  repository = lock.repository,
+  log = () => {},
+  fetch,
+}) {
+  const base = repository.replace(/\/+$/, '');
+  const missing = [];
+  await inParallel(lock.jars, 8, async jar => {
+    const file = path.join(localRepo, ...jar.path.split('/'));
+    const sha256 = await sha256File(file);
+    if (sha256 === jar.sha256) return;
+    if (sha256) log(`cljf: ${file} doesn't match resolver.lock.json, downloading it again`);
+    missing.push(jar);
+  });
+  if (missing.length) {
+    const mb = missing.reduce((sum, jar) => sum + jar.size, 0) / 1e6;
+    log(`cljf: downloading the dependency resolver, ${missing.length} jars (${mb.toFixed(1)} MB), from ${base}`);
+    const errors = await inParallel(missing, 8, jar =>
+      download(`${base}/${jar.path}`, path.join(localRepo, ...jar.path.split('/')), { sha256: jar.sha256, fetch }));
+    if (errors.length) {
+      throw new LauncherError(
+        `cljf: ${errors[0].message}${errors.length > 1 ? ` (and ${errors.length - 1} more)` : ''}\n` +
+        'Check the network connection and proxy settings. For a Maven Central mirror, set CLJF_MAVEN_REPO ' +
+        'to its URL; the project\'s own repositories come from :mvn/repos in deps.edn.',
+        { cause: errors[0] });
+    }
+  }
+  return lock.jars.map(jar => path.join(localRepo, ...jar.path.split('/')));
+}

package/cljf/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// cljf: builds and watches ClojureScript with the compiler (cljs.esm), on the
+// project's classpath resolved from its deps.edn. See usage below.
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { LauncherError } from './errors.js';
+import { classpath, compilerCommand, findJava, setupJava, version } from './launcher.js';
+
+const usage = `Usage: cljf [options] <command> [arguments]
+
+Commands:
+  build [options...]     compile once, cljs.esm's options: EDN maps, @file.edn
+                         and :profile keywords (defaults to :release)
+  watch [options...]     compile, then recompile on changes (defaults to :dev)
+  classpath              print the project's classpath
+  setup-java [version]   download Eclipse Temurin (the latest LTS by default)
+                         into cljf's cache, for machines without Java
+
+Options:
+  -A:alias1:alias2       apply deps.edn aliases, like the Clojure CLI's -A
+  --force                resolve the classpath again instead of using
+                         .cljf/cpcache
+  --version              print cljf's version
+
+The project is the current directory, with its deps.edn. Java 17 or later
+comes from CLJF_JAVA, JAVA_HOME, PATH or setup-java, in that order.
+
+  cljf build '{:main my.app :output-dir "out"}'
+  cljf -A:test watch @cljs.edn :test`;
+
+function parse(argv) {
+  const opts = { aliases: [], force: false };
+  let i = 0;
+  for (; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('-A')) opts.aliases.push(arg.length > 2 ? arg.slice(2) : argv[++i]);
+    else if (arg === '--force') opts.force = true;
+    else break;
+  }
+  return { opts, command: argv[i], args: argv.slice(i + 1) };
+}
+
+function run(command, args) {
+  const child = spawn(command, args, { stdio: 'inherit' });
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    // the terminal sends SIGINT to the JVM too, other signals are forwarded
+    process.on(signal, () => signal !== 'SIGINT' && child.kill(signal));
+  }
+  child.on('error', e => {
+    console.error(`cljf: ${command}: ${e.message}`);
+    process.exit(1);
+  });
+  child.on('exit', (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code);
+  });
+}
+
+async function main() {
+  const { opts, command, args } = parse(process.argv.slice(2));
+  const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY && !process.env.CI);
+  const log = line => process.stderr.write(`${line}\n`);
+  switch (command) {
+    case 'build':
+    case 'watch': {
+      const cmd = await compilerCommand({ ...opts, interactive, log });
+      run(cmd.command, [...cmd.args, '-m', 'cljs.esm', command, ...args]);
+      break;
+    }
+    case 'classpath': {
+      const cp = await classpath({ ...opts, java: findJava({ interactive, log }), log });
+      console.log(cp.classpath.join(path.delimiter));
+      break;
+    }
+    case 'setup-java': {
+      const { java } = await setupJava({ version: args[0], log });
+      console.log(java);
+      break;
+    }
+    case '--version':
+    case 'version':
+      console.log(version);
+      break;
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      console.log(usage);
+      break;
+    default:
+      console.error(`cljf: unknown command ${command}\n\n${usage}`);
+      process.exit(2);
+  }
+}
+
+main().catch(e => {
+  console.error(e instanceof LauncherError ? e.message : e);
+  process.exit(1);
+});

package/cljf/errors.js

@@ -0,0 +1,8 @@
+// An error whose message is meant for the user as it is: the CLI prints it
+// without a stack trace.
+export class LauncherError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'LauncherError';
+  }
+}

package/cljf/files.js

@@ -0,0 +1,96 @@
+// Files and directories shared by the launcher's parts.
+import { createHash, randomBytes } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+// The per-user cache, for the Java runtimes setup-java installs
+export function cacheDir(env = process.env, platform = process.platform) {
+  if (env.CLJF_CACHE_DIR) return path.resolve(env.CLJF_CACHE_DIR);
+  const home = os.homedir();
+  if (platform === 'darwin') return path.join(home, 'Library', 'Caches', 'cljf');
+  if (platform === 'win32') return path.join(env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'cljf');
+  return path.join(env.XDG_CACHE_HOME || path.join(home, '.cache'), 'cljf');
+}
+
+// The user's deps.edn, where tools.deps looks for it
+export function userDepsEdn(env = process.env) {
+  if (env.CLJ_CONFIG) return path.join(env.CLJ_CONFIG, 'deps.edn');
+  if (env.XDG_CONFIG_HOME) return path.join(env.XDG_CONFIG_HOME, 'clojure', 'deps.edn');
+  return path.join(os.homedir(), '.clojure', 'deps.edn');
+}
+
+async function readIfExists(file) {
+  try {
+    return await fs.readFile(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
+// The local Maven repository: :mvn/local-repo of the project's or the user's
+// deps.edn, as tools.deps uses it, or ~/.m2/repository
+export async function localRepository(project, env = process.env) {
+  for (const file of [path.join(project, 'deps.edn'), userDepsEdn(env)]) {
+    const match = (await readIfExists(file))?.match(/:mvn\/local-repo\s+"((?:[^"\\]|\\.)*)"/);
+    if (match) return path.resolve(project, JSON.parse(`"${match[1]}"`));
+  }
+  return path.join(os.homedir(), '.m2', 'repository');
+}
+
+export async function sha256File(file) {
+  const hash = createHash('sha256');
+  try {
+    await pipeline(createReadStream(file), hash);
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+  return hash.digest('hex');
+}
+
+// Writes content to file through a temporary file, so readers never see a
+// partial one
+export async function writeAtomically(file, content) {
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  await fs.writeFile(tmp, content);
+  await fs.rename(tmp, file);
+}
+
+// Downloads url to file, through a temporary file that's renamed once the
+// download is complete and its SHA-256 is sha256 (when given). Returns the
+// SHA-256.
+export async function download(url, file, { sha256, fetch = globalThis.fetch } = {}) {
+  let res;
+  try {
+    res = await fetch(url);
+  } catch (e) {
+    throw new Error(`downloading ${url} failed: ${e.cause?.message ?? e.message}`, { cause: e });
+  }
+  if (!res.ok) throw new Error(`downloading ${url} failed: HTTP ${res.status}`);
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.part`;
+  const hash = createHash('sha256');
+  try {
+    await pipeline(
+      Readable.fromWeb(res.body),
+      new Transform({ transform(chunk, _, done) { hash.update(chunk); done(null, chunk); } }),
+      createWriteStream(tmp),
+    );
+  } catch (e) {
+    await fs.rm(tmp, { force: true });
+    throw new Error(`downloading ${url} failed: ${e.cause?.message ?? e.message}`, { cause: e });
+  }
+  const actual = hash.digest('hex');
+  if (sha256 && actual !== sha256) {
+    await fs.rm(tmp, { force: true });
+    throw new Error(`${url} has SHA-256 ${actual}, expected ${sha256}`);
+  }
+  await fs.rename(tmp, file);
+  return actual;
+}