@ghini/xstart 26.1.5211744 → 26.1.6175449

package/README.md

@@ -1,47 +1,69 @@
-# 一个标准 TypeScript 2026 的 npm 库脚手架
+# TypeScript 2026 npm 库脚手架
 
-2026 版现代 TS 脚手架：基于 Node 24 原生 ESM，利用“源码直连”实现免 build 实时调试；通过 esbuild 抹除后缀并配合 publishConfig，兼顾开发爽感与发布标准，是极致紧凑的 npm 库闭环模板。
+基于 Node 24 原生 ESM，利用"源码直连"实现免 build 实时调试；通过 esbuild 抹除后缀并配合 publishConfig，兼顾开发爽感与发布标准。
 
-### 发布
+## 📦 创建新库
+
+**PowerShell (Windows)**
+
+```powershell
+$lib = "YOUR_LIB_NAME"
+git clone -b xstart git@github.com:xghini/mynpm.git $lib && cd $lib
+(Get-Content package.json) -replace 'xstart', $lib | Set-Content package.json
+(Get-Content README.md) -replace 'xstart', $lib | Set-Content README.md
+Remove-Item -Recurse -Force .git
+git init && git add . && git commit -m "init: $lib from xstart template"
+git branch -M $lib && git remote add origin git@github.com:xghini/mynpm.git
+git push -u origin $lib && pnpm i && pnpm pub
+```
+
+**Bash (Linux/macOS)**
 
 ```bash
-pnpm build       # 编译 TypeScript + 打包 + 更新版本号
-pnpm checkpub    # 检查发布内容
-pnpm pub         # 构建 + 发布到 npm + 提交 git
+lib="YOUR_LIB_NAME"
+git clone -b xstart git@github.com:xghini/mynpm.git $lib && cd $lib
+sed -i "s/xstart/$lib/g" package.json README.md
+rm -rf .git
+git init && git add . && git commit -m "init: $lib from xstart template"
+git branch -M $lib && git remote add origin git@github.com:xghini/mynpm.git
+git push -u origin $lib && pnpm i && pnpm pub
 ```
 
-## 🔧 如果需要 pnpm 迁移：
+## 🚀 开发命令
 
-```ps1
-pnpm import
-Remove-Item -Recurse -Force node_modules
-Remove-Item package-lock.json
-pnpm i
+```bash
+pnpm test          # 运行测试
+pnpm test:watch    # 监听模式
+pnpm test:coverage # 覆盖率报告
+pnpm typecheck     # 类型检查
+pnpm build         # 编译 + 打包 + 更新版本号
+pnpm pub           # 构建 + 发布 + 提交
 ```
 
-## 📦 创建新库
+## 🛠️ 内置工具
 
-全文件替换 `xstart` 为新库名：
+```typescript
+import {xpath, exefile, exedir} from '@ghini/xstart';
 
-```bash
-git clone -b xstart git@github.com:xghini/mynpm.git
-mv mynpm xstart&&cd xstart
-rm -rf .git
-Remove-Item -Recurse -Force .git
-git init
-git add .
-git commit -m "Initial commit"
-git branch -M xstart
-git remote add origin git@github.com:xghini/mynpm.git
-git push -u origin xstart
-pnpm pub
+xpath('./config.json'); // 相对于入口脚本解析路径
+xpath('../data/file.txt'); // 自动处理 ../
+xpath(); // 获取入口脚本目录
+xpath('C:/abs/path'); // 绝对路径直接返回
+xpath('file:///C:/path/file.ts'); // 自动剥离 file:/// 协议
 ```
 
-💡 核心设计说明
-源码直连：package.json 中的 exports 在开发态指向 src/\*.ts，配合 Node.js 24 --experimental-strip-types 实现保存即生效，告别 tsc --watch。
+## 💡 核心设计
 
-双模切换：利用 publishConfig 在发布时自动将入口切回 dist/\*.js，确保用户侧的兼容性。
+- **源码直连**：开发态 exports 指向 `src/*.ts`，Node 24 原生支持直接运行 TypeScript
+- **双模切换**：publishConfig 发布时自动切回 `dist/*.js`，确保兼容性
+- **自动版本**：build.js 内置日期版本算法（如 26.1.5161805）
+- **路径处理**：xpath 默认相对于入口脚本目录，支持 pm2 等场景通过 `KIT_EXEPATH` 环境变量覆盖
 
-自动版本：build.js 内部集成日期版本算法（如 26.1.5161805），无需手动维护版本号。
+## 🔧 pnpm 迁移
 
-esbuild 抹除：构建阶段自动处理 .ts 后缀映射，生成的单文件 ESM 产物极其紧凑。
+```powershell
+pnpm import
+Remove-Item -Recurse -Force node_modules
+Remove-Item package-lock.json
+pnpm i
+```

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export * from './start.ts';
+export * from './utils.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,8 +1,36 @@
-// src/start.ts
-function start() {
-  console.log("Hello Ghini use ts");
+// src/utils.ts
+import { normalize, join, isAbsolute, sep, dirname } from "node:path";
+var exefile = process.env.KIT_EXEPATH || process.env.KIT_EXEFILE || process.argv[1] || "";
+var exedir = dirname(exefile);
+function xpath(targetPath = ".", basePath = exedir, separator = "/") {
+  const stripFileProtocol = (p) => {
+    if (p.startsWith("file:///")) {
+      return process.platform === "win32" ? p.slice(8) : p.slice(7);
+    }
+    return p;
+  };
+  let resolvedBase = stripFileProtocol(basePath);
+  if (!isAbsolute(resolvedBase)) {
+    resolvedBase = join(process.cwd(), resolvedBase);
+  }
+  let result;
+  const cleanTarget = stripFileProtocol(targetPath);
+  if (isAbsolute(cleanTarget)) {
+    result = normalize(cleanTarget);
+  } else {
+    result = normalize(join(resolvedBase, cleanTarget));
+  }
+  if (separator === "/" && sep === "\\") {
+    return result.split(sep).join("/");
+  }
+  if (separator === "\\" && sep === "/") {
+    return result.split(sep).join("\\");
+  }
+  return result;
 }
 export {
-  start
+  exedir,
+  exefile,
+  xpath
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/start.ts"],
-  "sourcesContent": ["// start.ts\nexport { start };\n\nfunction start(): void {\n  console.log(\"Hello Ghini use ts\");\n}\n"],
-  "mappings": ";AAGA,SAAS,QAAc;AACrB,UAAQ,IAAI,oBAAoB;AAClC;",
+  "sources": ["../src/utils.ts"],
+  "sourcesContent": ["// src/utils.ts\nimport {normalize, join, isAbsolute, sep, dirname} from 'node:path';\n\nexport {xpath, exefile, exedir};\n\n/** \u6267\u884C\u6587\u4EF6\u8DEF\u5F84\uFF0C\u652F\u6301 pm2 \u7B49\u5DE5\u5177\u901A\u8FC7\u73AF\u5883\u53D8\u91CF\u8986\u76D6 */\nconst exefile = process.env.KIT_EXEPATH || process.env.KIT_EXEFILE || process.argv[1] || '';\n\n/** \u6267\u884C\u6587\u4EF6\u6240\u5728\u76EE\u5F55 */\nconst exedir = dirname(exefile);\n\n/**\n * \u5F3A\u5927\u53EF\u9760\u7684\u8DEF\u5F84\u5904\u7406\n * - \u76F8\u5BF9\u8DEF\u5F84\u5728\u540E\uFF0C\u7EDD\u5BF9\u8DEF\u5F84\u5728\u524D\uFF0C\u6700\u7EC8\u90FD\u8F6C\u6362\u4E3A\u7EDD\u5BF9\u8DEF\u5F84\n * - \u7EDF\u4E00\u5206\u9694\u7B26\uFF0C\u65B9\u4FBF\u6BD4\u8F83\u8DEF\u5F84\n * - \u81EA\u52A8\u5904\u7406 file:/// \u534F\u8BAE\u3001../\u88C1\u5207\u7B49\n * @param targetPath - \u76EE\u6807\u8DEF\u5F84\uFF08\u53EF\u4EE5\u662F\u76F8\u5BF9\u8DEF\u5F84\u6216\u7EDD\u5BF9\u8DEF\u5F84\uFF09\n * @param basePath - \u57FA\u51C6\u8DEF\u5F84\uFF0C\u9ED8\u8BA4\u4E3A process.cwd()\n * @param separator - \u8DEF\u5F84\u5206\u9694\u7B26\uFF0C\u9ED8\u8BA4\u4E3A '/'\n */\nfunction xpath(targetPath: string = '.', basePath: string = exedir, separator: '/' | '\\\\' = '/'): string {\n  // \u5904\u7406 file:/// \u534F\u8BAE\n  const stripFileProtocol = (p: string): string => {\n    if (p.startsWith('file:///')) {\n      // Windows: file:///C:/path \u2192 C:/path (\u53BB\u63898\u4E2A\u5B57\u7B26)\n      // Unix: file:///path \u2192 /path (\u53BB\u63897\u4E2A\u5B57\u7B26)\n      return process.platform === 'win32' ? p.slice(8) : p.slice(7);\n    }\n    return p;\n  };\n\n  // \u5904\u7406 basePath\n  let resolvedBase = stripFileProtocol(basePath);\n  if (!isAbsolute(resolvedBase)) {\n    resolvedBase = join(process.cwd(), resolvedBase);\n  }\n\n  // \u5904\u7406 targetPath\n  let result: string;\n  const cleanTarget = stripFileProtocol(targetPath);\n\n  if (isAbsolute(cleanTarget)) {\n    result = normalize(cleanTarget);\n  } else {\n    result = normalize(join(resolvedBase, cleanTarget));\n  }\n\n  // \u7EDF\u4E00\u5206\u9694\u7B26\n  if (separator === '/' && sep === '\\\\') {\n    return result.split(sep).join('/');\n  }\n  if (separator === '\\\\' && sep === '/') {\n    return result.split(sep).join('\\\\');\n  }\n  return result;\n}\n"],
+  "mappings": ";AACA,SAAQ,WAAW,MAAM,YAAY,KAAK,eAAc;AAKxD,IAAM,UAAU,QAAQ,IAAI,eAAe,QAAQ,IAAI,eAAe,QAAQ,KAAK,CAAC,KAAK;AAGzF,IAAM,SAAS,QAAQ,OAAO;AAW9B,SAAS,MAAM,aAAqB,KAAK,WAAmB,QAAQ,YAAwB,KAAa;AAEvG,QAAM,oBAAoB,CAAC,MAAsB;AAC/C,QAAI,EAAE,WAAW,UAAU,GAAG;AAG5B,aAAO,QAAQ,aAAa,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC;AAAA,IAC9D;AACA,WAAO;AAAA,EACT;AAGA,MAAI,eAAe,kBAAkB,QAAQ;AAC7C,MAAI,CAAC,WAAW,YAAY,GAAG;AAC7B,mBAAe,KAAK,QAAQ,IAAI,GAAG,YAAY;AAAA,EACjD;AAGA,MAAI;AACJ,QAAM,cAAc,kBAAkB,UAAU;AAEhD,MAAI,WAAW,WAAW,GAAG;AAC3B,aAAS,UAAU,WAAW;AAAA,EAChC,OAAO;AACL,aAAS,UAAU,KAAK,cAAc,WAAW,CAAC;AAAA,EACpD;AAGA,MAAI,cAAc,OAAO,QAAQ,MAAM;AACrC,WAAO,OAAO,MAAM,GAAG,EAAE,KAAK,GAAG;AAAA,EACnC;AACA,MAAI,cAAc,QAAQ,QAAQ,KAAK;AACrC,WAAO,OAAO,MAAM,GAAG,EAAE,KAAK,IAAI;AAAA,EACpC;AACA,SAAO;AACT;",
   "names": []
 }

package/dist/utils.d.ts

@@ -0,0 +1,16 @@
+export { xpath, exefile, exedir };
+/** 执行文件路径，支持 pm2 等工具通过环境变量覆盖 */
+declare const exefile: string;
+/** 执行文件所在目录 */
+declare const exedir: string;
+/**
+ * 强大可靠的路径处理
+ * - 相对路径在后，绝对路径在前，最终都转换为绝对路径
+ * - 统一分隔符，方便比较路径
+ * - 自动处理 file:/// 协议、../裁切等
+ * @param targetPath - 目标路径（可以是相对路径或绝对路径）
+ * @param basePath - 基准路径，默认为 process.cwd()
+ * @param separator - 路径分隔符，默认为 '/'
+ */
+declare function xpath(targetPath?: string, basePath?: string, separator?: '/' | '\\'): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAGA,OAAO,EAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAC,CAAC;AAEhC,gCAAgC;AAChC,QAAA,MAAM,OAAO,QAA8E,CAAC;AAE5F,eAAe;AACf,QAAA,MAAM,MAAM,QAAmB,CAAC;AAEhC;;;;;;;;GAQG;AACH,iBAAS,KAAK,CAAC,UAAU,GAAE,MAAY,EAAE,QAAQ,GAAE,MAAe,EAAE,SAAS,GAAE,GAAG,GAAG,IAAU,GAAG,MAAM,CAmCvG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghini/xstart",
-  "version": "26.1.5211744",
+  "version": "26.1.6175449",
   "type": "module",
   "author": "Ghini",
   "license": "MIT",
@@ -19,12 +19,19 @@
   ],
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
     "esbuild": "^0.27.2",
-    "typescript": "^5.9.3"
+    "fast-check": "^4.5.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
   },
   "scripts": {
     "build": "node ./build.js",
     "checkpub": "pnpm pack --dry-run",
-    "pub": "pnpm build && pnpm publish --no-git-checks && git add . && git commit -m 'update' && git push"
+    "pub": "pnpm build && pnpm publish --no-git-checks && git add . && git commit -m 'update' && git push",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/index.ts

@@ -1,2 +1,2 @@
 // src/index.ts
-export * from './start.ts';
+export * from './utils.ts';

package/src/utils.ts

@@ -0,0 +1,56 @@
+// src/utils.ts
+import {normalize, join, isAbsolute, sep, dirname} from 'node:path';
+
+export {xpath, exefile, exedir};
+
+/** 执行文件路径，支持 pm2 等工具通过环境变量覆盖 */
+const exefile = process.env.KIT_EXEPATH || process.env.KIT_EXEFILE || process.argv[1] || '';
+
+/** 执行文件所在目录 */
+const exedir = dirname(exefile);
+
+/**
+ * 强大可靠的路径处理
+ * - 相对路径在后，绝对路径在前，最终都转换为绝对路径
+ * - 统一分隔符，方便比较路径
+ * - 自动处理 file:/// 协议、../裁切等
+ * @param targetPath - 目标路径（可以是相对路径或绝对路径）
+ * @param basePath - 基准路径，默认为 process.cwd()
+ * @param separator - 路径分隔符，默认为 '/'
+ */
+function xpath(targetPath: string = '.', basePath: string = exedir, separator: '/' | '\\' = '/'): string {
+  // 处理 file:/// 协议
+  const stripFileProtocol = (p: string): string => {
+    if (p.startsWith('file:///')) {
+      // Windows: file:///C:/path → C:/path (去掉8个字符)
+      // Unix: file:///path → /path (去掉7个字符)
+      return process.platform === 'win32' ? p.slice(8) : p.slice(7);
+    }
+    return p;
+  };
+
+  // 处理 basePath
+  let resolvedBase = stripFileProtocol(basePath);
+  if (!isAbsolute(resolvedBase)) {
+    resolvedBase = join(process.cwd(), resolvedBase);
+  }
+
+  // 处理 targetPath
+  let result: string;
+  const cleanTarget = stripFileProtocol(targetPath);
+
+  if (isAbsolute(cleanTarget)) {
+    result = normalize(cleanTarget);
+  } else {
+    result = normalize(join(resolvedBase, cleanTarget));
+  }
+
+  // 统一分隔符
+  if (separator === '/' && sep === '\\') {
+    return result.split(sep).join('/');
+  }
+  if (separator === '\\' && sep === '/') {
+    return result.split(sep).join('\\');
+  }
+  return result;
+}

package/dist/start.d.ts

@@ -1,3 +0,0 @@
-export { start };
-declare function start(): void;
-//# sourceMappingURL=start.d.ts.map

package/dist/start.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"start.d.ts","sourceRoot":"","sources":["../src/start.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,iBAAS,KAAK,IAAI,IAAI,CAErB"}

package/src/start.ts

@@ -1,6 +0,0 @@
-// start.ts
-export { start };
-
-function start(): void {
-  console.log("Hello Ghini use ts");
-}