@youngwat/upload-file 1.0.0 → 1.0.3

package/README.md

@@ -13,7 +13,7 @@
 
 ## 环境要求
 
-- Node.js >= 18.20.4
+- Node.js >= 20
 
 ## 安装
 
@@ -41,6 +41,8 @@ upload-file
 upload-file -m full
 ```
 
+> 命令同时注册了 `upload-file` 与 `uploadFile` 两个名字，敲哪个都一样。
+
 ## 配置文件
 
 ### ftp.config.json —— 上传范围
@@ -224,6 +226,24 @@ npm run release -- --set-token --token npm_xxxxxxxx
 > 想继续用 granular token，就重新生成一个并勾选 **Bypass 2FA**，Permissions 给 `Read and write`。
 > 另外 `npm publish --dry-run`（脚本的 `--dry-run`）**不会**校验发布权限，试跑通过不代表能发，403 只有在真正 publish 时才暴露。
 
+### 版本号规则（脚本会强制校验）
+
+发布脚本在打包前会校验版本号，以下情况会被直接拦下，避免发出无效包：
+
+| 输入 | 结果 |
+| --- | --- |
+| `1.0.0`、`0.1.2`、`1.0.0-alpha`、`1.2.3-beta.1` | ✅ 接受，原样写入 |
+| `v1.0.0` | ✅ 接受，自动剥掉 `v` 前缀 |
+| `0.0.0`、`0.0.0-stage` | ❌ 拒绝（占位版本，只会发成空壳包） |
+| `1.0`、`01.0.0`、`1.0.0.0`、`abc` | ❌ 拒绝（不是合法 semver） |
+
+脚本**不会**静默改写你输入的版本号语义。
+
+另外两点提醒：
+
+- **预发布标签**：`1.0.0-beta.1` 这类版本默认会占用 `latest`，想避开就手动 `npm publish --tag next`。
+- **build metadata**：`1.2.3-rc.2+build.5` 里的 `+build.5` 会被 `npm version` 丢弃（npm 自身行为），最终版本号是 `1.2.3-rc.2`。
+
 ## License
 
 [MIT](./LICENSE)

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@youngwat/upload-file",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "基于 MD5 缓存的 FTP / SFTP 增量部署 CLI，支持全量/增量与私钥认证",
   "bin": {
-    "upload-file": "src/uploadFile.js"
+    "upload-file": "src/uploadFile.js",
+    "uploadFile": "src/uploadFile.js"
   },
   "files": [
     "src/uploadFile.js",
@@ -20,7 +21,7 @@
     "pack:check": "npm pack --dry-run"
   },
   "engines": {
-    "node": ">=18.20.4"
+    "node": ">=20"
   },
   "publishConfig": {
     "access": "public",
@@ -39,7 +40,7 @@
   "license": "MIT",
   "dependencies": {
     "ftp-deploy": "^2.4.7",
-    "glob": "^10.5.0",
+    "glob": "^11.1.0",
     "ssh2-sftp-client": "^12.1.1"
   },
   "overrides": {

package/release/release.js

@@ -213,10 +213,82 @@ function applyNewToken(token) {
  * ───────────────────────────────────────────── */
 
 const BUMPS = ["patch", "minor", "major"];
-const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+
+/**
+ * 严格 semver 校验（对齐 node-semver 语法）。
+ * 上一版正则写错了，把 1.2.3-beta.1 这种合法预发布误判为非法，
+ * 同时放过了 0.0.0-stage 这种「占位版本」（曾导致发空壳包出去）。
+ */
+const NUM = "(?:0|[1-9]\\d*)";
+const PRE = "(?:\\d*[A-Za-z-][0-9A-Za-z-]*|0|[1-9]\\d*)";
+const BUILD = "[0-9A-Za-z-]+";
+const SEMVER_RE = new RegExp(
+  `^(${NUM})\\.(${NUM})\\.(${NUM})(?:-(${PRE}(?:\\.${PRE})*))?(?:\\+(${BUILD}(?:\\.${BUILD})*))?$`
+);
+
+function isStrictSemver(v) {
+  return SEMVER_RE.test(v);
+}
+
+/**
+ * 版本号诊断：区分「合法」「占位版本」「语法错误」。
+ * 0.0.0 与 0.0.0-* 语法合法但几乎肯定是占位包，单独拦一道。
+ */
+function classifyVersion(v) {
+  const m = SEMVER_RE.exec(v);
+  if (!m) return { ok: false, reason: "syntax" };
+  const [major, minor, patch] = [m[1], m[2], m[3]];
+  if (major === "0" && minor === "0" && patch === "0") {
+    return { ok: false, reason: "placeholder" };
+  }
+  return { ok: true, version: v };
+}
+
+/**
+ * 把用户输入校验成合法 semver。
+ * 刻意**不做静默改写**：曾考虑把 1.2.3-beta 自动补成 1.2.3-beta.1，
+ * 但那会把用户明确输入的 1.0.0-alpha 也改成 1.0.0-alpha.1，
+ * 属于未经同意篡改版本语义。这里只接受或拒绝，并在有风险时给出提示。
+ */
+function normalizeVersionInput(input) {
+  if (input === undefined || input === null || String(input).trim() === "") return null;
+  const raw = String(input).trim().replace(/^v/i, "");
+  const result = classifyVersion(raw);
+
+  if (!result.ok) {
+    if (result.reason === "placeholder") {
+      fail(
+        `版本号 ${raw} 是占位版本，不能用于正式发布`,
+        "0.0.0 及 0.0.0-* 只会把包发成空壳/占位，请用 1.0.0 起步，例如: npm run release 1.0.0"
+      );
+    }
+    fail(
+      `"${input}" 不是合法的 semver 版本号`,
+      "正确写法是 主.次.修订，例如 1.0.0；预发布写成 1.2.3-beta.1（版本段不能省，如 1.0 应写 1.0.0）"
+    );
+  }
+
+  // 预发布版本默认会被打成 latest 标签，容易让用户装上未稳定版本，提前提醒
+  const pre = /-([0-9A-Za-z.-]+)$/.exec(result.version);
+  if (pre) {
+    warn(`这是预发布版本（-${pre[1]}），默认会占用 latest 标签`);
+    console.log(C.dim("      要避免，改成: npm publish --tag next（或先发正式版）"));
+  }
+
+  return result.version;
+}
 
 function parseArgs(argv) {
-  const out = { bump: null, yes: false, dryRun: false, login: false, help: false, token: null, setToken: false };
+  const out = {
+    bump: null,
+    versionInput: null,
+    yes: false,
+    dryRun: false,
+    login: false,
+    help: false,
+    token: null,
+    setToken: false,
+  };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--token") {
@@ -225,13 +297,24 @@ function parseArgs(argv) {
       out.token = value;
       out.setToken = true;
       i++;
-    } else if (BUMPS.includes(arg) || SEMVER_RE.test(arg)) out.bump = arg;
-    else if (arg === "-y" || arg === "--yes") out.yes = true;
-    else if (arg === "--dry-run") out.dryRun = true;
-    else if (arg === "--login") out.login = true;
-    else if (arg === "--set-token") out.setToken = true;
-    else if (arg === "-h" || arg === "--help") out.help = true;
-    else fail(`未知参数 ${arg}`, "node release/release.js [patch|minor|major|<版本号>] [-y] [--dry-run] [--login] [--set-token]");
+    } else if (BUMPS.includes(arg)) {
+      out.bump = arg;
+    } else if (arg === "-y" || arg === "--yes") {
+      out.yes = true;
+    } else if (arg === "--dry-run") {
+      out.dryRun = true;
+    } else if (arg === "--login") {
+      out.login = true;
+    } else if (arg === "--set-token") {
+      out.setToken = true;
+    } else if (arg === "-h" || arg === "--help") {
+      out.help = true;
+    } else if (arg.startsWith("-")) {
+      fail(`未知参数 ${arg}`, "用 --help 查看用法");
+    } else {
+      // 任意非选项参数都当版本号处理，后面严格校验，绝不静默忽略
+      out.versionInput = arg;
+    }
   }
   return out;
 }
@@ -244,7 +327,7 @@ const HELP = `
 
 版本（可选）:
   patch | minor | major      按语义化版本自增
-  1.2.3                      直接指定版本号（也支持 1.2.3-beta.1）
+  1.2.3                      直接指定版本号（预发布写作 1.2.3-beta.1）
 
 选项:
   -y, --yes       跳过二次确认
@@ -304,6 +387,38 @@ function assertPackageName(pkg) {
     fail("package.json 缺少 files 白名单", "没有白名单会把本地配置、测试产物一起发出去");
   }
   ok(`files 白名单 ${pkg.files.length} 项`);
+
+  // 白名单里的路径必须真实存在，否则会被静默忽略（曾出现过占位包只发 2 个文件的情况）
+  const missingFiles = pkg.files.filter((f) => !fs.existsSync(path.join(ROOT, f)));
+  if (missingFiles.length > 0) {
+    fail(`files 白名单里的路径不存在:\n      ${missingFiles.join("\n      ")}`);
+  }
+  ok("白名单路径全部存在");
+
+  // bin 入口必须存在且带 shebang，否则用户装完敲命令就是 MODULE_NOT_FOUND
+  if (!pkg.bin || Object.keys(pkg.bin).length === 0) {
+    fail("package.json 缺少 bin 字段", "CLI 包没有 bin 就不会注册命令");
+  }
+  for (const [cmd, rel] of Object.entries(pkg.bin)) {
+    const abs = path.join(ROOT, rel);
+    if (!fs.existsSync(abs)) fail(`bin "${cmd}" 指向的文件不存在: ${rel}`);
+    const head = fs.readFileSync(abs, "utf8").split("\n")[0];
+    if (!head.startsWith("#!")) warn(`bin "${cmd}" 的文件缺少 shebang（Unix 下可能无法直接执行）`);
+  }
+  ok(`bin 入口正常: ${Object.entries(pkg.bin).map(([c, f]) => `${c} → ${f}`).join(", ")}`);
+
+  const verCheck = classifyVersion(pkg.version);
+  if (!verCheck.ok) {
+    fail(
+      verCheck.reason === "placeholder"
+        ? `当前版本号 ${pkg.version} 是占位版本，不能发布`
+        : `版本号 ${pkg.version} 不是合法 semver`,
+      verCheck.reason === "placeholder"
+        ? "先跑: npm run release 1.0.0"
+        : "例如 1.0.0 或 1.0.0-beta.1"
+    );
+  }
+  ok(`版本号 ${pkg.version} 合法`);
 }
 
 function assertGitClean() {
@@ -359,13 +474,26 @@ function assertLoggedIn(autoLogin, dryRun) {
   );
 }
 
-function bumpVersion(bump) {
-  if (!bump) return;
-  step(`调整版本号 (${bump})`);
+function bumpVersion(opts) {
+  if (!opts.bump && !opts.versionInput) return;
+  step("调整版本号");
   const before = readPkg().version;
-  const r = runCapture("npm", ["version", bump, "--no-git-tag-version"]);
-  if (r.status !== 0) fail(`npm version ${bump} 失败: ${r.stderr || r.stdout}`);
+  const args = ["version", "--no-git-tag-version"];
+  if (opts.versionInput) {
+    const safe = normalizeVersionInput(opts.versionInput);
+    if (safe !== opts.versionInput.trim().replace(/^v/, "")) {
+      warn(`版本号已归一化为合法 semver: ${opts.versionInput} → ${safe}`);
+    }
+    args.push(safe);
+  } else {
+    args.push(opts.bump);
+  }
+  const r = runCapture("npm", args);
+  if (r.status !== 0) fail(`npm version 失败: ${r.stderr || r.stdout}`);
   const after = readPkg().version;
+  if (!isStrictSemver(after)) {
+    fail(`package.json 里的版本号 ${after} 不是合法 semver`, "手动改回 1.0.0 之类的合法值再试");
+  }
   ok(`版本号 ${before} → ${after}`);
 }
 
@@ -489,7 +617,7 @@ async function main() {
   }
 
   assertPackageName(readPkg());
-  bumpVersion(opts.bump);
+  bumpVersion(opts);
   const pkg = readPkg();
 
   assertGitClean();