fallow 2.88.2 → 2.88.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.88.2",
+  "version": "2.88.3",
   "description": "Deterministic codebase intelligence for TypeScript and JavaScript. Quality, risk, architecture, dependencies, duplication, and safe cleanup evidence for humans, CI, and agents. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 96 framework plugins.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.88.2",
-    "@fallow-cli/darwin-x64": "2.88.2",
-    "@fallow-cli/linux-x64-gnu": "2.88.2",
-    "@fallow-cli/linux-arm64-gnu": "2.88.2",
-    "@fallow-cli/linux-x64-musl": "2.88.2",
-    "@fallow-cli/linux-arm64-musl": "2.88.2",
-    "@fallow-cli/win32-arm64-msvc": "2.88.2",
-    "@fallow-cli/win32-x64-msvc": "2.88.2"
+    "@fallow-cli/darwin-arm64": "2.88.3",
+    "@fallow-cli/darwin-x64": "2.88.3",
+    "@fallow-cli/linux-x64-gnu": "2.88.3",
+    "@fallow-cli/linux-arm64-gnu": "2.88.3",
+    "@fallow-cli/linux-x64-musl": "2.88.3",
+    "@fallow-cli/linux-arm64-musl": "2.88.3",
+    "@fallow-cli/win32-arm64-msvc": "2.88.3",
+    "@fallow-cli/win32-x64-msvc": "2.88.3"
   }
 }

package/scripts/run-binary.js

@@ -14,6 +14,7 @@ const fs = require("node:fs");
 
 const { getPlatformPackage } = require("./platform-package");
 const { ensureVerified } = require("./lazy-verify");
+const { isPreSigningVersion } = require("./verify-binary");
 
 function resolvePlatformPackageName() {
   if (process.platform !== "linux") {
@@ -29,13 +30,34 @@ function resolvePlatformPackageName() {
 }
 
 function isVersionQuery(argv) {
-  // clap registers both --version and -V on the root command.
+  // 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";
+  return tail[0] === "--version" || tail[0] === "-V" || tail[0] === "-v";
 }
 
-function describeVerified(result) {
+// 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})`;
   }
@@ -79,9 +101,21 @@ function printVerifyError(verifyResult) {
   );
 }
 
-function writeVerifiedLineIfVersionQuery(verifyResult) {
+function writeVerifiedLineIfVersionQuery(verifyResult, version) {
   if (isVersionQuery(process.argv)) {
-    process.stdout.write(`${describeVerified(verifyResult)}\n`);
+    process.stdout.write(`${describeVerified(verifyResult, version)}\n`);
+  }
+}
+
+// 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;
   }
 }
 
@@ -105,6 +139,7 @@ function guardBrokenStdout() {
 function runBinary(binaryBaseName) {
   guardBrokenStdout();
   const { pkg, manifestPath, platformPkgDir } = resolvePlatformPaths();
+  const resolvedVersion = readResolvedVersion(manifestPath);
 
   const binaryName = process.platform === "win32" ? `${binaryBaseName}.exe` : binaryBaseName;
   const binaryPath = path.join(platformPkgDir, binaryName);
@@ -126,11 +161,11 @@ function runBinary(binaryBaseName) {
     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);
+    if (e.status === 0) writeVerifiedLineIfVersionQuery(verifyResult, resolvedVersion);
     process.exit(e.status);
   }
 
-  writeVerifiedLineIfVersionQuery(verifyResult);
+  writeVerifiedLineIfVersionQuery(verifyResult, resolvedVersion);
 }
 
 module.exports = {

package/scripts/run-binary.test.js

@@ -37,3 +37,40 @@ test("guardBrokenStdout rethrows non-EPIPE stdout errors (exit 1)", () => {
   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");
 });
+
+test("isVersionQuery recognizes --version, -V, and -v as the first argument", () => {
+  const { isVersionQuery } = require(RUN_BINARY);
+  assert.equal(isVersionQuery(["node", "fallow", "--version"]), true);
+  assert.equal(isVersionQuery(["node", "fallow", "-V"]), true);
+  assert.equal(
+    isVersionQuery(["node", "fallow", "-v"]),
+    true,
+    "-v must append the verified line too",
+  );
+  assert.equal(isVersionQuery(["node", "fallow"]), false);
+  assert.equal(isVersionQuery(["node", "fallow", "dead-code"]), false);
+  assert.equal(
+    isVersionQuery(["node", "fallow", "dead-code", "-v"]),
+    false,
+    "-v only counts as the first arg",
+  );
+});
+
+test("describeVerified annotates the resolved version's signing status", () => {
+  const { describeVerified } = require(RUN_BINARY);
+  const ok = { ok: true, sentinelPath: "/c/s" };
+  // Signed-era version: appended as `signed`.
+  assert.match(
+    describeVerified(ok, "2.83.0"),
+    /verified: yes \(sentinel \/c\/s\); fallow 2\.83\.0 signed/,
+  );
+  // Pre-signing version: the fleet pre-flight signal, most useful on skip.
+  const skipped = { skipped: true, reason: "FALLOW_SKIP_BINARY_VERIFY is set" };
+  assert.match(
+    describeVerified(skipped, "2.76.0"),
+    /verified: skipped \(.*\); fallow 2\.76\.0 unsigned \(predates 2\.77\.0\)/,
+  );
+  // Unknown / unreadable version: no annotation, version line stays intact.
+  assert.equal(describeVerified(ok, undefined), "verified: yes (sentinel /c/s)");
+  assert.equal(describeVerified(ok, ""), "verified: yes (sentinel /c/s)");
+});

package/scripts/verify-binary.js

@@ -81,6 +81,10 @@ function _verifyWithKey(binaryPath, rawPubKey) {
     signature = fs.readFileSync(sigPath);
   } catch (err) {
     if (err && err.code === "ENOENT") {
+      // Low-level result: the version-aware guidance is attached one layer up
+      // in verifyOneBinary{,Sync}, which knows the resolved platform-package
+      // version and can distinguish a pre-signing version from a >=2.77.0
+      // package whose signature is missing (a tampering signal). Refs #944.
       return { ok: false, code: "sig-missing", message: `signature not found at ${sigPath}` };
     }
     return {
@@ -389,16 +393,69 @@ function resolvePlatformPackageForVerify(opts) {
   };
 }
 
+// Signed platform binaries ship from fallow 2.77.0 onward (the `.sig` staging
+// step, the `files` entries, and this verifier all landed in #488, first
+// released in 2.77.0). A resolved version below this epoch has no signature and
+// never will (npm is immutable), so its missing-sig failure is expected and the
+// fix is to upgrade the pin. A version at or above the epoch whose signature is
+// absent is a different, alarming case (tampered or incomplete package).
+const SIGNING_EPOCH = [2, 77, 0];
+
+// True when `version` is a parseable semver strictly below the signing epoch.
+// An unparsable / unknown version returns false so the caller uses the
+// cautious (possible-tampering) message rather than telling the user to bump.
+function isPreSigningVersion(version) {
+  if (typeof version !== "string") {
+    return false;
+  }
+  const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return false;
+  }
+  const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
+  for (let i = 0; i < SIGNING_EPOCH.length; i += 1) {
+    if (parts[i] < SIGNING_EPOCH[i]) {
+      return true;
+    }
+    if (parts[i] > SIGNING_EPOCH[i]) {
+      return false;
+    }
+  }
+  return false;
+}
+
+// Attach version-aware remediation to a `sig-missing` low-level result. Other
+// failure codes pass through untouched. The split distinguishes a pre-signing
+// version (no signature exists and never will, so the fix is to upgrade the
+// pin) from a >=2.77.0 package whose signature is unexpectedly absent (a
+// tampering signal). Each message gives the CONSTRUCTIVE fix only; the bypass
+// escape hatch (FALLOW_SKIP_BINARY_VERIFY) is owned by the caller's trailer and
+// SECURITY.md, deliberately not surfaced here so a tampering victim is never
+// nudged to bypass and the env is not normalized in CI logs.
+function describeSigMissing(result, version) {
+  if (result.code !== "sig-missing") {
+    return result;
+  }
+  const message = isPreSigningVersion(version)
+    ? `${result.message}. fallow ${version} predates signed binaries (signatures ship in 2.77.0 ` +
+      `and later), so this package has no signature to verify. Bump the \`fallow\` dependency in ` +
+      `your project's package.json to >=2.77.0 (for example \`npm install fallow@latest\`).`
+    : `${result.message}. fallow ${version} should be signed but its signature is missing; the ` +
+      `platform package may be tampered with or incomplete. Reinstall with \`npm install fallow@latest\` ` +
+      `and report it if it persists on a clean install.`;
+  return { ...result, message };
+}
+
 // Verify one binary against its sig + expected SHA-256. Used by both the
 // sync and async verify-installed entry points; the digest provider may be
 // sync (returns string) or async (returns Promise<string>), and the loop body
 // awaits the value regardless. Keeps the outer functions a flat for-loop so
 // cyclomatic + cognitive complexity stays low.
-async function verifyOneBinary(target, dir, pkg, manifestPath, verifyFn, digestProvider) {
+async function verifyOneBinary(target, dir, pkg, manifestPath, verifyFn, digestProvider, version) {
   const binaryPath = path.join(dir, target.binary);
   const sigResult = verifyFn(binaryPath);
   if (!sigResult.ok) {
-    return { ...sigResult, binary: binaryPath, package: pkg };
+    return { ...describeSigMissing(sigResult, version), binary: binaryPath, package: pkg };
   }
   // Prefer the digest embedded in the platform package's package.json
   // (written at release time by `npm-prep`). Falling back to the GitHub
@@ -478,7 +535,15 @@ async function verifyInstalled(options) {
   const boundProvider = async (args) => digestProvider({ ...args, version });
 
   for (const target of binaryTargetsForPlatform(platformId)) {
-    const result = await verifyOneBinary(target, dir, pkg, manifestPath, verify, boundProvider);
+    const result = await verifyOneBinary(
+      target,
+      dir,
+      pkg,
+      manifestPath,
+      verify,
+      boundProvider,
+      version,
+    );
     if (!result.ok) return result;
   }
   return { ok: true, package: pkg, version };
@@ -518,7 +583,15 @@ function verifyInstalledSync(options) {
   const { dir, manifestPath, pkg, version, platformId } = resolved;
 
   for (const target of binaryTargetsForPlatform(platformId)) {
-    const result = verifyOneBinarySync(target, dir, pkg, manifestPath, verify, digestProvider);
+    const result = verifyOneBinarySync(
+      target,
+      dir,
+      pkg,
+      manifestPath,
+      verify,
+      digestProvider,
+      version,
+    );
     if (!result.ok) return result;
   }
   return { ok: true, package: pkg, version };
@@ -529,11 +602,11 @@ function verifyInstalledSync(options) {
 // actionable error pointing the user at `npm install fallow@latest` (since
 // there is no network fallback in lazy mode), and the digestProvider is
 // optional (tests inject one; production callers rely on the embedded digest).
-function verifyOneBinarySync(target, dir, pkg, manifestPath, verifyFn, digestProvider) {
+function verifyOneBinarySync(target, dir, pkg, manifestPath, verifyFn, digestProvider, version) {
   const binaryPath = path.join(dir, target.binary);
   const sigResult = verifyFn(binaryPath);
   if (!sigResult.ok) {
-    return { ...sigResult, binary: binaryPath, package: pkg };
+    return { ...describeSigMissing(sigResult, version), binary: binaryPath, package: pkg };
   }
   let expectedDigest = manifestPath ? readEmbeddedDigest(manifestPath, target.binary) : null;
   if (!expectedDigest && digestProvider) {
@@ -575,6 +648,8 @@ module.exports = {
   verifyInstalled,
   verifyInstalledSync,
   _verifyWithKey,
+  isPreSigningVersion,
+  describeSigMissing,
   normalizeDigest,
   readEmbeddedDigest,
   sha256Hex,

package/scripts/verify-binary.test.js

@@ -7,6 +7,8 @@ const path = require("node:path");
 
 const {
   _verifyWithKey,
+  isPreSigningVersion,
+  describeSigMissing,
   verifyBinaryAt,
   verifyDigestAt,
   verifyInstalled,
@@ -133,6 +135,56 @@ test("_verifyWithKey returns sig-missing when the signature file does not exist"
   }
 });
 
+// The version-aware remediation lives in describeSigMissing (attached by
+// verifyOneBinary{,Sync}), not in the low-level _verifyWithKey result. Refs #944.
+test("isPreSigningVersion is true below 2.77.0 and false at/above it", () => {
+  assert.equal(isPreSigningVersion("2.76.0"), true);
+  assert.equal(isPreSigningVersion("2.73.0"), true);
+  assert.equal(isPreSigningVersion("1.9.0"), true);
+  assert.equal(isPreSigningVersion("2.77.0"), false);
+  assert.equal(isPreSigningVersion("2.83.0"), false);
+  assert.equal(isPreSigningVersion("2.88.2"), false);
+  // Unknown / unparsable versions default to false so the caller uses the
+  // cautious possible-tampering message rather than telling the user to bump.
+  assert.equal(isPreSigningVersion("unknown"), false);
+  assert.equal(isPreSigningVersion(undefined), false);
+});
+
+test("describeSigMissing gives upgrade guidance for a pre-signing version", () => {
+  const base = { ok: false, code: "sig-missing", message: "signature not found at /x/fallow.sig" };
+  const result = describeSigMissing(base, "2.76.0");
+  // The security-critical invariant: enriching the message must never flip the
+  // verdict. A sig-missing result stays a hard failure.
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "sig-missing");
+  assert.match(result.message, /predates signed binaries/);
+  assert.match(result.message, /2\.77\.0/);
+  // Names WHERE the pin lives so the user can act.
+  assert.match(result.message, /package\.json/);
+  // The bypass escape hatch is owned by the caller's trailer + SECURITY.md, not
+  // surfaced inline, so it is not normalized in CI logs.
+  assert.doesNotMatch(result.message, new RegExp(SKIP_ENV));
+  // The original low-level detail is preserved.
+  assert.match(result.message, /signature not found/);
+});
+
+test("describeSigMissing flags possible tampering for a signed-era version", () => {
+  const base = { ok: false, code: "sig-missing", message: "signature not found at /x/fallow.sig" };
+  const result = describeSigMissing(base, "2.83.0");
+  assert.equal(result.ok, false);
+  assert.equal(result.code, "sig-missing");
+  assert.match(result.message, /tampered with or incomplete/);
+  assert.match(result.message, /Reinstall/);
+  // Must NOT nudge a possible-tampering victim toward bypassing verification.
+  assert.doesNotMatch(result.message, new RegExp(SKIP_ENV));
+});
+
+test("describeSigMissing passes non-sig-missing results through untouched", () => {
+  const base = { ok: false, code: "digest-mismatch", message: "digest mismatch" };
+  const result = describeSigMissing(base, "2.76.0");
+  assert.equal(result.message, "digest mismatch");
+});
+
 test("_verifyWithKey returns binary-missing when the binary does not exist", () => {
   const { rawPub } = makeKeypair();
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), "fallow-vbtest-"));
@@ -343,6 +395,32 @@ test("verifyInstalled with dirOverride reports sig-missing when a .sig is absent
   assert.match(result.binary, /fallow-mcp/);
 });
 
+test("verifyInstalled threads the resolved version into the sig-missing message", async (t) => {
+  const { privateKey, rawPub } = makeKeypair();
+  const preDir = makePlatformDir(privateKey, { skipSigFor: "fallow-mcp" });
+  const eraDir = makePlatformDir(privateKey, { skipSigFor: "fallow-mcp" });
+  t.after(() => {
+    cleanup(preDir);
+    cleanup(eraDir);
+  });
+  const pre = await verifyInstalled({
+    dirOverride: preDir,
+    version: "2.76.0",
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(preDir),
+  });
+  assert.equal(pre.code, "sig-missing");
+  assert.match(pre.message, /predates signed binaries/);
+  const era = await verifyInstalled({
+    dirOverride: eraDir,
+    version: "2.83.0",
+    verifyFn: (p) => _verifyWithKey(p, rawPub),
+    digestProvider: makeDigestProvider(eraDir),
+  });
+  assert.equal(era.code, "sig-missing");
+  assert.match(era.message, /tampered with or incomplete/);
+});
+
 test("verifyInstalled reports digest-mismatch when SHA-256 disagrees with the provider", async (t) => {
   const { privateKey, rawPub } = makeKeypair();
   const dir = makePlatformDir(privateKey);

package/skills/fallow/references/cli-reference.md

@@ -486,7 +486,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.88.3",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -876,7 +876,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.88.3",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -949,7 +949,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.88.3",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1488,7 +1488,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.88.3",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1648,7 +1648,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.88.3",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1692,11 +1692,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.88.2",
+  "version": "2.88.3",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.88.2",
+    "version": "2.88.3",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],