@morlay/dsh-oxc-node 0.0.0-stage → 0.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 morlay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @morlay/dsh-oxc-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**本仓库的 TS 运行时入口**：注册 Node 的 module hooks，让 `node_modules` 下的 `.ts` 也能直接跑（ESM only）。
+
+为什么需要它：Node 内建的 type stripping 拒绝对 `node_modules` 里的文件动手，而 `@oxc-node/core` 也刻意
+放行那类文件（转译本身当然能做，只是那层策略不放）。这里自己注册 hooks、直接调 `oxc-transform`，
+于是"源码面"（`exports` 指向 `src/*.ts` 的包）在壳与宿主里都能直接加载。
+
+## 用法
+
+```
+node --import <本包>/register.mjs <入口>
+```
+
+- **壳**不直接依赖它：随包运行时（`<Resources>/runtime/loader`）里放着一份，壳按**路径**把它交给宿主
+  与子进程（见 `packages/desktop/dsh-desktop-shell/src/index.ts` 的 `loader`）；
+- **工具**（`@local/dshdev`）依赖它，并在备 runtime 时把这一份连同它的依赖层一起拷进
+  `<buildCache>/runtime/loader`（见 `devpackages/dshdev/src/cli/prepare-runtime.ts` 的 `prepareLoader`）。
+
+依赖方向因此是"**devpackages → packages**"：`@local/*` 只出现在工具链里，不落到任何发布包的运行时依赖上。

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@morlay/dsh-oxc-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.6",
+  "description": "本仓库的 TS 运行时入口：注册 hooks 后 Node 也能跑 node_modules 下的 .ts（ESM only）。壳与宿主按路径取用（工具把它装进随包运行时）。",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "loader",
+    "oxc",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "morlay",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morlay/dsh-plugin.git"
+  },
+  "files": [
+    "register.mjs"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./register.mjs"
+  },
+  "dependencies": {
+    "@oxc-project/runtime": "^0.154.0",
+    "oxc-transform": "^0.154.0"
+  },
+  "engines": {
+    "node": ">=24.11.0"
+  }
 }

package/register.mjs

@@ -0,0 +1,84 @@
+/**
+ * 让 Node 也能跑 `node_modules` 下的 `.ts`。
+ *
+ * Node 内建的 type stripping **拒绝对 `node_modules` 里的文件**做剥离
+ * （`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`），而 `@oxc-node/core/register` 也**刻意放行**那类文件
+ * （它把 Node 判成 `commonjs-typescript` 的 `.ts` 原样交给 Node，好让报错来自 Node 而不是它）。但**转译
+ * 本身**当然能做：这里自己注册 hooks（`registerHooks`，同步钩子），对 `.ts` 直接调 `oxc-transform`——
+ * 转译器还是 oxc，只是不再经过"给不给 node_modules 转"的那层策略。
+ *
+ * 为什么不用 `@oxc-node/core`：它的 `OxcTransformer` 没法配 target（`setTsconfigPath()` 要求"第一次
+ * transform/resolve 之前"调用，而加载它自己就已经过了那个时机；`cwd` 与环境变量都不决定 target），默认
+ * target 低到不支持顶层 await。独立的 `oxc-transform` 可以直接给 `target: "esnext"`。
+ *
+ * 也为什么不用内建的 `stripTypeScriptTypes`：它只有 `mode: "strip"`（`transform` 已移除），处理不了
+ * `enum` / `namespace` / 参数属性这些非可擦除语法。
+ *
+ * **为什么是 `.mjs` 而不是 `.ts`**：它自己就是"让 Node 能跑 TS"的那一步，写成 TS 就自举了。
+ *
+ * 用法：随进程启动挂上（壳的入口 `import` 它；宿主用 `--import`），本模块只做注册、没有导出。
+ */
+import { readFileSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { fileURLToPath } from "node:url";
+import { transformSync } from "oxc-transform";
+
+/** 排查用：`DSH_TS_DEBUG=1` 时把"挂上/转译了哪个"打到 stderr（平时安静）。 */
+const debug = process.env.DSH_TS_DEBUG === "1";
+if (debug) process.stderr.write(`[ts-register] 已挂载 pid=${String(process.pid)}\n`);
+
+registerHooks({
+  load(url, context, nextLoad) {
+    if (!url.startsWith("file:") || !url.endsWith(".ts")) return nextLoad(url, context);
+    if (debug) process.stderr.write(`[ts-register] 转译 ${url.slice(7)}\n`);
+    const path = fileURLToPath(url);
+    // oxlint-disable-next-line node/no-sync -- `registerHooks` 的 load 钩子必须同步返回。
+    const original = readFileSync(path, "utf8");
+    // oxlint-disable-next-line node/no-sync -- 钩子契约要求同步。
+    const result = transformSync(path, original, {
+      sourcemap: false,
+      // `es2022`：装饰器要在这里降级（`esnext` 会把 `@dec` 原样留着，而 Node 不认它——报出来是一句没头没尾
+      // 的 `SyntaxError: Invalid or unexpected token`）；顶层 await 在 es2022 就有，保得住。
+      target: "es2022",
+      // 装饰器：dsh 用的是 legacy 装饰器（`experimentalDecorators`），oxc 要显式开才会转；`@Remote` 这类
+      // 原样留着就是上面那句语法错。
+      decorator: { legacy: true },
+      // helper 用默认形态：输出 `@oxc-project/runtime/helpers/<name>` 这种子出口（那个包只导出
+      // `./helpers/*`）。显式写 `helpers: { mode: "Runtime" }` 反而会引到它的**根**导出处而解析失败。
+    });
+    if (result.errors.length > 0) {
+      const detail = result.errors.map((e) => e.message).join("; ");
+      // 上游把 import 失败吞成一句 "failed to import"，所以这里直接打到 stderr——否则看不见真正的原因。
+      process.stderr.write(`[ts-register] 转译失败 ${path}: ${detail}\n`);
+      throw new Error(`ts-register: ${path}: ${detail}`);
+    }
+    // 一律按 ESM 交回 Node：这条链要跑的 `.ts`（上游经 `exports` 指到 `src` 的那些）都是 ESM 源码，
+    // 而它们的 `package.json` 未必带 `type: "module"`——按包类型去判会把 ESM 代码当 CJS 载入，
+    // 报出来是一句没头没尾的 `SyntaxError: Invalid or unexpected token`。
+    const format = "module";
+    // 装饰器 helper 的 specifier 是相对**被转译的文件**解析的，而那些文件（上游包）身边没有
+    // `@oxc-project/runtime`。这里把它解析成绝对 URL（按 loader 自己的解析面）——不能直接拼目录，
+    // 那个包的 helper 名字经 `exports` 映射到 `src/helpers/*.js`。
+    const code = result.code.replace(
+      /(["'])(@oxc-project\/runtime\/[^"']+)\1/gu,
+      (whole, quote, specifier) => {
+        try {
+          return `${quote}${import.meta.resolve(specifier)}${quote}`;
+        } catch {
+          return whole;
+        }
+      },
+    );
+    // `map` 可能是字符串，也可能是 sourcemap 对象——两种都要能带上（栈里才指向原文件）。
+    const map =
+      result.map === undefined || result.map === null ? undefined : JSON.stringify(result.map);
+    return {
+      format,
+      source:
+        map === undefined
+          ? code
+          : `${code}\n//# sourceMappingURL=data:application/json;charset=utf-8;base64,${Buffer.from(map, "utf8").toString("base64")}`,
+      shortCircuit: true,
+    };
+  },
+});