@lionad/safe-npx 0.4.0 → 0.5.0

package/README.md

@@ -9,11 +9,11 @@
 
 **This project is archived as of April 2026.**
 
-npm v11.10.0+ now provides native protection via `min-release-age` configuration. snpx has served its purpose and is no longer needed.
+npm v11.10.0+ now provides native protection via `min-release-age` configuration.
 
 **项目已于 2026 年 4 月归档。**
 
-npm v11.10.0+ 已原生支持 `min-release-age` 配置，提供相同的供应链攻击防护。snpx 已完成历史使命，不再需要。
+npm v11.10.0+ 已原生支持 `min-release-age` 配置，提供相同的供应链攻击防护。
 
 ### Migration / 迁移指南
 
@@ -86,7 +86,8 @@ snpx 使用**包名前/后**来区分不同层级的参数：
 | 类别 | 支持的参数 | 说明 |
 |------|-----------|------|
 | **snpx 专属** | `--help`, `--version`, `--show-version`<br>`--time`, `--fallback-strategy`<br>`--self-update`, `--unsafe-self-update` | snpx 的配置选项 |
-| **npx 白名单** | `-y`, `--yes`, `--no`<br>`-p <pkg>`, `--package=<pkg>`<br>`-c <cmd>`, `--call=<cmd>`<br>`--offline`, `--prefer-offline`<br>`-w <name>`, `--workspace=<name>`<br>`--silent`, `--quiet`, `--registry=<url>` | 传递给 npx 的前置参数 |
+| **npx 白名单** | `-y`, `--yes`, `--no`<br>`-p <pkg>`, `--package=<pkg>`<br>`-c <cmd>`, `--call=<cmd>`<br>`--offline`, `--prefer-offline`<br>`-w <name>`, `--workspace=<name>`<br>`--quiet`, `--registry=<url>` | 传递给 npx 的前置参数 |
+| **snpx 日志** | `--verbose` | 显示 snpx 内部日志（默认静默） |
 
 **After package / 包名之后**（全部透传给被执行的工具）：
 
@@ -156,8 +157,17 @@ snpx --help
 
 # Use -- to prevent tool flags from being parsed as snpx flags / 使用 -- 防止工具参数被误解析为 snpx 标志
 snpx -- cowsay --help
+
+# Show snpx internal logs / 显示 snpx 内部日志
+snpx --verbose cowsay@latest
 ```
 
+### Default Silent Mode / 默认静默模式
+
+**By default, snpx runs silently.** It only prints `--help`, `--version`, and `--show-version` to stdout, plus errors to stderr. No `[snpx] Resolving...` logs are emitted unless you pass `--verbose`. This ensures stdout remains clean for downstream consumers like MCP servers.
+
+**默认情况下，snpx 以静默模式运行。** 只有 `--help`、`--version`、`--show-version` 会输出到 stdout，错误输出到 stderr。除非传入 `--verbose`，否则不会打印 `[snpx] Resolving...` 等内部日志。这保证了对 MCP server 等下游依赖的 stdout 不产生污染。
+
 ## Environment Variables / 环境变量
 
 - `SNPX_TIME` — Default for `--time` / `--time` 的默认值

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { spawn } from "child_process";
+import { constants, homedir } from "os";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { homedir } from "os";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -38,20 +38,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 //#region src/constants.ts
-var constants_exports = /* @__PURE__ */ __exportAll({
-	CACHE_DIR: () => CACHE_DIR,
-	DEFAULT_FALLBACK_STRATEGY: () => DEFAULT_FALLBACK_STRATEGY,
-	DEFAULT_TIME_HOURS: () => 24,
-	HELP_TEXT: () => HELP_TEXT,
-	MS_PER_HOUR: () => MS_PER_HOUR,
-	NPX_PREFIX_FLAGS: () => NPX_PREFIX_FLAGS,
-	NPX_PREFIX_FLAGS_WITH_VALUE: () => NPX_PREFIX_FLAGS_WITH_VALUE,
-	PKG_NAME: () => PKG_NAME,
-	REGISTRY: () => REGISTRY,
-	VERSION: () => VERSION,
-	colors: () => colors,
-	isTty: () => isTty
-});
 var __dirname, VERSION, CACHE_DIR, REGISTRY, PKG_NAME, DEFAULT_TIME_HOURS, DEFAULT_FALLBACK_STRATEGY, MS_PER_HOUR, isTty, colors, HELP_TEXT, NPX_PREFIX_FLAGS, NPX_PREFIX_FLAGS_WITH_VALUE;
 var init_constants = __esmMin((() => {
 	__dirname = dirname(fileURLToPath(import.meta.url));
@@ -93,6 +79,8 @@ ${colors.bold("Options:")}
                             ${colors.dim("major")}  = most recently published version of previous major line
   ${colors.yellow("--show-version")}            Print resolved version and exit (no execution)
   ${colors.yellow("--version")}                 Print snpx version and exit
+  ${colors.yellow("--silent")}                  Suppress snpx info logs (default)
+  ${colors.yellow("--verbose")}                 Show snpx info logs
   ${colors.yellow("--self-update")}             Check for snpx updates (safe mode, default 24h)
   ${colors.yellow("--unsafe-self-update")}      Allow immediate snpx updates without safety window
 
@@ -121,7 +109,6 @@ ${colors.bold("Examples:")}
 		"--workspaces",
 		"--ws",
 		"--include-workspace-root",
-		"--silent",
 		"--quiet",
 		"-q"
 	]);
@@ -139,6 +126,15 @@ ${colors.bold("Examples:")}
 //#region src/cli.ts
 init_constants();
 /**
+* Create a logger that suppresses info-level output when silent is true.
+* Info messages are written to stderr to avoid polluting stdout.
+*/
+function createLogger(silent) {
+	return { info: (msg) => {
+		if (!silent) console.error(msg);
+	} };
+}
+/**
 * Extract package name from spec.
 * @example 'cowsay@1.5.0' → 'cowsay'
 * @example '@vue/cli@latest' → '@vue/cli'
@@ -170,6 +166,8 @@ function parseArgs(argv) {
 		showVersion: false,
 		selfUpdate: false,
 		unsafeSelfUpdate: false,
+		silent: true,
+		verbose: false,
 		time: null,
 		fallbackStrategy: null
 	};
@@ -199,7 +197,11 @@ function parseArgs(argv) {
 		else if (arg === "--version") snpxFlags.version = true;
 		else if (arg === "--show-version") snpxFlags.showVersion = true;
 		else if (arg === "--self-update") snpxFlags.selfUpdate = true;
-		else if (arg === "--unsafe-self-update") snpxFlags.unsafeSelfUpdate = true;
+		else if (arg === "--silent") snpxFlags.silent = true;
+		else if (arg === "--verbose") {
+			snpxFlags.silent = false;
+			snpxFlags.verbose = true;
+		} else if (arg === "--unsafe-self-update") snpxFlags.unsafeSelfUpdate = true;
 		else if (arg === "--time") {
 			if (i + 1 >= args.length) throw new Error("Missing value for --time");
 			snpxFlags.time = args[++i];
@@ -249,7 +251,8 @@ function buildOptions(snpxFlags) {
 	return {
 		timeHours,
 		timeMs: parsedHours * MS_PER_HOUR,
-		strategy: (snpxFlags.fallbackStrategy ?? envStrategy ?? "patch,minor,major").split(",").map((s) => s.trim()).filter(Boolean)
+		strategy: (snpxFlags.fallbackStrategy ?? envStrategy ?? "patch,minor,major").split(",").map((s) => s.trim()).filter(Boolean),
+		silent: snpxFlags.verbose ? false : snpxFlags.silent ?? true
 	};
 }
 //#endregion
@@ -1804,8 +1807,9 @@ init_registry();
 function runNpx(args) {
 	return new Promise((resolve, reject) => {
 		const child = spawn("npx", args, { stdio: "inherit" });
-		child.on("close", (code) => {
-			process.exitCode = code ?? 0;
+		child.on("close", (code, signal) => {
+			if (signal) process.exitCode = 128 + (constants.signals[signal] || 0);
+			else process.exitCode = code ?? 0;
 			resolve();
 		});
 		child.on("error", reject);
@@ -1824,12 +1828,13 @@ async function main() {
 		console.log(VERSION);
 		return;
 	}
-	const { timeHours, timeMs, strategy } = buildOptions(snpxFlags);
+	const { timeHours, timeMs, strategy, silent } = buildOptions(snpxFlags);
+	const logger = createLogger(silent);
 	const selfUpdate = snpxFlags.selfUpdate;
 	const unsafeSelfUpdate = snpxFlags.unsafeSelfUpdate;
 	if (selfUpdate || unsafeSelfUpdate) {
 		const unsafe = unsafeSelfUpdate;
-		console.error(`[snpx] Checking for updates${unsafe ? " (unsafe mode)" : ""}...`);
+		logger.info(`[snpx] Checking for updates${unsafe ? " (unsafe mode)" : ""}...`);
 		try {
 			const { hasUpdate, currentVersion, latestVersion } = await checkSelfUpdate();
 			if (!latestVersion) {
@@ -1837,21 +1842,20 @@ async function main() {
 				process.exit(1);
 			}
 			if (hasUpdate) {
-				console.error(`[snpx] Update available: ${currentVersion} → ${latestVersion}`);
-				console.error("[snpx] Run: npm update -g @lionad/safe-npx");
+				logger.info(`[snpx] Update available: ${currentVersion} → ${latestVersion}`);
+				logger.info("[snpx] Run: npm update -g @lionad/safe-npx");
 				if (!unsafe) {
 					const { fetchPackageMetadata } = await Promise.resolve().then(() => (init_registry(), registry_exports));
-					const { REGISTRY } = await Promise.resolve().then(() => (init_constants(), constants_exports));
 					const latestTime = ((await fetchPackageMetadata("@lionad/safe-npx")).time || {})[latestVersion];
 					if (latestTime) {
 						const age = Date.now() - new Date(latestTime).getTime();
 						if (age < timeMs) {
-							console.error(`[snpx] Warning: Latest version is only ${Math.floor(age / MS_PER_HOUR)}h old. Waiting for ${timeHours}h safety window.`);
-							console.error("[snpx] Use --unsafe-self-update to bypass (not recommended)");
+							logger.info(`[snpx] Warning: Latest version is only ${Math.floor(age / MS_PER_HOUR)}h old. Waiting for ${timeHours}h safety window.`);
+							logger.info("[snpx] Use --unsafe-self-update to bypass (not recommended)");
 						}
 					}
 				}
-			} else console.error(`[snpx] Already up to date (${currentVersion})`);
+			} else logger.info(`[snpx] Already up to date (${currentVersion})`);
 		} catch (err) {
 			console.error(`[snpx] Error checking for updates: ${err.message}`);
 			process.exit(1);
@@ -1872,19 +1876,19 @@ async function main() {
 	}
 	let version = getCachedVersion(pkgName, timeMs);
 	if (!version) {
-		console.error(`[snpx] Resolving safe version for ${pkgName}...`);
+		logger.info(`[snpx] Resolving safe version for ${pkgName}...`);
 		try {
 			version = await resolveSafeVersion(pkgName, {
 				timeMs,
 				strategy
 			});
 			setCachedVersion(pkgName, version);
-			console.error(`[snpx] Using ${pkgName}@${version} (strategy: ${strategy.join(",")}, window: ${timeHours}h)`);
+			logger.info(`[snpx] Using ${pkgName}@${version} (strategy: ${strategy.join(",")}, window: ${timeHours}h)`);
 		} catch (err) {
 			console.error(`[snpx] Error: ${err.message}`);
 			process.exit(1);
 		}
-	} else console.error(`[snpx] Using cached ${pkgName}@${version}`);
+	} else logger.info(`[snpx] Using cached ${pkgName}@${version}`);
 	if (snpxFlags.showVersion) {
 		console.log(version);
 		return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionad/safe-npx",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Safe npx wrapper - lock to latest-1 version with 24h cache",
   "type": "module",
   "bin": {