@symbiosis-lab/moss 0.11.1 → 0.11.5

package/README.md

@@ -54,6 +54,24 @@ The wrapper downloads the moss version matching its own package version;
 they are released in lockstep. `MOSS_VERSION_OVERRIDE=v0.11.1` forces a
 specific release (ops/testing escape hatch).
 
+## Controlling the download
+
+| Variable | Effect |
+|---|---|
+| `MOSS_SKIP_BINARY_DOWNLOAD=1` | Install the wrapper without fetching a binary. `moss` then fetches it on first run. |
+| `MOSS_BINARY_PATH=/path/to/moss` | Run that binary instead of the vendored one, and skip the download entirely. |
+| `MOSS_FORCE_BINARY_DOWNLOAD=1` | Download even where the wrapper would otherwise skip. |
+
+Each also reads from `.npmrc` under its lowercased name (`moss_skip_binary_download=true`),
+because npm passes config keys to lifecycle scripts as `npm_config_*`.
+
+**Inside the moss repo the download is skipped automatically.** A checkout is
+not an install: `packages/moss` sits in the workspace rather than under
+`node_modules`, so `pnpm install` at the repo root would otherwise pull a
+release binary that no moss developer wants — they build from source. Point
+`MOSS_BINARY_PATH` at `src-tauri/target/release/moss` to exercise the wrapper
+against your own build.
+
 ## License
 
 The wrapper code in this package is MIT (see LICENSE). The moss binary it

package/bin/moss.js

@@ -7,16 +7,26 @@
 
 const fs = require('node:fs');
 const { spawnSync } = require('node:child_process');
-const { fetchBinary, vendorBinary } = require('../lib/fetch.js');
+const { fetchBinary, resolveBinary } = require('../lib/fetch.js');
 
 async function main() {
-  if (!fs.existsSync(vendorBinary)) {
+  const binary = resolveBinary();
+
+  if (!fs.existsSync(binary)) {
+    // An explicit MOSS_BINARY_PATH that isn't there is a mistake to report,
+    // not a cue to download a release binary over the top of the developer's
+    // intent.
+    if (process.env.MOSS_BINARY_PATH) {
+      throw new Error(
+        `moss-npm: MOSS_BINARY_PATH is set to ${binary}, but no file is there.`
+      );
+    }
     await fetchBinary();
   }
 
   // stderr is piped so a loader failure can be recognized, then replayed
   // verbatim. stdin/stdout stay inherited for interactive use.
-  const result = spawnSync(vendorBinary, process.argv.slice(2), {
+  const result = spawnSync(binary, process.argv.slice(2), {
     stdio: ['inherit', 'inherit', 'pipe'],
   });
 

package/install.js

@@ -1,12 +1,21 @@
 // postinstall: download the moss binary for this platform.
 //
-// Never fails the npm install — an offline machine or a proxy hiccup should
-// not break an unrelated `npm install`. The bin shim (bin/moss.js) retries
-// the download lazily on first run, so exiting 0 here loses nothing.
+// Two things it will not do. It never fails the npm install — an offline
+// machine or a proxy hiccup should not break an unrelated `npm install`, and
+// the bin shim (bin/moss.js) retries the download lazily on first run, so
+// exiting 0 here loses nothing. And it does not download at all when nobody
+// asked for a release binary: inside the moss repo itself, or when the
+// developer has pointed MOSS_BINARY_PATH at their own build.
 
 'use strict';
 
-const { fetchBinary } = require('./lib/fetch.js');
+const { fetchBinary, skipDownloadReason } = require('./lib/fetch.js');
+
+const skip = skipDownloadReason();
+if (skip) {
+  console.log(`moss-npm: skipping the binary download — ${skip}.`);
+  process.exit(0);
+}
 
 fetchBinary().catch((err) => {
   console.warn(`\nmoss-npm: could not download the moss binary now:\n  ${err.message}`);

package/lib/fetch.js

@@ -16,6 +16,51 @@ const RELEASES = 'https://github.com/Symbiosis-Lab/moss-releases/releases/downlo
 const packageRoot = path.join(__dirname, '..');
 const vendorBinary = path.join(packageRoot, 'vendor', 'moss');
 
+// npm and pnpm expose every `.npmrc` key to lifecycle scripts as `npm_config_<key>`,
+// so one lookup covers both the environment variable and the config file. This is
+// the mechanism Cypress documents for `CYPRESS_INSTALL_BINARY` and puppeteer for
+// `PUPPETEER_SKIP_DOWNLOAD`.
+function flag(name) {
+  const value =
+    process.env[name] ?? process.env[`npm_config_${name.toLowerCase()}`];
+  if (value === undefined || value === '') return false;
+  return !/^(0|false|no)$/i.test(value);
+}
+
+// True when this copy of the package was installed as somebody's dependency.
+// Every package manager unpacks a published tarball into a directory with a
+// `node_modules` segment in its path — npm and pnpm's store both, and Yarn PnP's
+// unplugged cache. A checkout of the moss repo has no such segment, so the
+// absence of one means we are running from source, not from an install.
+function isInstalledAsDependency() {
+  return packageRoot.split(path.sep).includes('node_modules');
+}
+
+/**
+ * Why the postinstall download should not run, or null to go ahead.
+ *
+ * Returns a reason suitable for printing — the caller decides whether that is
+ * a log line or an error.
+ */
+function skipDownloadReason() {
+  if (flag('MOSS_FORCE_BINARY_DOWNLOAD')) return null;
+  if (flag('MOSS_SKIP_BINARY_DOWNLOAD')) return 'MOSS_SKIP_BINARY_DOWNLOAD is set';
+  if (process.env.MOSS_BINARY_PATH) {
+    return `MOSS_BINARY_PATH points at ${process.env.MOSS_BINARY_PATH}`;
+  }
+  if (!isInstalledAsDependency()) {
+    return 'running from a source checkout, not an install — build moss yourself, ' +
+      'or set MOSS_FORCE_BINARY_DOWNLOAD=1 to fetch the release binary anyway';
+  }
+  return null;
+}
+
+// Which binary `moss` should execute. `MOSS_BINARY_PATH` wins so a developer can
+// point the wrapper at a locally built moss (esbuild's `ESBUILD_BINARY_PATH`).
+function resolveBinary() {
+  return process.env.MOSS_BINARY_PATH || vendorBinary;
+}
+
 function resolveVersion() {
   const override = process.env.MOSS_VERSION_OVERRIDE;
   if (override) return override.replace(/^v/, '');
@@ -95,4 +140,11 @@ async function fetchBinary() {
   return vendorBinary;
 }
 
-module.exports = { fetchBinary, vendorBinary, resolveAsset, resolveVersion };
+module.exports = {
+  fetchBinary,
+  vendorBinary,
+  resolveAsset,
+  resolveBinary,
+  resolveVersion,
+  skipDownloadReason,
+};

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@symbiosis-lab/moss",
-  "version": "0.11.1",
-  "description": "moss on your PATH \u2014 npm wrapper that installs the moss CLI binary from moss-releases",
+  "version": "0.11.5",
+  "description": "moss on your PATH — npm wrapper that installs the moss CLI binary from moss-releases",
   "bin": {
     "moss": "bin/moss.js"
   },
   "scripts": {
     "postinstall": "node install.js",
+    "test": "node --test test/*.test.js",
     "test:smoke": "node bin/moss.js --version"
   },
   "files": [