@lionad/safe-npx 0.2.1 → 0.2.3

package/README.md

@@ -1,81 +1,92 @@
-# safe-npx (snpx)
+<center>
+   <img src="./assets/logo.png" alt="safe-npx logo" height="300px"/>
+   <p style="margin-top: -4em;"><em><code>snpx -y pkg@latest</code> protects you from newly compromised packages</em></p>
+   <br>
+   <br>
+</center>
 
-Safe npx wrapper with configurable time-based fallback strategy.
-
-## Why
+## Why / 为什么需要
 
 `npx -y pkg@latest` installs the bleeding edge. If that version was just compromised in a supply chain attack, you get owned immediately. **snpx** intercepts `@latest` (and bare package names) and resolves a safe version based on publish age and a configurable fallback strategy. This gives the security community time to catch malicious releases.
 
-## Install
+`npx -y pkg@latest` 会直接安装最新版本。如果该版本刚被供应链攻击（Supply Chain Attack）篡改，你会立即中招。**snpx** 会拦截 `@latest`（以及裸包名），根据发布时间和可配置的回退策略（Fallback Strategy）解析出一个安全版本。这为安全社区争取了发现和处置恶意发布的时间窗口。
+
+## Install / 安装
 
 ```bash
 npm install -g @lionad/safe-npx
 ```
 
-## Usage
+## Usage / 用法
 
-Drop-in replacement for `npx`:
+Drop-in replacement for `npx` — 直接替换 `npx` 即可：
 
 ```bash
 # Instead of npx -y create-react-app@latest my-app
+# 替代 npx -y create-react-app@latest my-app
 snpx -y create-react-app@latest my-app
 
-# Works with scoped packages too
+# Works with scoped packages too / 支持带 scope 的包
 snpx -y @vue/cli@latest create my-project
 
-# Bare package names are also intercepted
+# Bare package names are also intercepted / 裸包名同样会被拦截
 snpx -y cowsay "Hello World"
+
+# Flags after the package are passed through to the tool / 包名之后的参数会透传给被执行的工具
+snpx cowsay@latest --version
 ```
 
-## How it works
+## How it works / 工作原理
 
-1. Intercepts calls containing `@latest` and bare package names
-2. Queries npm registry for the package
-3. If `latest` is older than the safety window (default 24h), uses `latest`
-4. Otherwise, falls back through the configured strategy:
-   - `patch` = version published immediately before `latest`
-   - `minor` = most recently published version of the previous minor line
-   - `major` = most recently published version of the previous major line
-5. Verifies the fallback version is also older than the safety window
-6. Caches the resolved version for the duration of the safety window
-7. Executes `npx pkg@resolved_version ...`
+1. Intercepts calls containing `@latest` and bare package names / 拦截包含 `@latest` 和裸包名的调用
+2. Queries npm registry for the package / 查询 npm registry 获取包信息
+3. If `latest` is older than the safety window (default 24h), uses `latest` / 如果 `latest` 发布时间超过安全窗口（默认 24 小时），直接使用
+4. Otherwise, falls back through the configured strategy / 否则，按配置的策略依次回退：
+   - `patch` = version published immediately before `latest` / 发布时间紧邻 `latest` 之前的版本
+   - `minor` = most recently published version of the previous minor line / 上一个 minor 线最近发布的版本
+   - `major` = most recently published version of the previous major line / 上一个 major 线最近发布的版本
+5. Verifies the fallback version is also older than the safety window / 验证回退版本也超过安全窗口
+6. Caches the resolved version for the duration of the safety window / 在安全窗口期间缓存解析结果
+7. Executes `npx pkg@resolved_version ...` / 执行 `npx pkg@resolved_version ...`
 
-## Options
+## Options / 选项
 
 ```bash
-# Configure safety window (hours)
+# Configure safety window (hours) / 配置安全窗口（小时）
 snpx --time 48 cowsay@latest
 
-# Configure fallback strategy (left-to-right precedence)
+# Configure fallback strategy (left-to-right precedence) / 配置回退策略（从左到右优先）
 snpx --fallback-strategy patch,minor,major cowsay@latest
 
-# Print resolved version without executing
+# Print resolved version without executing / 打印解析到的版本但不执行
 snpx --show-version cowsay@latest
 
-# Check for snpx updates (safe mode - respects 24h window)
+# Check for snpx updates (safe mode - respects 24h window) / 检查 snpx 自身更新（安全模式，遵守 24 小时窗口）
 snpx --self-update
 
-# Bypass safety window for self-update check (not recommended)
+# Bypass safety window for self-update check (not recommended) / 跳过安全窗口检查更新（不推荐）
 snpx --unsafe-self-update
 
-# Show help
+# Show help / 显示帮助
 snpx --help
 ```
 
-## Environment Variables
+## Environment Variables / 环境变量
 
-- `SNPX_TIME` — Default for `--time`
-- `SNPX_FALLBACK_STRATEGY` — Default for `--fallback-strategy`
+- `SNPX_TIME` — Default for `--time` / `--time` 的默认值
+- `SNPX_FALLBACK_STRATEGY` — Default for `--fallback-strategy` / `--fallback-strategy` 的默认值
 
-## Cache
+## Cache / 缓存
 
 Resolved versions are cached in `~/.cache/snpx/` for the duration of the safety window (default 24 hours). This means:
-- Fast subsequent runs (no registry requests)
-- At most one registry query per package per window
+- Fast subsequent runs (no registry requests) / 后续运行更快（无需请求 registry）
+- At most one registry query per package per window / 每个安全窗口内每个包最多一次 registry 查询
+
+## Acknowledgments / 致谢
 
-## Acknowledgments
+Inspired by [safe-npm](https://github.com/kevinslin/safe-npm) by Kevin Lin.
 
-Inspired by [safe-npm](https://github.com/kevinslin/safe-npm) by Kevin Lin. The core idea of using package age as a supply chain security signal comes from that project.
+灵感来自 Kevin Lin 的 [safe-npm](https://github.com/kevinslin/safe-npm)。
 
 ## License
 

package/package.json

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

package/snpx.js

@@ -15,35 +15,45 @@ const DEFAULT_TIME_HOURS = 24;
 const DEFAULT_FALLBACK_STRATEGY = 'patch,minor,major';
 const MS_PER_HOUR = 60 * 60 * 1000;
 
+const _tty = process.stdout.isTTY && !process.env.NO_COLOR;
+const _c = {
+  bold: (s) => _tty ? `\x1b[1m${s}\x1b[22m` : s,
+  dim: (s) => _tty ? `\x1b[2m${s}\x1b[22m` : s,
+  green: (s) => _tty ? `\x1b[32m${s}\x1b[39m` : s,
+  cyan: (s) => _tty ? `\x1b[36m${s}\x1b[39m` : s,
+  yellow: (s) => _tty ? `\x1b[33m${s}\x1b[39m` : s,
+};
+
 const HELP_TEXT = `
-safe-npx (snpx) - Safe npx wrapper with configurable fallback strategy
+${_c.bold(_c.cyan('safe-npx (snpx)'))} — Safe npx wrapper with configurable fallback strategy
 
-Usage:
-  snpx [options] <package>@latest [args...]
-  snpx [options] <package> [args...]
-  snpx [options] <command>
+${_c.bold('Usage:')}
+  ${_c.green('snpx')} [options] <package>@latest [args...]
+  ${_c.green('snpx')} [options] <package> [args...]
+  ${_c.green('snpx')} [options] <command>
 
-Options:
-  -h, --help                Show this help message
-  --time <hours>            Safety window in hours (default: 24)
-  --fallback-strategy <str> Comma-separated fallback order.
+${_c.bold('Options:')}
+  ${_c.yellow('-h, --help')}                Show this help message
+  ${_c.yellow('--time')} ${_c.dim('<hours>')}            Safety window in hours (default: 24)
+  ${_c.yellow('--fallback-strategy')} ${_c.dim('<str>')} Comma-separated fallback order.
                             Default: patch,minor,major
                             Left-to-right: first matching safe version wins.
-                            patch  = version immediately before latest
-                            minor  = most recently published version of previous minor line
-                            major  = most recently published version of previous major line
-  --show-version            Print resolved version and exit (no execution)
-  --self-update             Check for snpx updates (safe mode, default 24h)
-  --unsafe-self-update      Allow immediate snpx updates without safety window
-
-Environment Variables:
-  SNPX_TIME                 Default for --time
-  SNPX_FALLBACK_STRATEGY    Default for --fallback-strategy
-
-Examples:
-  snpx -y cowsay@latest "Hello World"
-  snpx --time 48 --fallback-strategy patch,minor cowsay@latest
-  snpx --show-version cowsay@latest
+                            ${_c.dim('patch')}  = version immediately before latest
+                            ${_c.dim('minor')}  = most recently published version of previous minor line
+                            ${_c.dim('major')}  = most recently published version of previous major line
+  ${_c.yellow('--show-version')}            Print resolved version and exit (no execution)
+  ${_c.yellow('--self-update')}             Check for snpx updates (safe mode, default 24h)
+  ${_c.yellow('--unsafe-self-update')}      Allow immediate snpx updates without safety window
+
+${_c.bold('Environment Variables:')}
+  ${_c.green('SNPX_TIME')}                 Default for --time
+  ${_c.green('SNPX_FALLBACK_STRATEGY')}    Default for --fallback-strategy
+
+${_c.bold('Examples:')}
+  ${_c.green('snpx')} -y cowsay@latest "Hello World"
+  ${_c.green('snpx')} --time 48 --fallback-strategy patch,minor cowsay@latest
+  ${_c.green('snpx')} --show-version cowsay@latest
+  ${_c.green('snpx')} cowsay@latest --version               ${_c.dim('# passes --version to cowsay')}
 `.trim();
 
 /**
@@ -64,9 +74,14 @@ export function parseSemver(version) {
 }
 
 /**
- * Parse CLI arguments.
- * Separates snpx-specific flags from npx passthrough arguments.
- * Recognizes both @latest specifiers and bare package names.
+ * Parse CLI arguments using two-phase parsing:
+ *
+ *   Phase 1 (before package): Only snpx flags accepted.
+ *     Unknown --flags → error. Single-dash flags (-y) → npx passthrough.
+ *   Phase 2 (after package): Everything is passthrough to the executed tool.
+ *
+ *   snpx [snpx-flags] <package> [tool-args...]
+ *   snpx [snpx-flags]                (--help, --self-update, etc.)
  */
 export function parseArgs(argv) {
   const args = argv.slice(2);
@@ -78,14 +93,21 @@ export function parseArgs(argv) {
     time: null,
     fallbackStrategy: null,
   };
-  const npxArgs = [];
   let pkgSpec = null;
   let pkgName = null;
-  let sawFirstPositional = false;
+  const restArgs = [];
+  let foundPackage = false;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
 
+    // Phase 2: after package name, everything is passthrough
+    if (foundPackage) {
+      restArgs.push(arg);
+      continue;
+    }
+
+    // Phase 1: before package, only known snpx flags accepted
     if (arg === '-h' || arg === '--help') {
       snpxFlags.help = true;
     } else if (arg === '--show-version') {
@@ -106,30 +128,32 @@ export function parseArgs(argv) {
       snpxFlags.fallbackStrategy = arg.slice('--fallback-strategy='.length);
     } else if (arg.startsWith('--')) {
       throw new Error(`Unknown flag: ${arg}. Run 'snpx --help' for available options.`);
+    } else if (arg.startsWith('-')) {
+      // Single-dash npx flags (e.g. -y, -p) are always passthrough
+      restArgs.push(arg);
     } else {
-      npxArgs.push(arg);
-      if (!pkgName && !sawFirstPositional) {
-        // Single-dash flags (e.g. -y) skip package detection;
-        // positional args undergo package name matching.
-        if (!arg.startsWith('-')) {
-          sawFirstPositional = true;
-          const latestMatch = arg.match(/^(@[^/]+\/[^@]+|[^@]+)@latest$/);
-          if (latestMatch) {
-            pkgSpec = arg;
-            pkgName = latestMatch[1];
-          } else {
-            const bareMatch = arg.match(/^(@[^/]+\/[^@]+|[^@]+)$/);
-            if (bareMatch) {
-              pkgSpec = arg;
-              pkgName = bareMatch[1];
-            }
-          }
+      // Positional: check if it's a package name
+      const latestMatch = arg.match(/^(@[^/]+\/[^@]+|[^@]+)@latest$/);
+      if (latestMatch) {
+        pkgSpec = arg;
+        pkgName = latestMatch[1];
+        foundPackage = true;
+      } else {
+        const bareMatch = arg.match(/^(@[^/]+\/[^@]+|[^@]+)$/);
+        if (bareMatch) {
+          pkgSpec = arg;
+          pkgName = bareMatch[1];
+          foundPackage = true;
+        } else {
+          // Not a recognized package spec (e.g. pkg@1.0.0).
+          // Stop phase 1; treat this and everything after as npx passthrough.
+          foundPackage = true;
+          restArgs.push(arg);
         }
       }
     }
   }
 
-  const restArgs = npxArgs.filter(a => a !== pkgSpec);
   return { snpxFlags, pkgSpec, pkgName, restArgs, isLatest: !!(pkgSpec && pkgSpec.includes('@latest')) };
 }
 
@@ -265,14 +289,14 @@ export async function checkSelfUpdate() {
   try {
     const data = await fetchPackageMetadata(PKG_NAME);
     const latest = data['dist-tags']?.latest;
-    if (!latest) return { hasUpdate: false, currentVersion: '0.2.1', latestVersion: null };
+    if (!latest) return { hasUpdate: false, currentVersion: '0.2.3', latestVersion: null };
 
-    const currentVersion = '0.2.1'; // Should match package.json
+    const currentVersion = '0.2.3'; // Should match package.json
     const hasUpdate = latest !== currentVersion;
 
     return { hasUpdate, currentVersion, latestVersion: latest };
   } catch {
-    return { hasUpdate: false, currentVersion: '0.2.1', latestVersion: null };
+    return { hasUpdate: false, currentVersion: '0.2.3', latestVersion: null };
   }
 }