pmsec 0.8.0 → 0.10.0

package/README.md

@@ -8,37 +8,37 @@ re-verification, build-script attestation, and more.
 ## Install
 
 ```bash
-npx pmsec enable
-npx pmsec check
-npx pmsec disable
+npx pmsec
+npx pmsec --check
+npx pmsec --disable
 ```
 
 ```bash
-uvx pmsec enable
-uvx pmsec check
-uvx pmsec disable
+uvx pmsec
+uvx pmsec --check
+uvx pmsec --disable
 ```
 
 If your environment already enforces cooldown (or routes through a proxy
 registry), bootstrap pmsec by overriding just for that call:
 
 ```bash
-npx --registry=https://registry.npmjs.org/ --min-release-age=0 pmsec check
-uvx --index https://pypi.org/simple --exclude-newer-package pmsec=2099-01-01 pmsec check
+npx --registry=https://registry.npmjs.org/ --min-release-age=0 pmsec --check
+uvx --index https://pypi.org/simple --exclude-newer-package pmsec=2099-01-01 pmsec --check
 ```
 
 Zero runtime dependencies, ESM, requires Node 22+.
 
-## Commands
+## Usage
 
-| Command | Description |
+| Invocation | Description |
 | --- | --- |
-| `pmsec enable` | Write the hardening bundle (3-day cooldown + per-tool extras) to every selected tool's user config. |
-| `pmsec check` | Read each tool's config; exit 1 if any row is missing or below the bundled value. |
-| `pmsec disable` | Remove every key the bundle set; other keys in the file are preserved. |
+| `pmsec` | Default action: write the hardening bundle (1-day cooldown + per-tool extras) to every selected tool's user config. |
+| `pmsec --check` | Read each tool's config; exit 1 if any row is missing or below the bundled value. |
+| `pmsec --disable` | Remove every key the bundle set; other keys in the file are preserved. |
 | `pmsec --version` | Print the installed pmsec version. |
 
-Options: `--tool npm,pnpm,yarn,bun,cargo,mise,uv`, `--days N` (override the 3-day default), `--force` (overwrite stricter existing cooldowns; default is monotonic), `--json`.
+Options: `--tool npm,pnpm,yarn,bun,cargo,mise,uv`, `--days N` (override the 1-day default), `--force` (overwrite stricter existing cooldowns; default is monotonic), `--json`. `--check` and `--disable` are mutually exclusive.
 
 When the target file is owned by another user (typical: `~/.npmrc` left
 root-owned by an old `sudo npm config set`), the write fails with `EACCES`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmsec",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },

package/src/cli.mjs

@@ -1,5 +1,6 @@
 import { homedir } from "node:os";
 import { readFileSync } from "node:fs";
+import { shellQuote } from "./util/io.mjs";
 import * as npm from "./tools/npm.mjs";
 import * as pnpm from "./tools/pnpm.mjs";
 import * as yarn from "./tools/yarn.mjs";
@@ -11,37 +12,34 @@ import * as uv from "./tools/uv.mjs";
 const TOOLS = [npm, pnpm, yarn, bun, cargo, mise, uv];
 // Default cooldown for the hardening bundle. Override per-invocation with
 // `--days N`; the default tracks the safest value we'd recommend.
-const BUNDLE_DAYS = 3;
+const BUNDLE_DAYS = 1;
 export const VERSION = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8")
 ).version;
 
-const USAGE = `pmsec <command> [options]
+const USAGE = `pmsec [options]
 
 Zero-config install-time supply-chain hardening across npm, pnpm, yarn,
-bun, cargo, mise, uv. \`set\` flips on every safe-by-default key each
-tool exposes (cooldown, audit-level, trust-policy, hardened mode,
+bun, cargo, mise, uv. Default action enables every safe-by-default key
+each tool exposes (cooldown, audit-level, trust-policy, hardened mode,
 attestation re-verification, ...). No knobs.
 
-Commands:
-  enable                Apply the hardening bundle to all selected tools
-  disable               Remove the hardening bundle from selected tools
-  check                 Verify the bundle is in place (exit 1 if anything missing)
-
 Options:
+  --check               Verify the bundle is in place (exit 1 if anything missing)
+  --disable             Remove the hardening bundle from selected tools
   --tool TOOL[,TOOL]    Restrict to specific tools (npm,pnpm,yarn,bun,cargo,mise,uv)
-  --days N              Override cooldown days (default 3)
+  --days N              Override cooldown days (default 1)
   --force               Overwrite stricter existing cooldowns (otherwise enable is monotonic)
   --json                Emit JSON output
   -V, --version         Show version
   -h, --help            Show this help
 
 Examples:
-  npx pmsec enable
-  npx pmsec enable --days 7
-  npx pmsec enable --days 1 --force
-  npx pmsec check
-  npx pmsec disable --tool npm
+  npx pmsec
+  npx pmsec --days 7
+  npx pmsec --days 1 --force
+  npx pmsec --check
+  npx pmsec --disable --tool npm
 `;
 
 function parseDays(raw) {
@@ -51,7 +49,13 @@ function parseDays(raw) {
 }
 
 function parse(argv) {
-  const opts = { command: null, json: false, only: null, days: BUNDLE_DAYS, force: false, help: false, version: false };
+  const opts = { mode: "enable", json: false, only: null, days: BUNDLE_DAYS, force: false, help: false, version: false };
+  let modeSet = false;
+  const setMode = (m) => {
+    if (modeSet && opts.mode !== m) throw new Error(`--check and --disable are mutually exclusive`);
+    opts.mode = m;
+    modeSet = true;
+  };
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -59,6 +63,8 @@ function parse(argv) {
     else if (a === "-V" || a === "--version") opts.version = true;
     else if (a === "--json") opts.json = true;
     else if (a === "--force") opts.force = true;
+    else if (a === "--check") setMode("check");
+    else if (a === "--disable") setMode("disable");
     else if (a === "--tool") opts.only = argv[++i].split(",");
     else if (a.startsWith("--tool=")) opts.only = a.slice(7).split(",");
     else if (a === "--days") opts.days = parseDays(argv[++i]);
@@ -66,8 +72,7 @@ function parse(argv) {
     else if (a.startsWith("-")) throw new Error(`unknown flag: ${a}`);
     else positional.push(a);
   }
-  opts.command = positional[0] ?? null;
-  if (positional.length > 1) throw new Error(`unexpected argument: ${positional[1]}`);
+  if (positional.length) throw new Error(`unexpected argument: ${positional[0]}`);
   return opts;
 }
 
@@ -79,20 +84,20 @@ function selectTools(only) {
   return found;
 }
 
-function preflightWarn(t) {
+function preflightWarn(t, ctx) {
   if (typeof t.preflight !== "function") return null;
-  const pf = t.preflight();
+  const pf = t.preflight(ctx);
   return pf?.message ?? null;
 }
 
-async function gatherStatus(targets, env, home, platform) {
+async function gatherStatus(targets, ctx) {
   return Promise.all(targets.map(async t => {
-    const r = await t.read(env, home, platform);
+    const r = await t.read(ctx);
     return {
       tool: t.name, key: t.key, path: r.path,
       configured: r.configured, days: r.days,
       extras: r.extras ?? [],
-      warn: preflightWarn(t)
+      warn: preflightWarn(t, ctx)
     };
   }));
 }
@@ -113,53 +118,50 @@ function renderHuman(rows, min) {
   return lines.join("\n") + "\n";
 }
 
-async function runCheck(targets, { json, days }, env, home, platform, out, err) {
-  const rows = await gatherStatus(targets, env, home, platform);
+async function runCheck(targets, { json, days }, ctx, out, err) {
+  const rows = await gatherStatus(targets, ctx);
   const failingPrimary = rows.filter(r => r.days === null || r.days < days);
   const failingExtras = rows.flatMap(r => r.extras.filter(e => !e.ok));
   const ok = failingPrimary.length === 0 && failingExtras.length === 0;
   if (json) out.write(JSON.stringify({ bundleDays: days, rows, ok }, null, 2) + "\n");
   else out.write(renderHuman(rows, days));
-  if (failingPrimary.length) err.write(`pmsec: ${failingPrimary.length} tool(s) below ${days} days — run \`pmsec enable\`\n`);
-  if (failingExtras.length) err.write(`pmsec: ${failingExtras.length} hardening setting(s) not at safe value — run \`pmsec enable\`\n`);
+  if (failingPrimary.length) err.write(`pmsec: ${failingPrimary.length} tool(s) below ${days} days — run \`pmsec\`\n`);
+  if (failingExtras.length) err.write(`pmsec: ${failingExtras.length} hardening setting(s) not at safe value — run \`pmsec\`\n`);
   return ok ? 0 : 1;
 }
 
-function shQuote(s) { return s ? `'${String(s).replace(/'/g, `'\\''`)}'` : ""; }
-
 function explainFsError(e, tool) {
   if (e?.code === "EACCES" || e?.code === "EPERM") {
     const p = e.path ?? "";
-    const q = shQuote(p);
+    const q = p ? shellQuote(p) : "";
     return `${tool}: cannot write ${p} (${e.code}). Check file ownership: \`ls -la ${q}\` — if owned by root, run \`sudo chown -h $(id -u):$(id -g) ${q}\`.`;
   }
   if (e?.code === "EROFS") return `${tool}: ${e.path ?? ""} is on a read-only filesystem (EROFS).`;
   return `${tool}: ${e?.message ?? e}`;
 }
 
-async function runEnable(targets, json, days, force, env, home, platform, out, err) {
-  const results = [];
-  const failures = [];
-  const warnings = [];
-  for (const t of targets) {
-    const warn = preflightWarn(t);
-    if (warn) warnings.push({ tool: t.name, warn });
+async function runEnable(targets, json, days, force, ctx, out, err) {
+  // Each tool writes a different config file; safe to run in parallel.
+  // Promise.all preserves input order in the results array.
+  const results = await Promise.all(targets.map(async t => {
+    const warn = preflightWarn(t, ctx);
     try {
       let effective = days;
       let kept = false;
       if (!force) {
-        const current = await t.read(env, home, platform);
+        const current = await t.read(ctx);
         const currentDays = current.days ?? 0;
         effective = Math.max(currentDays, days);
         kept = currentDays >= days && currentDays > 0;
       }
-      const r = await t.write(effective, env, home, platform);
-      results.push({ tool: t.name, path: r.path, days: effective, requested: days, kept, forced: force, ok: true, warn });
+      const r = await t.write(effective, ctx);
+      return { tool: t.name, path: r.path, days: effective, requested: days, kept, forced: force, ok: true, warn };
     } catch (e) {
-      failures.push({ tool: t.name, error: explainFsError(e, t.name) });
-      results.push({ tool: t.name, path: e?.path ?? null, days, requested: days, kept: false, forced: force, ok: false, error: explainFsError(e, t.name), warn });
+      return { tool: t.name, path: e?.path ?? null, days, requested: days, kept: false, forced: force, ok: false, error: explainFsError(e, t.name), warn };
     }
-  }
+  }));
+  const failures = results.filter(r => !r.ok).map(r => ({ tool: r.tool, error: r.error }));
+  const warnings = results.filter(r => r.warn).map(r => ({ tool: r.tool, warn: r.warn }));
   if (json) out.write(JSON.stringify({ enabled: true, bundleDays: days, results, warnings, ok: failures.length === 0 }, null, 2) + "\n");
   else for (const r of results) {
     if (r.ok) {
@@ -176,18 +178,16 @@ async function runEnable(targets, json, days, force, env, home, platform, out, e
   return failures.length ? 1 : 0;
 }
 
-async function runDisable(targets, json, env, home, platform, out, err) {
-  const results = [];
-  const failures = [];
-  for (const t of targets) {
+async function runDisable(targets, json, ctx, out, err) {
+  const results = await Promise.all(targets.map(async t => {
     try {
-      const r = await t.unset(env, home, platform);
-      results.push({ tool: t.name, path: r.path, removed: r.removed, ok: true });
+      const r = await t.unset(ctx);
+      return { tool: t.name, path: r.path, removed: r.removed, ok: true };
     } catch (e) {
-      failures.push({ tool: t.name, error: explainFsError(e, t.name) });
-      results.push({ tool: t.name, path: e?.path ?? null, removed: false, ok: false, error: explainFsError(e, t.name) });
+      return { tool: t.name, path: e?.path ?? null, removed: false, ok: false, error: explainFsError(e, t.name) };
     }
-  }
+  }));
+  const failures = results.filter(r => !r.ok).map(r => ({ tool: r.tool, error: r.error }));
   if (json) out.write(JSON.stringify({ results, ok: failures.length === 0 }, null, 2) + "\n");
   else for (const r of results) {
     if (!r.ok) out.write(`FAIL    ${r.tool.padEnd(4)} ${r.error}\n`);
@@ -208,16 +208,15 @@ export async function run(argv, {
   try { opts = parse(argv); }
   catch (e) { err.write(`pmsec: ${e.message}\n`); return 2; }
   if (opts.version) { out.write(`pmsec ${VERSION}\n`); return 0; }
-  if (opts.help || !opts.command) { out.write(USAGE); return opts.help ? 0 : 2; }
+  if (opts.help) { out.write(USAGE); return 0; }
   let targets;
   try { targets = selectTools(opts.only); }
   catch (e) { err.write(`pmsec: ${e.message}\n`); return 2; }
+  const ctx = { env, home, platform };
   try {
-    if (opts.command === "check") return await runCheck(targets, opts, env, home, platform, out, err);
-    if (opts.command === "enable") return await runEnable(targets, opts.json, opts.days, opts.force, env, home, platform, out, err);
-    if (opts.command === "disable") return await runDisable(targets, opts.json, env, home, platform, out, err);
-    err.write(`pmsec: unknown command "${opts.command}"\n`);
-    return 2;
+    if (opts.mode === "check") return await runCheck(targets, opts, ctx, out, err);
+    if (opts.mode === "disable") return await runDisable(targets, opts.json, ctx, out, err);
+    return await runEnable(targets, opts.json, opts.days, opts.force, ctx, out, err);
   } catch (e) {
     err.write(`pmsec: ${e.message}\n`);
     return 1;

package/src/tools/bun.mjs

@@ -1,7 +1,7 @@
 import { bunConfigPath } from "../util/paths.mjs";
 import { readSafe, writeAtomic } from "../util/io.mjs";
 import { readKey, setKey, removeKey } from "../util/lines.mjs";
-import { detectVersion, gte } from "../util/version.mjs";
+import { buildPreflight } from "../util/version.mjs";
 
 export const name = "bun";
 export const key = "minimumReleaseAge";
@@ -10,33 +10,28 @@ export const docs = "https://bun.com/docs/runtime/bunfig#install";
 export const minBin = [1, 3, 0];
 export const extras = [];
 
-export function path(env, home) { return bunConfigPath(env, home); }
+export function path(ctx) { return bunConfigPath(ctx.env, ctx.home); }
 
-export function preflight() {
-  const v = detectVersion("bun");
-  if (v === null) return { ok: true, message: null };
-  if (gte(v, minBin)) return { ok: true, version: v.raw, message: null };
-  return { ok: true, warn: true, version: v.raw, message: `bun ${v.raw} < ${minBin.join(".")}: minimumReleaseAge is silently ignored. Upgrade bun to enforce the cooldown.` };
-}
+export const preflight = buildPreflight(name, minBin,
+  "minimumReleaseAge is silently ignored. Upgrade bun to enforce the cooldown.");
 
-export async function read(env, home) {
-  const p = path(env, home);
+export async function read(ctx) {
+  const p = path(ctx);
   const raw = await readSafe(p);
   const value = readKey(raw, key, { section });
   const seconds = value === null ? null : Number(value);
   return { path: p, configured: value, days: seconds === null || Number.isNaN(seconds) ? null : Math.floor(seconds / 86400), extras: [] };
 }
 
-export async function write(days, env, home) {
-  const p = path(env, home);
-  const before = await readSafe(p);
-  const after = setKey(before, key, `${key} = ${days * 86400}`, { section });
-  await writeAtomic(p, after);
-  return { path: p, before, after };
+export async function write(days, ctx) {
+  const p = path(ctx);
+  const text = setKey(await readSafe(p), key, `${key} = ${days * 86400}`, { section });
+  await writeAtomic(p, text);
+  return { path: p };
 }
 
-export async function unset(env, home) {
-  const p = path(env, home);
+export async function unset(ctx) {
+  const p = path(ctx);
   const before = await readSafe(p);
   const { text: after, removed } = removeKey(before, key, { section });
   if (removed) await writeAtomic(p, after);

package/src/tools/cargo.mjs

@@ -8,7 +8,7 @@ export const section = "install";
 export const docs = "https://rust-lang.github.io/rfcs/3801-package-cooldown.html";
 export const extras = [];
 
-export function path(env, home) { return cargoConfigPath(env, home); }
+export function path(ctx) { return cargoConfigPath(ctx.env, ctx.home); }
 
 function parseDays(value) {
   if (value === null) return null;
@@ -18,23 +18,22 @@ function parseDays(value) {
   return /^(w|weeks?)$/i.test(m[2]) ? n * 7 : n;
 }
 
-export async function read(env, home) {
-  const p = path(env, home);
+export async function read(ctx) {
+  const p = path(ctx);
   const raw = await readSafe(p);
   const value = readKey(raw, key, { section });
   return { path: p, configured: value, days: parseDays(value), extras: [] };
 }
 
-export async function write(days, env, home) {
-  const p = path(env, home);
-  const before = await readSafe(p);
-  const after = setKey(before, key, `${key} = "${days}d"`, { section });
-  await writeAtomic(p, after);
-  return { path: p, before, after };
+export async function write(days, ctx) {
+  const p = path(ctx);
+  const text = setKey(await readSafe(p), key, `${key} = "${days}d"`, { section });
+  await writeAtomic(p, text);
+  return { path: p };
 }
 
-export async function unset(env, home) {
-  const p = path(env, home);
+export async function unset(ctx) {
+  const p = path(ctx);
   const before = await readSafe(p);
   const { text: after, removed } = removeKey(before, key, { section });
   if (removed) await writeAtomic(p, after);

package/src/tools/mise.mjs

@@ -2,7 +2,7 @@ import { miseConfigPath } from "../util/paths.mjs";
 import { readSafe, writeAtomic } from "../util/io.mjs";
 import { readKey, setKey, removeKey } from "../util/lines.mjs";
 import { readExtras, applyExtras, removeExtras } from "../util/extras.mjs";
-import { detectVersion, gte } from "../util/version.mjs";
+import { buildPreflight } from "../util/version.mjs";
 export const name = "mise";
 export const key = "minimum_release_age";
 export const section = "settings";
@@ -12,14 +12,10 @@ export const extras = [
   { key: "paranoid", expected: "true", line: "paranoid = true", section }
 ];
 
-export function path(env, home, platform) { return miseConfigPath(env, home, platform); }
+export function path(ctx) { return miseConfigPath(ctx.env, ctx.home, ctx.platform); }
 
-export function preflight() {
-  const v = detectVersion("mise");
-  if (v === null) return { ok: true, message: null };
-  if (gte(v, minBin)) return { ok: true, version: v.raw, message: null };
-  return { ok: true, warn: true, version: v.raw, message: `mise ${v.raw} < ${minBin.join(".")}: setting was named install_before before 2026.4.22 and minimum_release_age is silently ignored on older mise. Upgrade mise (\`mise self-update\`) to enforce the cooldown.` };
-}
+export const preflight = buildPreflight(name, minBin,
+  "setting was named install_before before 2026.4.22 and minimum_release_age is silently ignored on older mise. Upgrade mise (`mise self-update`) to enforce the cooldown.");
 
 function parseDays(value) {
   if (value === null) return null;
@@ -33,8 +29,8 @@ function parseDays(value) {
   return n;
 }
 
-export async function read(env, home, platform) {
-  const p = path(env, home, platform);
+export async function read(ctx) {
+  const p = path(ctx);
   const raw = await readSafe(p);
   const value = readKey(raw, key, { section });
   return {
@@ -43,17 +39,16 @@ export async function read(env, home, platform) {
   };
 }
 
-export async function write(days, env, home, platform) {
-  const p = path(env, home, platform);
-  const before = await readSafe(p);
-  let after = setKey(before, key, `${key} = "${days}d"`, { section });
-  after = applyExtras(after, extras);
-  await writeAtomic(p, after);
-  return { path: p, before, after };
+export async function write(days, ctx) {
+  const p = path(ctx);
+  let text = setKey(await readSafe(p), key, `${key} = "${days}d"`, { section });
+  text = applyExtras(text, extras);
+  await writeAtomic(p, text);
+  return { path: p };
 }
 
-export async function unset(env, home, platform) {
-  const p = path(env, home, platform);
+export async function unset(ctx) {
+  const p = path(ctx);
   const before = await readSafe(p);
   const cooldown = removeKey(before, key, { section });
   const ex = removeExtras(cooldown.text, extras);

package/src/tools/npm.mjs

@@ -2,7 +2,7 @@ import { npmrcPath } from "../util/paths.mjs";
 import { readSafe, writeAtomic } from "../util/io.mjs";
 import { readKey, setKey, removeKey } from "../util/lines.mjs";
 import { readExtras, applyExtras, removeExtras } from "../util/extras.mjs";
-import { detectVersion, gte } from "../util/version.mjs";
+import { buildPreflight } from "../util/version.mjs";
 
 export const name = "npm";
 export const key = "min-release-age";
@@ -12,17 +12,13 @@ export const extras = [
   { key: "audit-level", expected: "high", line: "audit-level=high" }
 ];
 
-export function path(env, home) { return npmrcPath(env, home); }
+export function path(ctx) { return npmrcPath(ctx.env, ctx.home); }
 
-export function preflight() {
-  const v = detectVersion("npm");
-  if (v === null) return { ok: true, message: null };
-  if (gte(v, minBin)) return { ok: true, version: v.raw, message: null };
-  return { ok: true, warn: true, version: v.raw, message: `npm ${v.raw} < ${minBin.join(".")}: min-release-age is silently ignored. Upgrade npm to enforce the cooldown.` };
-}
+export const preflight = buildPreflight(name, minBin,
+  "min-release-age is silently ignored. Upgrade npm to enforce the cooldown.");
 
-export async function read(env, home) {
-  const p = path(env, home);
+export async function read(ctx) {
+  const p = path(ctx);
   const raw = await readSafe(p);
   const value = readKey(raw, key);
   return {
@@ -32,17 +28,16 @@ export async function read(env, home) {
   };
 }
 
-export async function write(days, env, home) {
-  const p = path(env, home);
-  const before = await readSafe(p);
-  let after = setKey(before, key, `${key}=${days}`);
-  after = applyExtras(after, extras);
-  await writeAtomic(p, after);
-  return { path: p, before, after };
+export async function write(days, ctx) {
+  const p = path(ctx);
+  let text = setKey(await readSafe(p), key, `${key}=${days}`);
+  text = applyExtras(text, extras);
+  await writeAtomic(p, text);
+  return { path: p };
 }
 
-export async function unset(env, home) {
-  const p = path(env, home);
+export async function unset(ctx) {
+  const p = path(ctx);
   const before = await readSafe(p);
   const cooldown = removeKey(before, key);
   const ex = removeExtras(cooldown.text, extras);

package/src/tools/pnpm.mjs

@@ -17,25 +17,34 @@ export const extras = [
   { key: "strict-dep-builds", expected: "true", line: "strict-dep-builds=true" }
 ];
 
-export function path(env, home, platform) { return pnpmRcPath(env, home, platform); }
+export function path(ctx) { return pnpmRcPath(ctx.env, ctx.home, ctx.platform); }
 
-function pnpmVersion(env) {
-  return detectVersion("pnpm", ["--version"], { env, overrideKey: "PMSEC_PNPM_VERSION" });
+// Cache `pnpm --version` for the lifetime of the process. preflight() and
+// read() both want it; without memoization a single `pmsec check` spawns
+// pnpm twice. Cache key is the override env value so tests with different
+// `PMSEC_PNPM_VERSION` settings invalidate naturally.
+let _versionCache = null;
+function pnpmVersion(ctx) {
+  const override = ctx.env?.PMSEC_PNPM_VERSION ?? null;
+  if (_versionCache && _versionCache.override === override) return _versionCache.value;
+  const v = detectVersion("pnpm", ["--version"], { env: ctx.env, overrideKey: "PMSEC_PNPM_VERSION" });
+  _versionCache = { override, value: v };
+  return v;
 }
 
-export function preflight(env) {
-  const v = pnpmVersion(env);
+export function preflight(ctx) {
+  const v = pnpmVersion(ctx);
   if (v === null) return { ok: true, message: null };
   if (gte(v, minBin)) return { ok: true, version: v.raw, message: null };
   return { ok: true, warn: true, version: v.raw, message: `pnpm ${v.raw} < ${minBin.join(".")}: minimum-release-age is silently ignored. Upgrade pnpm to enforce the cooldown.` };
 }
 
-export async function read(env, home, platform) {
-  const p = path(env, home, platform);
+export async function read(ctx) {
+  const p = path(ctx);
   const raw = await readSafe(p);
   const value = readKey(raw, key);
   const minutes = value === null ? null : Number(value);
-  const v = pnpmVersion(env);
+  const v = pnpmVersion(ctx);
   const defaults = new Map(extras.filter(x => x.defaultSinceMajor).map(x => [x.key, x.defaultSinceMajor]));
   const evaluated = readExtras(raw, extras).map(e => {
     const def = defaults.get(e.key);
@@ -51,17 +60,16 @@ export async function read(env, home, platform) {
   };
 }
 
-export async function write(days, env, home, platform) {
-  const p = path(env, home, platform);
-  const before = await readSafe(p);
-  let after = setKey(before, key, `${key}=${days * 24 * 60}`);
-  after = applyExtras(after, extras);
-  await writeAtomic(p, after);
-  return { path: p, before, after };
+export async function write(days, ctx) {
+  const p = path(ctx);
+  let text = setKey(await readSafe(p), key, `${key}=${days * 24 * 60}`);
+  text = applyExtras(text, extras);
+  await writeAtomic(p, text);
+  return { path: p };
 }
 
-export async function unset(env, home, platform) {
-  const p = path(env, home, platform);
+export async function unset(ctx) {
+  const p = path(ctx);
   const before = await readSafe(p);
   const cooldown = removeKey(before, key);
   const ex = removeExtras(cooldown.text, extras);

package/src/tools/uv.mjs

@@ -1,7 +1,7 @@
 import { uvConfigPath } from "../util/paths.mjs";
 import { readSafe, writeAtomic } from "../util/io.mjs";
 import { readKey, setKey, removeKey } from "../util/lines.mjs";
-import { detectVersion, gte } from "../util/version.mjs";
+import { buildPreflight } from "../util/version.mjs";
 
 export const name = "uv";
 export const key = "exclude-newer";
@@ -9,14 +9,10 @@ export const docs = "https://docs.astral.sh/uv/reference/settings/#exclude-newer
 export const minBin = [0, 9, 17];
 export const extras = [];
 
-export function path(env, home, platform) { return uvConfigPath(env, home, platform); }
+export function path(ctx) { return uvConfigPath(ctx.env, ctx.home, ctx.platform); }
 
-export function preflight() {
-  const v = detectVersion("uv");
-  if (v === null) return { ok: true, message: null };
-  if (gte(v, minBin)) return { ok: true, version: v.raw, message: null };
-  return { ok: true, warn: true, version: v.raw, message: `uv ${v.raw} < ${minBin.join(".")}: writing exclude-newer = "N days" will break this uv until you \`uv self update\` (file will fail to parse).` };
-}
+export const preflight = buildPreflight(name, minBin,
+  "writing exclude-newer = \"N days\" will break this uv until you `uv self update` (file will fail to parse).");
 
 function parseDays(value) {
   if (value === null) return null;
@@ -26,23 +22,22 @@ function parseDays(value) {
   return /^(week|weeks|w)$/i.test(m[2]) ? n * 7 : n;
 }
 
-export async function read(env, home, platform) {
-  const p = path(env, home, platform);
+export async function read(ctx) {
+  const p = path(ctx);
   const raw = await readSafe(p);
   const value = readKey(raw, key);
   return { path: p, configured: value, days: parseDays(value), extras: [] };
 }
 
-export async function write(days, env, home, platform) {
-  const p = path(env, home, platform);
-  const before = await readSafe(p);
-  const after = setKey(before, key, `${key} = "${days} days"`);
-  await writeAtomic(p, after);
-  return { path: p, before, after };
+export async function write(days, ctx) {
+  const p = path(ctx);
+  const text = setKey(await readSafe(p), key, `${key} = "${days} days"`);
+  await writeAtomic(p, text);
+  return { path: p };
 }
 
-export async function unset(env, home, platform) {
-  const p = path(env, home, platform);
+export async function unset(ctx) {
+  const p = path(ctx);
   const before = await readSafe(p);
   const { text: after, removed } = removeKey(before, key);
   if (removed) await writeAtomic(p, after);

package/src/tools/yarn.mjs

@@ -2,7 +2,7 @@ import { yarnrcPath } from "../util/paths.mjs";
 import { readSafe, writeAtomic } from "../util/io.mjs";
 import { readKey, setKey, removeKey } from "../util/lines.mjs";
 import { readExtras, applyExtras, removeExtras } from "../util/extras.mjs";
-import { detectVersion, gte } from "../util/version.mjs";
+import { buildPreflight } from "../util/version.mjs";
 
 export const name = "yarn";
 export const key = "npmMinimalAgeGate";
@@ -13,14 +13,10 @@ export const extras = [
   { key: "enableHardenedMode", expected: "true", line: "enableHardenedMode: true", sep: SEP }
 ];
 
-export function path(env, home) { return yarnrcPath(env, home); }
+export function path(ctx) { return yarnrcPath(ctx.env, ctx.home); }
 
-export function preflight() {
-  const v = detectVersion("yarn");
-  if (v === null) return { ok: true, message: null };
-  if (gte(v, minBin)) return { ok: true, version: v.raw, message: null };
-  return { ok: true, warn: true, version: v.raw, message: `yarn ${v.raw} < ${minBin.join(".")}: npmMinimalAgeGate is silently ignored. Upgrade yarn (v4.10+) to enforce the cooldown.` };
-}
+export const preflight = buildPreflight(name, minBin,
+  "npmMinimalAgeGate is silently ignored. Upgrade yarn (v4.10+) to enforce the cooldown.");
 
 function parseDays(value) {
   if (value === null) return null;
@@ -30,8 +26,8 @@ function parseDays(value) {
   return /^(w|weeks?)$/i.test(m[2]) ? n * 7 : n;
 }
 
-export async function read(env, home) {
-  const p = path(env, home);
+export async function read(ctx) {
+  const p = path(ctx);
   const raw = await readSafe(p);
   const value = readKey(raw, key, { sep: SEP });
   return {
@@ -40,17 +36,16 @@ export async function read(env, home) {
   };
 }
 
-export async function write(days, env, home) {
-  const p = path(env, home);
-  const before = await readSafe(p);
-  let after = setKey(before, key, `${key}: "${days}d"`, { sep: SEP });
-  after = applyExtras(after, extras);
-  await writeAtomic(p, after);
-  return { path: p, before, after };
+export async function write(days, ctx) {
+  const p = path(ctx);
+  let text = setKey(await readSafe(p), key, `${key}: "${days}d"`, { sep: SEP });
+  text = applyExtras(text, extras);
+  await writeAtomic(p, text);
+  return { path: p };
 }
 
-export async function unset(env, home) {
-  const p = path(env, home);
+export async function unset(ctx) {
+  const p = path(ctx);
   const before = await readSafe(p);
   const cooldown = removeKey(before, key, { sep: SEP });
   const ex = removeExtras(cooldown.text, extras);

package/src/util/io.mjs

@@ -23,7 +23,7 @@ function underHome(p, home) {
   return r === h || r.startsWith(h + sep);
 }
 
-function shellQuote(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
+export function shellQuote(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
 
 async function reclaim(path, home, err) {
   if (process.platform === "win32" || typeof process.getuid !== "function") return false;

package/src/util/version.mjs

@@ -19,7 +19,7 @@ export function detectVersion(bin, args = ["--version"], { env, overrideKey } =
     }
   }
   try {
-    const res = spawnSync(bin, args, { encoding: "utf8" });
+    const res = spawnSync(bin, args, { encoding: "utf8", timeout: 5000, killSignal: "SIGKILL" });
     if (res.status !== 0) return null;
     return parseSemver(res.stdout);
   } catch { return null; }
@@ -32,3 +32,13 @@ export function gte(v, target) {
   if (v.minor !== b) return v.minor > b;
   return v.patch >= c;
 }
+
+export function buildPreflight(name, minBin, suffix) {
+  return () => {
+    const v = detectVersion(name);
+    if (v === null) return { ok: true, message: null };
+    if (gte(v, minBin)) return { ok: true, version: v.raw, message: null };
+    return { ok: true, warn: true, version: v.raw,
+      message: `${name} ${v.raw} < ${minBin.join(".")}: ${suffix}` };
+  };
+}