fallow
Version:
Codebase intelligence for TypeScript and JavaScript: health, complexity, duplication, architecture, styling drift, and unused code from one graph. CLI, LSP, and MCP server. Zero config for over 100 frameworks.
379 lines (347 loc) • 14.9 kB
JavaScript
// 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 os = require("node:os");
const {
getPlatformPackageCandidates,
resolveInstalledPlatformPackage,
} = require("./platform-package");
const { ensureVerified } = require("./lazy-verify");
const { isPreSigningVersion } = require("./verify-binary");
const SIMILAR_CODE_PROVIDER_ENV = "FALLOW_SIMILAR_CODE_PROVIDER";
function detectLibcFamily() {
if (process.platform !== "linux") return undefined;
try {
return require("detect-libc").familySync();
} catch {
// Unknown libc selects the musl package: musl binaries are statically
// linked and work on both glibc and musl.
return null;
}
}
function isVersionQuery(argv) {
// The root command answers all three version flags (--version, -V, and the
// TS/JS-toolchain-style -v), so the verified-status line must be appended for
// every one of them, not just --version / -V.
const tail = argv.slice(2);
if (tail.length === 0) return false;
return tail[0] === "--version" || tail[0] === "-V" || tail[0] === "-v";
}
// Signing status of the resolved CLI version, appended to the `verified:` line.
// Most informative on the `skipped` path: a fleet running with
// FALLOW_SKIP_BINARY_VERIFY can see whether the pinned version is even signable
// (pre-signing versions predate the 2.77.0 epoch and have no signature to
// verify). Best-effort: an unknown/unreadable version yields no annotation.
function describeSigning(version) {
if (typeof version !== "string" || version.length === 0) {
return "";
}
return isPreSigningVersion(version)
? `; fallow ${version} unsigned (predates 2.77.0)`
: `; fallow ${version} signed`;
}
function describeVerified(result, version) {
const status = describeVerifiedStatus(result);
return `${status}${describeSigning(version)}`;
}
function describeVerifiedStatus(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 libcFamily = detectLibcFamily();
const candidates = getPlatformPackageCandidates(process.platform, process.arch, libcFamily);
if (candidates.length === 0) {
process.stderr.write(`Unsupported platform: ${process.platform}-${process.arch}\n`);
process.exit(1);
}
const resolved = resolveInstalledPlatformPackage(candidates);
if (resolved === null) {
process.stderr.write(missingPlatformPackageMessage(candidates[0], libcFamily));
process.exit(1);
}
return { ...resolved, platformPkgDir: path.dirname(resolved.manifestPath) };
}
// npm installs a Linux platform package only for the libc that it detects at
// install time, so a tree installed for another libc, or from macOS or
// Windows without `--libc`, has no matching binary.
function missingPlatformPackageMessage(pkg, libcFamily) {
const hint = libcFamily
? ` This host uses ${libcFamily}. When node_modules was installed on another libc or OS, reinstall with \`npm install --os=linux --cpu=${process.arch} --libc=${libcFamily}\`.`
: "";
return `Could not find ${pkg}. Run 'npm install' to install the platform-specific binary.${hint}\n`;
}
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`,
);
}
// Call only after the child exits. Bun sets O_NONBLOCK on fd 1 when a script
// first reads `process.stdout`. The child inherits that open file description,
// so a large write from the binary fails with EAGAIN and the output is cut
// short (issue #3276).
function writeVerifiedLineIfVersionQuery(verifyResult, version) {
if (isVersionQuery(process.argv)) {
guardBrokenStdout();
process.stdout.write(`${describeVerified(verifyResult, version)}\n`);
}
}
// Exit code for a child failure caught from execFileSync. A signal death has
// status === null; map it to the shell convention 128 + signal number so CI
// gates see a crash, never a success.
function exitCodeForChildFailure(e) {
if (e.status !== null) return e.status;
const signalNumber = os.constants.signals[e.signal];
return signalNumber ? 128 + signalNumber : 1;
}
// Read the resolved CLI version from the platform package manifest (its version
// is released in lockstep with the CLI). Best-effort: never throws, so a
// missing/garbled manifest just omits the signing annotation on --version.
function readResolvedVersion(manifestPath) {
try {
const version = JSON.parse(fs.readFileSync(manifestPath, "utf8")).version;
return typeof version === "string" ? version : undefined;
} catch {
return undefined;
}
}
// `fallow` does not depend on its companions (`fallow-type-aware`,
// `fallow-similar-code`): a project installs one at the same version when it
// uses it. npm and Yarn hoist it next to `fallow`. pnpm links it only into the
// project node_modules, so a second lookup starts at the project root. That
// lookup accepts a companion only when it is in the same node_modules tree as
// the running `fallow` package, so a global `fallow` never runs a companion
// that a cloned project ships. Only an exact version match is accepted.
function resolveCompanionManifest(
packageName,
fallowVersion,
{
resolvePackage = require.resolve,
readFile = fs.readFileSync,
projectRoot = process.cwd(),
launcherDir = __dirname,
} = {},
) {
const local = matchingManifest(packageName, fallowVersion, resolvePackage, readFile, undefined);
if (local !== undefined) return local;
const project = matchingManifest(packageName, fallowVersion, resolvePackage, readFile, {
paths: [projectRoot],
});
if (project === undefined) return undefined;
const tree = installTree(launcherDir);
return tree !== null && tree === installTree(project) ? project : undefined;
}
function matchingManifest(packageName, fallowVersion, resolvePackage, readFile, options) {
try {
const manifestPath = resolvePackage(`${packageName}/package.json`, options);
const manifest = JSON.parse(readFile(manifestPath, "utf8"));
return manifest.version === fallowVersion ? manifestPath : undefined;
} catch {
return undefined;
}
}
// The outermost node_modules directory of a real path, or null outside one.
function installTree(file) {
let real;
try {
real = fs.realpathSync.native(file);
} catch {
return null;
}
const parts = real.split(path.sep);
const index = parts.indexOf("node_modules");
return index === -1 ? null : parts.slice(0, index + 1).join(path.sep);
}
function resolveTypeAwareCompanion(
fallowVersion,
resolvePackage = require.resolve,
readFile = fs.readFileSync,
projectRoot = process.cwd(),
launcherDir = __dirname,
) {
const manifestPath = resolveCompanionManifest("fallow-type-aware", fallowVersion, {
resolvePackage,
readFile,
projectRoot,
launcherDir,
});
if (manifestPath === undefined) return undefined;
const companion = path.join(path.dirname(manifestPath), "fallow-type-aware.mjs");
return fs.existsSync(companion) ? companion : undefined;
}
// The binary of the exact-version `fallow-similar-code` package, after its own
// resolver and verifier accept it (the Node API loader uses the same pair).
// The Rust code checks the signature again before it runs the binary.
function resolveSimilarCodeProvider(fallowVersion, options = {}) {
const { report = reportToStderr } = options;
const manifestPath = resolveCompanionManifest("fallow-similar-code", fallowVersion, options);
if (manifestPath === undefined) return undefined;
const scripts = path.join(path.dirname(manifestPath), "scripts");
try {
const { resolveBinaryArtifact, resolvePlatformPackage } = require(
path.join(scripts, "run-binary.js"),
);
const { verifyBinary } = require(path.join(scripts, "verify-binary.js"));
const artifact = resolveBinaryArtifact(resolvePlatformPackage());
const verification = verifyBinary(artifact);
if (verification.ok) return artifact.binaryPath;
report(`fallow: the similar-code companion failed verification: ${verification.message}\n`);
} catch (error) {
report(`fallow: the similar-code companion failed verification: ${error.message}\n`);
}
return undefined;
}
// Write to fd 2 directly: under Bun, `process.stderr` makes the pipes that the
// child inherits non-blocking (issue #3276). A failed write is ignored.
function reportToStderr(message) {
try {
fs.writeSync(2, message);
} catch {
// Best effort.
}
}
// Only these commands start the similar-code provider, so other runs skip the
// lookup and its digest check.
function usesSimilarCode(args) {
return args.includes("similar-code") || args.includes("mcp-server");
}
function typeAwareCommand(
companion,
{ platform = process.platform, execPath = process.execPath } = {},
) {
return platform === "win32"
? { binary: execPath, script: companion }
: { binary: companion, script: undefined };
}
function childEnvironment(
resolvedVersion,
resolveCompanion = resolveTypeAwareCompanion,
commandOptions,
{ args = [], resolveProvider = resolveSimilarCodeProvider } = {},
) {
let environment = process.env;
if (!process.env.FALLOW_TYPE_AWARE_BIN) {
const companion = resolveCompanion(resolvedVersion);
if (companion !== undefined) {
environment = typeAwareEnvironment(environment, typeAwareCommand(companion, commandOptions));
}
}
if (!process.env[SIMILAR_CODE_PROVIDER_ENV] && usesSimilarCode(args)) {
const provider = resolveProvider(resolvedVersion);
if (provider !== undefined) {
environment = { ...environment, [SIMILAR_CODE_PROVIDER_ENV]: provider };
}
}
return environment;
}
function typeAwareEnvironment(base, command) {
const environment = {
...base,
FALLOW_TYPE_AWARE_BIN: command.binary,
// Marks the wiring as launcher-provided node_modules resolution so
// `type-aware status` does not report it as a user-set override.
FALLOW_TYPE_AWARE_BIN_SOURCE: "npm-wrapper",
};
if (command.script) {
environment.FALLOW_TYPE_AWARE_SCRIPT = command.script;
} else {
delete environment.FALLOW_TYPE_AWARE_SCRIPT;
}
return environment;
}
// 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;
});
}
// Run the resolved platform binary. `options.prependArgs` (default none) is a
// list of leading arguments inserted before the process argv, used by the
// `fallow-lsp` / `fallow-mcp` launcher shims to spawn the multicall binary as
// `fallow lsp-server` / `fallow mcp-server`. Because the platform packages ship
// a single `fallow` binary, those shims pass `binaryBaseName = "fallow"` and
// the subcommand via `prependArgs`; signal, exit-code, and version-line
// handling stay identical to a bare `fallow` invocation.
function runBinary(binaryBaseName, options = {}) {
const prependArgs = Array.isArray(options.prependArgs) ? options.prependArgs : [];
// Do not read `process.stdout` or write to `process.stderr` before the child
// exits: under Bun that makes the inherited pipes non-blocking for the child.
const { pkg, manifestPath, platformPkgDir } = resolvePlatformPaths();
const resolvedVersion = readResolvedVersion(manifestPath);
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, [...prependArgs, ...process.argv.slice(2)], {
stdio: "inherit",
env: childEnvironment(resolvedVersion, undefined, undefined, {
args: [...prependArgs, ...process.argv.slice(2)],
}),
});
} catch (e) {
if (e.status === undefined) throw e;
if (e.status === null) {
process.stderr.write(`fallow binary terminated by signal ${e.signal ?? "unknown"}\n`);
}
// 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, resolvedVersion);
process.exit(exitCodeForChildFailure(e));
}
writeVerifiedLineIfVersionQuery(verifyResult, resolvedVersion);
}
module.exports = {
runBinary,
describeVerified, // test-only
isVersionQuery, // test-only
guardBrokenStdout, // test-only
exitCodeForChildFailure, // test-only
missingPlatformPackageMessage, // test-only
resolveTypeAwareCompanion, // test-only
resolveSimilarCodeProvider, // test-only
childEnvironment, // test-only
};