@oclif/core 3.0.5 → 3.0.6

package/README.md

@@ -1,5 +1,4 @@
-@oclif/core
-===========
+# @oclif/core
 
 base library for oclif CLIs
 
@@ -7,9 +6,7 @@ base library for oclif CLIs
 [![Downloads/week](https://img.shields.io/npm/dw/@oclif/core.svg)](https://npmjs.org/package/@oclif/core)
 [![License](https://img.shields.io/npm/l/@oclif/core.svg)](https://github.com/oclif/core/blob/main/package.json)
 
-
-Migrating
-=====
+# Migrating
 
 See the [v3 migration guide](./guides/V3_MIGRATION.md) for an overview of breaking changes that occurred between v2 and v3.
 
@@ -17,19 +14,18 @@ See the [v2 migration guide](./guides/V2_MIGRATION.md) for an overview of breaki
 
 Migrating from `@oclif/config` and `@oclif/command`? See the [v1 migration guide](./guides/PRE_CORE_MIGRATION.md).
 
-CLI UX
-=====
+# CLI UX
 
 The [ux README](./src/cli-ux/README.md) contains detailed usage examples of using the `ux` export.
 
-Usage
-=====
+# Usage
 
 We strongly encourage you generate an oclif CLI using the [oclif cli](https://github.com/oclif/oclif). The generator will generate an npm package with `@oclif/core` as a dependency.
 
 You can, however, use `@oclif/core` in a standalone script like this:
+
 ```typescript
-#!/usr/bin/env ts-node
+#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
 
 import * as fs from 'fs'
 import {Command, Flags, flush, handle} from '@oclif/core'
@@ -54,11 +50,14 @@ class LS extends Command {
   }
 }
 
-LS.run().then(async () => {
-  await flush()
-}, async (err) => {
-  await handle(err)
-})
+LS.run().then(
+  async () => {
+    await flush()
+  },
+  async (err) => {
+    await handle(err)
+  },
+)
 ```
 
 Then run it like this:

package/lib/config/ts-node.js

@@ -86,6 +86,10 @@ function registerTSNode(root) {
             sourceMap: tsconfig.compilerOptions.sourceMap ?? true,
             target: tsconfig.compilerOptions.target ?? 'es2019',
             typeRoots,
+            ...(tsconfig.compilerOptions.moduleResolution
+                ? { moduleResolution: tsconfig.compilerOptions.moduleResolution }
+                : {}),
+            ...(tsconfig.compilerOptions.jsx ? { jsx: tsconfig.compilerOptions.jsx } : {}),
         },
         cwd: root,
         esm: tsconfig['ts-node']?.esm ?? true,
@@ -95,18 +99,67 @@ function registerTSNode(root) {
         skipProject: true,
         transpileOnly: true,
     };
-    if (tsconfig.compilerOptions.moduleResolution) {
-        // @ts-expect-error TSNode.RegisterOptions.compilerOptions is typed as a plain object
-        conf.compilerOptions.moduleResolution = tsconfig.compilerOptions.moduleResolution;
-    }
-    if (tsconfig.compilerOptions.jsx) {
-        // @ts-expect-error TSNode.RegisterOptions.compilerOptions is typed as a plain object
-        conf.compilerOptions.jsx = tsconfig.compilerOptions.jsx;
-    }
     tsNode.register(conf);
     REGISTERED.add(root);
     return tsconfig;
 }
+/**
+ * Skip ts-node registration for ESM plugins in production.
+ * The node ecosystem is not mature enough to support auto-transpiling ESM modules at this time.
+ * See the following:
+ * - https://github.com/TypeStrong/ts-node/issues/1791#issuecomment-1149754228
+ * - https://github.com/nodejs/node/issues/49432
+ * - https://github.com/nodejs/node/pull/49407
+ * - https://github.com/nodejs/node/issues/34049
+ *
+ * We still register ts-node for ESM plugins when NODE_ENV is "test" or "development" and root plugin is also ESM
+ * since that allows plugins to be auto-transpiled when developing locally using `bin/dev.js`.
+ */
+function cannotTranspileEsm(root, plugin, isProduction) {
+    return (isProduction || ROOT_PLUGIN?.moduleType === 'commonjs') && plugin?.moduleType === 'module';
+}
+/**
+ * If the dev script is run with ts-node for an ESM plugin, skip ts-node registration
+ * and fall back on compiled source since ts-node executable cannot transpile ESM in Node 20+
+ *
+ * See the following:
+ * https://nodejs.org/en/blog/announcements/v20-release-announce#custom-esm-loader-hooks-nearing-stable
+ * https://github.com/oclif/core/issues/817
+ * https://github.com/TypeStrong/ts-node/issues/1997
+ */
+function cannotUseTsNode(root, plugin, isProduction) {
+    if (plugin?.moduleType !== 'module' || isProduction)
+        return false;
+    const nodeMajor = Number.parseInt(process.version.replace('v', '').split('.')[0], 10);
+    const tsNodeExecIsUsed = process.execArgv[0] === '--require' && process.execArgv[1].split(node_path_1.sep).includes(`ts-node`);
+    return tsNodeExecIsUsed && nodeMajor >= 20;
+}
+/**
+ * Determine the path to the source file from the compiled ./lib files
+ */
+function determinePath(root, orig) {
+    const tsconfig = registerTSNode(root);
+    if (!tsconfig)
+        return orig;
+    const { outDir, rootDir, rootDirs } = tsconfig.compilerOptions;
+    const rootDirPath = rootDir || (rootDirs || [])[0];
+    if (!rootDirPath || !outDir)
+        return orig;
+    // rewrite path from ./lib/foo to ./src/foo
+    const lib = (0, node_path_1.join)(root, outDir); // ./lib
+    const src = (0, node_path_1.join)(root, rootDirPath); // ./src
+    const relative = (0, node_path_1.relative)(lib, orig); // ./commands
+    // For hooks, it might point to a js file, not a module. Something like "./hooks/myhook.js" which doesn't need the js.
+    const out = (0, node_path_1.join)(src, relative).replace(/\.js$/, ''); // ./src/commands
+    // this can be a directory of commands or point to a hook file
+    // if it's a directory, we check if the path exists. If so, return the path to the directory.
+    // For hooks, it might point to a module, not a file. Something like "./hooks/myhook"
+    // That file doesn't exist, and the real file is "./hooks/myhook.ts"
+    // In that case we attempt to resolve to the filename. If it fails it will revert back to the lib path
+    if ((0, node_fs_1.existsSync)(out) || (0, node_fs_1.existsSync)(out + '.ts'))
+        return out;
+    return orig;
+}
 function tsPath(root, orig, plugin) {
     if (plugin?.isRoot)
         ROOT_PLUGIN = plugin;
@@ -119,51 +172,24 @@ function tsPath(root, orig, plugin) {
         return orig;
     }
     const isProduction = (0, util_1.isProd)();
-    /**
-     * Skip ts-node registration for ESM plugins.
-     * The node ecosystem is not mature enough to support auto-transpiling ESM modules at this time.
-     * See the following:
-     * - https://github.com/TypeStrong/ts-node/issues/1791#issuecomment-1149754228
-     * - https://github.com/nodejs/node/issues/49432
-     * - https://github.com/nodejs/node/pull/49407
-     * - https://github.com/nodejs/node/issues/34049
-     *
-     * We still register ts-node for ESM plugins when NODE_ENV is "test" or "development" and root plugin is also ESM.
-     * In other words, this allows plugins to be auto-transpiled when developing locally using `bin/dev.js`.
-     */
-    if ((isProduction || ROOT_PLUGIN?.moduleType === 'commonjs') && plugin?.moduleType === 'module') {
+    if (cannotTranspileEsm(root, plugin, isProduction)) {
         debug(`Skipping ts-node registration for ${root} because it's an ESM module (NODE_ENV: ${process.env.NODE_ENV}, root plugin module type: ${ROOT_PLUGIN?.moduleType})))`);
-        if (plugin.type === 'link')
-            (0, errors_1.memoizedWarn)(`${plugin.name} is a linked ESM module and cannot be auto-transpiled. Existing compiled source will be used instead.`);
+        if (plugin?.type === 'link')
+            (0, errors_1.memoizedWarn)(`${plugin?.name} is a linked ESM module and cannot be auto-transpiled. Existing compiled source will be used instead.`);
         return orig;
     }
     if (settings_1.settings.tsnodeEnabled === undefined && isProduction && plugin?.type !== 'link') {
         debug(`Skipping ts-node registration for ${root} because NODE_ENV is NOT "test" or "development"`);
         return orig;
     }
-    try {
-        const tsconfig = registerTSNode(root);
-        if (!tsconfig)
-            return orig;
-        const { outDir, rootDir, rootDirs } = tsconfig.compilerOptions;
-        const rootDirPath = rootDir || (rootDirs || [])[0];
-        if (!rootDirPath || !outDir)
-            return orig;
-        // rewrite path from ./lib/foo to ./src/foo
-        const lib = (0, node_path_1.join)(root, outDir); // ./lib
-        const src = (0, node_path_1.join)(root, rootDirPath); // ./src
-        const relative = (0, node_path_1.relative)(lib, orig); // ./commands
-        // For hooks, it might point to a js file, not a module. Something like "./hooks/myhook.js" which doesn't need the js.
-        const out = (0, node_path_1.join)(src, relative).replace(/\.js$/, ''); // ./src/commands
-        // this can be a directory of commands or point to a hook file
-        // if it's a directory, we check if the path exists. If so, return the path to the directory.
-        // For hooks, it might point to a module, not a file. Something like "./hooks/myhook"
-        // That file doesn't exist, and the real file is "./hooks/myhook.ts"
-        // In that case we attempt to resolve to the filename. If it fails it will revert back to the lib path
-        if ((0, node_fs_1.existsSync)(out) || (0, node_fs_1.existsSync)(out + '.ts'))
-            return out;
+    if (cannotUseTsNode(root, plugin, isProduction)) {
+        debug(`Skipping ts-node registration for ${root} because ts-node is run in node version ${process.version}"`);
+        (0, errors_1.memoizedWarn)(`ts-node executable cannot transpile ESM in Node 20. Existing compiled source will be used instead. See https://github.com/oclif/core/issues/817.`);
         return orig;
     }
+    try {
+        return determinePath(root, orig);
+    }
     catch (error) {
         debug(error);
         return orig;

package/lib/execute.d.ts

@@ -7,7 +7,7 @@ import { LoadOptions } from './interfaces';
  *
  * @example For ESM dev.js
  * ```
- * #!/usr/bin/env ts-node
+ * #!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
  * async function main() {
  *   const oclif = await import('@oclif/core')
  *   await oclif.execute({development: true, dir: import.meta.url})

package/lib/execute.js

@@ -13,7 +13,7 @@ const settings_1 = require("./settings");
  *
  * @example For ESM dev.js
  * ```
- * #!/usr/bin/env ts-node
+ * #!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning
  * async function main() {
  *   const oclif = await import('@oclif/core')
  *   await oclif.execute({development: true, dir: import.meta.url})

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oclif/core",
   "description": "base library for oclif CLIs",
-  "version": "3.0.5",
+  "version": "3.0.6",
   "author": "Salesforce",
   "bugs": "https://github.com/oclif/core/issues",
   "dependencies": {