fallow 2.81.0 → 2.83.0

package/scripts/run-binary.js

@@ -0,0 +1,141 @@
+// Shared launcher used by bin/fallow, bin/fallow-lsp, and bin/fallow-mcp.
+//
+// 1. Resolves the platform package for the current process (platform + arch + libc).
+// 2. Runs ensureVerified (Ed25519 + SHA-256 lazy first-run verify).
+// 3. Execs the platform binary.
+// 4. For `<bin> --version`, appends a `verified: ...` status line to stdout
+//    so procurement teams have a single command that surfaces the integrity
+//    posture (replaces the install-time confirmation message removed when
+//    postinstall verification was retired for RFC 868 readiness).
+
+const { execFileSync } = require("node:child_process");
+const path = require("node:path");
+const fs = require("node:fs");
+
+const { getPlatformPackage } = require("./platform-package");
+const { ensureVerified } = require("./lazy-verify");
+
+function resolvePlatformPackageName() {
+  if (process.platform !== "linux") {
+    return getPlatformPackage(process.platform, process.arch);
+  }
+  try {
+    const { familySync } = require("detect-libc");
+    return getPlatformPackage(process.platform, process.arch, familySync());
+  } catch {
+    // musl binaries are statically linked and work on both glibc and musl
+    return getPlatformPackage(process.platform, process.arch, "musl");
+  }
+}
+
+function isVersionQuery(argv) {
+  // clap registers both --version and -V on the root command.
+  const tail = argv.slice(2);
+  if (tail.length === 0) return false;
+  return tail[0] === "--version" || tail[0] === "-V";
+}
+
+function describeVerified(result) {
+  if (result.skipped) {
+    return `verified: skipped (${result.reason})`;
+  }
+  if (result.ok) {
+    if (result.cached) {
+      return `verified: yes (cache hit at ${result.sentinelPath})`;
+    }
+    if (result.sentinelPath) {
+      return `verified: yes (sentinel ${result.sentinelPath})`;
+    }
+    return "verified: yes (sentinel not persisted)";
+  }
+  return `verified: no (${result.code})`;
+}
+
+// Resolve the platform package directory + manifest path, or print an
+// actionable error and exit. Keeps `runBinary` a flat top-level sequence.
+function resolvePlatformPaths() {
+  const pkg = resolvePlatformPackageName();
+  if (!pkg) {
+    process.stderr.write(`Unsupported platform: ${process.platform}-${process.arch}\n`);
+    process.exit(1);
+  }
+  try {
+    const manifestPath = require.resolve(`${pkg}/package.json`);
+    return { pkg, manifestPath, platformPkgDir: path.dirname(manifestPath) };
+  } catch {
+    process.stderr.write(
+      `Could not find ${pkg}. Run 'npm install' to install the platform-specific binary.\n`,
+    );
+    process.exit(1);
+  }
+}
+
+function printVerifyError(verifyResult) {
+  const where = verifyResult.binary ? ` ${verifyResult.binary}` : "";
+  process.stderr.write(
+    `fallow: binary verification failed${where} (${verifyResult.code}): ${verifyResult.message}\n` +
+      `See https://github.com/fallow-rs/fallow/blob/main/SECURITY.md for the trust model. ` +
+      `Set FALLOW_SKIP_BINARY_VERIFY=1 only when you deliberately replace the published binary.\n`,
+  );
+}
+
+function writeVerifiedLineIfVersionQuery(verifyResult) {
+  if (isVersionQuery(process.argv)) {
+    process.stdout.write(`${describeVerified(verifyResult)}\n`);
+  }
+}
+
+// Swallow EPIPE on stdout. When fallow's output is piped into a reader that
+// closes early (e.g. `fallow --version | head`), the trailing `verified:`
+// status line would otherwise surface as an unhandled EPIPE 'error' event and
+// dump a Node stack trace. EPIPE arrives as an async 'error' event on the
+// stdout stream, not as a throw, so a try/catch around the write cannot catch
+// it. The child binary's primary output is already written via inherited
+// stdio; the status line is best-effort, so exit cleanly once the reader is
+// gone. Scoped to stdout so a genuine error write to stderr still sets exit 1.
+function guardBrokenStdout() {
+  process.stdout.on("error", (err) => {
+    if (err && err.code === "EPIPE") {
+      process.exit(0);
+    }
+    throw err;
+  });
+}
+
+function runBinary(binaryBaseName) {
+  guardBrokenStdout();
+  const { pkg, manifestPath, platformPkgDir } = resolvePlatformPaths();
+
+  const binaryName = process.platform === "win32" ? `${binaryBaseName}.exe` : binaryBaseName;
+  const binaryPath = path.join(platformPkgDir, binaryName);
+  if (!fs.existsSync(binaryPath)) {
+    process.stderr.write(`Binary not found at ${binaryPath}\n`);
+    process.exit(1);
+  }
+
+  // Lazy first-run verify. Errors are user-facing.
+  const verifyResult = ensureVerified({ platformPkgDir, packageName: pkg, manifestPath });
+  if (!verifyResult.ok) {
+    printVerifyError(verifyResult);
+    process.exit(1);
+  }
+
+  try {
+    execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+  } catch (e) {
+    if (e.status === undefined) throw e;
+    // Child has already written its --version line via inherited stdio;
+    // append the verified line here only on a clean exit.
+    if (e.status === 0) writeVerifiedLineIfVersionQuery(verifyResult);
+    process.exit(e.status);
+  }
+
+  writeVerifiedLineIfVersionQuery(verifyResult);
+}
+
+module.exports = {
+  runBinary,
+  describeVerified, // test-only
+  isVersionQuery, // test-only
+  guardBrokenStdout, // test-only
+};

package/scripts/run-binary.test.js

@@ -0,0 +1,39 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const RUN_BINARY = path.join(__dirname, "run-binary.js");
+
+// Run a child that installs guardBrokenStdout, then emits a synthetic stdout
+// 'error' with the given code. Node delivers a broken-pipe failure as exactly
+// this event ("Emitted 'error' event on Socket instance"), so emitting it is a
+// faithful reproduction of `fallow --version | head` without needing a live
+// pipe or an installed @fallow-cli platform package. Requiring run-binary.js
+// has no side effects beyond defining functions, so no binary is resolved.
+function runGuardChild(errorCode) {
+  const script =
+    `const { guardBrokenStdout } = require(${JSON.stringify(RUN_BINARY)});` +
+    `guardBrokenStdout();` +
+    `process.stdout.emit("error", Object.assign(new Error("write ${errorCode}"), { code: "${errorCode}" }));` +
+    // Reached only if the guard neither exited (EPIPE) nor rethrew (other).
+    `process.exit(42);`;
+  return spawnSync(process.execPath, ["-e", script], { encoding: "utf8" });
+}
+
+test("guardBrokenStdout swallows EPIPE on stdout and exits 0", () => {
+  const res = runGuardChild("EPIPE");
+  assert.equal(res.status, 0, "EPIPE on stdout should exit 0 cleanly, not crash");
+  assert.doesNotMatch(res.stderr, /EPIPE/, "no EPIPE stack trace on stderr");
+});
+
+test("guardBrokenStdout rethrows non-EPIPE stdout errors (exit 1)", () => {
+  const res = runGuardChild("ENOSPC");
+  assert.equal(res.status, 1, "a non-EPIPE stdout error must surface, not be swallowed");
+  // Match the thrown error's header ("Error: write ENOSPC"), not just the
+  // message substring: a missing-guard TypeError would leak the script source
+  // (`new Error("write ENOSPC")`) into its code frame and match a looser regex,
+  // masking a regression. The colon-space header only appears on a real rethrow.
+  assert.match(res.stderr, /Error: write ENOSPC/, "the rethrown error reaches stderr");
+  assert.doesNotMatch(res.stderr, /is not a function/, "guard must be present, not absent");
+});

package/scripts/sentinel-path.js

@@ -0,0 +1,165 @@
+// Cascading cache-dir resolution for the lazy-verify sentinel.
+//
+// Preference order:
+//   1. <platform-pkg-dir>/.fallow-verified
+//   2. $FALLOW_VERIFY_CACHE_DIR/<package-id>.json
+//   3. $XDG_CACHE_HOME/fallow/sentinels/<package-id>.json   (Linux/macOS)
+//      or %LOCALAPPDATA%\fallow\sentinels\<package-id>.json (Windows)
+//      or ~/.cache/fallow/sentinels/<package-id>.json       (POSIX fallback)
+//   4. Every location read-only: returns { path: null, location: 'none', writable: false }.
+//      Callers run verify on every invocation and surface FALLOW_SKIP_BINARY_VERIFY=1 as the escape.
+//
+// Refs RFC 868 (npm/cli#9360). See .plans/rfc-868-lazy-binary-verify.md.
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const SENTINEL_FILENAME = ".fallow-verified";
+
+// Returns true when the directory exists and the current process can create
+// a file in it. Tries an atomic O_CREAT|O_EXCL write so we never disturb an
+// existing sentinel during the writability probe. Falls back to fs.accessSync
+// when mkdtempSync fails for non-permission reasons.
+function isWritable(dir) {
+  if (typeof dir !== "string" || dir.length === 0) {
+    return false;
+  }
+  let stat;
+  try {
+    stat = fs.statSync(dir);
+  } catch {
+    return false;
+  }
+  if (!stat.isDirectory()) {
+    return false;
+  }
+  // Probe by creating a unique zero-byte file and deleting it. Cross-platform
+  // and tolerant of pnpm/yarn/bun store layouts where the dir is real but the
+  // package manager owns its contents.
+  const probe = path.join(dir, `.fallow-verify-probe-${process.pid}-${Date.now()}`);
+  let fd;
+  try {
+    fd = fs.openSync(probe, "wx");
+    fs.closeSync(fd);
+    fs.unlinkSync(probe);
+    return true;
+  } catch {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {}
+    }
+    return false;
+  }
+}
+
+function ensureDirExists(dir) {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function xdgCacheRoot(env, homeDir, platformId) {
+  if (platformId === "win32") {
+    return env.LOCALAPPDATA && env.LOCALAPPDATA.length > 0 ? env.LOCALAPPDATA : null;
+  }
+  if (env.XDG_CACHE_HOME && env.XDG_CACHE_HOME.length > 0) {
+    return env.XDG_CACHE_HOME;
+  }
+  return homeDir ? path.join(homeDir, ".cache") : null;
+}
+
+// Convert an npm package name like "@fallow-cli/darwin-arm64" into a stable
+// filesystem-safe identifier used as the sentinel's file basename when the
+// sentinel lives outside the platform package directory.
+function packageIdToFilename(packageName) {
+  if (typeof packageName !== "string" || packageName.length === 0) {
+    return "unknown.json";
+  }
+  return `${packageName.replace(/^@/, "").replace(/[/\\]/g, "__")}.json`;
+}
+
+// Each cascade step is a small helper that returns a resolved sentinel
+// descriptor or null. Resolving in this shape keeps `resolveSentinelPath`
+// itself a flat for-loop so cyclomatic complexity stays low.
+
+function tryPlatformPkgDir(platformPkgDir, writableProbe) {
+  if (typeof platformPkgDir !== "string" || platformPkgDir.length === 0) {
+    return null;
+  }
+  if (!writableProbe(platformPkgDir)) {
+    return null;
+  }
+  return {
+    path: path.join(platformPkgDir, SENTINEL_FILENAME),
+    location: "platform-pkg",
+    writable: true,
+  };
+}
+
+function tryCacheDirEnv(env, filename, ensureDir, writableProbe) {
+  const dir = env.FALLOW_VERIFY_CACHE_DIR;
+  if (!dir || dir.length === 0) return null;
+  if (!ensureDir(dir) || !writableProbe(dir)) return null;
+  return { path: path.join(dir, filename), location: "cache-dir-env", writable: true };
+}
+
+function xdgLocationLabel(env, platformId) {
+  if (platformId === "win32") return "localappdata";
+  return env.XDG_CACHE_HOME ? "xdg" : "home-cache";
+}
+
+function tryXdgFallback(env, homeDir, platformId, filename, ensureDir, writableProbe) {
+  const root = xdgCacheRoot(env, homeDir, platformId);
+  if (!root) return null;
+  const dir = path.join(root, "fallow", "sentinels");
+  if (!ensureDir(dir) || !writableProbe(dir)) return null;
+  return {
+    path: path.join(dir, filename),
+    location: xdgLocationLabel(env, platformId),
+    writable: true,
+  };
+}
+
+// Resolve the sentinel path according to the cascade documented above.
+// Dependency-inject env / homedir / platform / fsProbe so the unit tests can
+// exercise every branch without touching the real filesystem state.
+//
+// Returns: {
+//   path: string | null,        // null means "no writable cache location"
+//   location: 'platform-pkg' | 'cache-dir-env' | 'xdg' | 'localappdata' | 'home-cache' | 'none',
+//   writable: boolean,
+// }
+function resolveSentinelPath(options) {
+  const opts = options || {};
+  const env = opts.env || process.env;
+  // Using `in` so an explicit `homedir: undefined` opts out of the os.homedir()
+  // fallback (tests rely on this to exercise the "no cache home" branch).
+  const homeDir = "homedir" in opts ? opts.homedir : os.homedir();
+  const platformId = opts.platform || process.platform;
+  const writableProbe = typeof opts.isWritable === "function" ? opts.isWritable : isWritable;
+  const ensureDir = typeof opts.ensureDir === "function" ? opts.ensureDir : ensureDirExists;
+  const filename = packageIdToFilename(opts.packageName);
+
+  return (
+    tryPlatformPkgDir(opts.platformPkgDir, writableProbe) ||
+    tryCacheDirEnv(env, filename, ensureDir, writableProbe) ||
+    tryXdgFallback(env, homeDir, platformId, filename, ensureDir, writableProbe) || {
+      path: null,
+      location: "none",
+      writable: false,
+    }
+  );
+}
+
+module.exports = {
+  SENTINEL_FILENAME,
+  packageIdToFilename,
+  resolveSentinelPath,
+  // exported for tests
+  _isWritable: isWritable,
+};

package/scripts/sentinel-path.test.js

@@ -0,0 +1,236 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const {
+  SENTINEL_FILENAME,
+  packageIdToFilename,
+  resolveSentinelPath,
+  _isWritable,
+} = require("./sentinel-path");
+
+function mkTmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "fallow-sentinel-path-"));
+}
+
+function cleanup(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+test("packageIdToFilename normalises scoped package names", () => {
+  assert.equal(packageIdToFilename("@fallow-cli/darwin-arm64"), "fallow-cli__darwin-arm64.json");
+  assert.equal(packageIdToFilename("@fallow-cli/linux-x64-gnu"), "fallow-cli__linux-x64-gnu.json");
+  assert.equal(packageIdToFilename("fallow"), "fallow.json");
+  assert.equal(packageIdToFilename(""), "unknown.json");
+  assert.equal(packageIdToFilename(undefined), "unknown.json");
+});
+
+test("packageIdToFilename strips backslashes too (Windows scoped paths)", () => {
+  assert.equal(packageIdToFilename("@scope\\name"), "scope__name.json");
+});
+
+test("isWritable returns true for a writable tmpdir", () => {
+  const dir = mkTmp();
+  try {
+    assert.equal(_isWritable(dir), true);
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test("isWritable returns false for a non-existent path", () => {
+  assert.equal(_isWritable("/this/path/does/not/exist/probably"), false);
+  assert.equal(_isWritable(""), false);
+  assert.equal(_isWritable(undefined), false);
+});
+
+test("isWritable returns false when the target is a file, not a dir", () => {
+  const dir = mkTmp();
+  try {
+    const filePath = path.join(dir, "a-file");
+    fs.writeFileSync(filePath, "x");
+    assert.equal(_isWritable(filePath), false);
+  } finally {
+    cleanup(dir);
+  }
+});
+
+test("resolveSentinelPath prefers the platform pkg dir when writable", () => {
+  const platformPkgDir = mkTmp();
+  try {
+    const result = resolveSentinelPath({
+      platformPkgDir,
+      packageName: "@fallow-cli/darwin-arm64",
+      env: {},
+    });
+    assert.equal(result.location, "platform-pkg");
+    assert.equal(result.writable, true);
+    assert.equal(result.path, path.join(platformPkgDir, SENTINEL_FILENAME));
+  } finally {
+    cleanup(platformPkgDir);
+  }
+});
+
+test("resolveSentinelPath falls back to FALLOW_VERIFY_CACHE_DIR when platform pkg dir is non-writable", () => {
+  const cacheDir = mkTmp();
+  try {
+    const result = resolveSentinelPath({
+      platformPkgDir: "/dev/null/not-a-dir",
+      packageName: "@fallow-cli/darwin-arm64",
+      env: { FALLOW_VERIFY_CACHE_DIR: cacheDir },
+    });
+    assert.equal(result.location, "cache-dir-env");
+    assert.equal(result.writable, true);
+    assert.equal(result.path, path.join(cacheDir, "fallow-cli__darwin-arm64.json"));
+  } finally {
+    cleanup(cacheDir);
+  }
+});
+
+test("resolveSentinelPath honors FALLOW_VERIFY_CACHE_DIR even when platform pkg dir IS writable", () => {
+  // Per the cascade documented in the source, the platform pkg dir wins when
+  // writable. The cache-dir env is the FALLBACK for when the platform dir is
+  // read-only. We pass a non-existent platform dir to force the fallback.
+  const cacheDir = mkTmp();
+  try {
+    const result = resolveSentinelPath({
+      platformPkgDir: undefined,
+      packageName: "@fallow-cli/linux-x64-gnu",
+      env: { FALLOW_VERIFY_CACHE_DIR: cacheDir },
+    });
+    assert.equal(result.location, "cache-dir-env");
+    assert.equal(result.path, path.join(cacheDir, "fallow-cli__linux-x64-gnu.json"));
+  } finally {
+    cleanup(cacheDir);
+  }
+});
+
+test("resolveSentinelPath falls back to XDG_CACHE_HOME on Linux/macOS", () => {
+  const homeDir = mkTmp();
+  const xdg = path.join(homeDir, "xdg-cache");
+  fs.mkdirSync(xdg);
+  try {
+    const result = resolveSentinelPath({
+      platformPkgDir: undefined,
+      packageName: "@fallow-cli/darwin-arm64",
+      env: { XDG_CACHE_HOME: xdg },
+      homedir: homeDir,
+      platform: "darwin",
+    });
+    assert.equal(result.location, "xdg");
+    assert.equal(result.writable, true);
+    assert.equal(
+      result.path,
+      path.join(xdg, "fallow", "sentinels", "fallow-cli__darwin-arm64.json"),
+    );
+    // The fallow/sentinels/ subdir must have been created.
+    assert.equal(fs.existsSync(path.join(xdg, "fallow", "sentinels")), true);
+  } finally {
+    cleanup(homeDir);
+  }
+});
+
+test("resolveSentinelPath falls back to ~/.cache on Linux/macOS when XDG_CACHE_HOME is unset", () => {
+  const homeDir = mkTmp();
+  try {
+    const result = resolveSentinelPath({
+      platformPkgDir: undefined,
+      packageName: "@fallow-cli/linux-x64-gnu",
+      env: {},
+      homedir: homeDir,
+      platform: "linux",
+    });
+    assert.equal(result.location, "home-cache");
+    assert.equal(
+      result.path,
+      path.join(homeDir, ".cache", "fallow", "sentinels", "fallow-cli__linux-x64-gnu.json"),
+    );
+  } finally {
+    cleanup(homeDir);
+  }
+});
+
+test("resolveSentinelPath uses LOCALAPPDATA on Windows", () => {
+  const localAppData = mkTmp();
+  try {
+    const result = resolveSentinelPath({
+      platformPkgDir: undefined,
+      packageName: "@fallow-cli/win32-x64-msvc",
+      env: { LOCALAPPDATA: localAppData },
+      homedir: "/c/Users/test",
+      platform: "win32",
+    });
+    assert.equal(result.location, "localappdata");
+    assert.equal(result.writable, true);
+    assert.equal(
+      result.path,
+      path.join(localAppData, "fallow", "sentinels", "fallow-cli__win32-x64-msvc.json"),
+    );
+  } finally {
+    cleanup(localAppData);
+  }
+});
+
+test("resolveSentinelPath returns no path when every location is non-writable", () => {
+  const result = resolveSentinelPath({
+    platformPkgDir: undefined,
+    packageName: "@fallow-cli/darwin-arm64",
+    env: {},
+    homedir: undefined,
+    platform: "darwin",
+  });
+  assert.equal(result.path, null);
+  assert.equal(result.location, "none");
+  assert.equal(result.writable, false);
+});
+
+test("resolveSentinelPath returns no path on Windows without LOCALAPPDATA", () => {
+  const result = resolveSentinelPath({
+    platformPkgDir: undefined,
+    packageName: "@fallow-cli/win32-x64-msvc",
+    env: {},
+    homedir: undefined,
+    platform: "win32",
+  });
+  assert.equal(result.path, null);
+  assert.equal(result.location, "none");
+});
+
+test("resolveSentinelPath honors injected isWritable + ensureDir for full test isolation", () => {
+  const calls = [];
+  const result = resolveSentinelPath({
+    platformPkgDir: "/synthetic/pkg-dir",
+    packageName: "@fallow-cli/darwin-arm64",
+    env: {},
+    isWritable: (dir) => {
+      calls.push(["isWritable", dir]);
+      return dir === "/synthetic/pkg-dir";
+    },
+    ensureDir: (dir) => {
+      calls.push(["ensureDir", dir]);
+      return true;
+    },
+  });
+  assert.equal(result.location, "platform-pkg");
+  assert.deepEqual(calls, [["isWritable", "/synthetic/pkg-dir"]]);
+});
+
+test("resolveSentinelPath skips cache-dir-env when ensureDir fails for it", () => {
+  // FALLOW_VERIFY_CACHE_DIR points at a non-creatable path, XDG points at a
+  // creatable one. Confirm the resolver moves past the env override.
+  const homeDir = mkTmp();
+  try {
+    const result = resolveSentinelPath({
+      platformPkgDir: undefined,
+      packageName: "@fallow-cli/darwin-arm64",
+      env: { FALLOW_VERIFY_CACHE_DIR: "/dev/null/inside/a/file" },
+      homedir: homeDir,
+      platform: "darwin",
+    });
+    assert.equal(result.location, "home-cache");
+  } finally {
+    cleanup(homeDir);
+  }
+});