@fynjs/run 1.1.0 → 1.1.2

package/dist/cli/search-up-task-file.js

@@ -0,0 +1,79 @@
+import Path from "path";
+import Fs from "fs";
+import config from "./config.js";
+/*
+ * Look for xrun file at xrunDir
+ * Search up each directory if `search` is true
+ * Until a file "package.json" is found or top is reached
+ */
+function searchUpTaskFile(xrunDir, search) {
+    let result;
+    let dir = xrunDir;
+    do {
+        result = findTaskFile(dir);
+        // If we found a task file or package.json, stop searching
+        if (result.found || result.foundPkg) {
+            break;
+        }
+        // If we're not searching up or we've hit the root, stop
+        if (!search)
+            break;
+        const tmp = Path.join(dir, "..");
+        if (!tmp || tmp === "." || tmp === dir) {
+            break;
+        }
+        dir = tmp;
+    } while (true);
+    // If we didn't find a task file, use the original directory
+    if (!result.found) {
+        result.dir = xrunDir;
+    }
+    return result;
+}
+function findTaskFile(xrunDir) {
+    const dirFiles = Fs.readdirSync(xrunDir);
+    const files = config.search;
+    // First check the root directory
+    let xrunFile;
+    files.find(n => (xrunFile = dirFiles.find(f => f.startsWith(n))));
+    // If found in root, return it
+    if (xrunFile) {
+        const foundPkg = Boolean(dirFiles.find(f => f === "package.json"));
+        return {
+            found: true,
+            foundPkg,
+            xrunFile: Path.join(xrunDir, xrunFile),
+            dir: xrunDir
+        };
+    }
+    // If not found in root, check subdirectories: scripts/, tools/, build/, tasks/
+    const subDirs = ["scripts", "tools", "build", "tasks"];
+    for (const subDir of subDirs) {
+        const subDirPath = Path.join(xrunDir, subDir);
+        try {
+            const subDirFiles = Fs.readdirSync(subDirPath);
+            files.find(n => (xrunFile = subDirFiles.find(f => f.startsWith(n))));
+            if (xrunFile) {
+                const foundPkg = Boolean(dirFiles.find(f => f === "package.json"));
+                return {
+                    found: true,
+                    foundPkg,
+                    xrunFile: Path.join(subDirPath, xrunFile),
+                    dir: xrunDir
+                };
+            }
+        }
+        catch (err) {
+            // Subdirectory doesn't exist or can't be read, skip it
+        }
+    }
+    // Not found anywhere
+    const foundPkg = Boolean(dirFiles.find(f => f === "package.json"));
+    return {
+        found: false,
+        foundPkg,
+        xrunFile: undefined,
+        dir: xrunDir
+    };
+}
+export { searchUpTaskFile, findTaskFile };

package/dist/cli/task-file.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Update the current working directory
+ * @param {string} [dir] - Directory to change to
+ * @returns {string} New working directory
+ */
+declare function updateCwd(dir: any): any;
+/**
+ * Search for task files in the given directory
+ * @param {boolean} search - Whether to search up directories
+ * @param {ParseOptions} opts - Search options
+ * @returns {SearchResult} Search result
+ */
+declare function searchTaskFile(search: any, opts: any): any;
+/**
+ * Load a task file.
+ *
+ * Loading goes through `import()` rather than `require`, which is what lets a task file use
+ * top-level await - node's `require(esm)` refuses that graph outright and always will. Every
+ * other format keeps working: `import()` of a CommonJS file yields a namespace with
+ * `module.exports` on `.default`, which processTasks already unwraps.
+ *
+ * @param {string} name - Path to the task file
+ * @returns {Promise<Object|Function|undefined>} Loaded task module, or undefined if it failed
+ */
+declare function loadTaskFile(name: any): Promise<any>;
+/**
+ * Process loaded tasks and register them with xrun
+ * @param {Object|Function} tasks - Tasks to process
+ * @param {string} loadMsg - Message to display when tasks are loaded
+ * @param {string} [ns="xrun"] - Namespace to load tasks into
+ */
+declare function processTasks(tasks: any, loadMsg: any, ns?: string): void;
+/**
+ * Load tasks from files or required modules
+ * @param {ParseOptions} opts - Options for loading tasks
+ * @param {SearchResult} searchResult - Result from searching for task files
+ * @returns {boolean} Whether any tasks were loaded
+ */
+declare function loadTasks(opts: any, searchResult: any): Promise<boolean>;
+export { updateCwd, searchTaskFile, loadTaskFile, processTasks, loadTasks };

package/dist/cli/task-file.js

@@ -0,0 +1,177 @@
+import { pathToFileURL } from "node:url";
+import Path from "path";
+import env from "./env.js";
+import xsh from "xsh";
+import logger from "../lib/logger.js";
+import config from "./config.js";
+import ck from "./ck.js";
+import { searchUpTaskFile } from "./search-up-task-file.js";
+import WrapProcess from "./wrap-process.js";
+import { createRequire } from "node:module";
+import npmLoader from "./npm-loader.js";
+import instance from "../lib/xrun-instance.js";
+import TsRunner from "./ts-runner.js";
+/**
+ * Update the current working directory
+ * @param {string} [dir] - Directory to change to
+ * @returns {string} New working directory
+ */
+function updateCwd(dir) {
+    dir = dir || WrapProcess.cwd();
+    const newCwd = Path.isAbsolute(dir) ? dir : Path.resolve(dir);
+    try {
+        const cwd = WrapProcess.cwd();
+        if (newCwd !== cwd) {
+            WrapProcess.chdir(newCwd);
+            logger.log(ck `CWD changed to <magenta>${newCwd}</>`);
+        }
+        else if (env.get(env.xrunCwd) !== cwd) {
+            logger.log(ck `CWD is <magenta>${cwd}</>`);
+        }
+        env.set(env.xrunCwd, newCwd);
+        return newCwd;
+    }
+    catch (err) {
+        logger.log(ck `chdir <magenta>${newCwd}</> <red>failed</>`);
+        WrapProcess.exit(1);
+    }
+}
+/**
+ * Search for task files in the given directory
+ * @param {boolean} search - Whether to search up directories
+ * @param {ParseOptions} opts - Search options
+ * @returns {SearchResult} Search result
+ */
+function searchTaskFile(search, opts) {
+    const xrunDir = Path.join(opts.cwd, opts.dir || "");
+    const loadResult = searchUpTaskFile(xrunDir, search);
+    if (!loadResult.found) {
+        if (env.get(env.xrunTaskFile) !== "not found") {
+            const x = xsh.pathCwd.replace(xrunDir, "./");
+            logger.log(ck `No <green>${config.taskFile}</> found in <magenta>${x}</>`);
+        }
+        // set env to let subsequent xrun calls know that the task file was not found
+        // and avoid logging the same message again
+        env.set(env.xrunTaskFile, "not found");
+    }
+    else if (opts.updateCwd !== false) {
+        // force CWD to where xrun task file was found
+        loadResult.cwd = updateCwd(loadResult.dir);
+    }
+    return loadResult;
+}
+/**
+ * Load a task file.
+ *
+ * Loading goes through `import()` rather than `require`, which is what lets a task file use
+ * top-level await - node's `require(esm)` refuses that graph outright and always will. Every
+ * other format keeps working: `import()` of a CommonJS file yields a namespace with
+ * `module.exports` on `.default`, which processTasks already unwraps.
+ *
+ * @param {string} name - Path to the task file
+ * @returns {Promise<Object|Function|undefined>} Loaded task module, or undefined if it failed
+ */
+async function loadTaskFile(name) {
+    const ext = Path.extname(name);
+    if (ext === ".ts" || ext === ".tsx" || ext === ".mts" || ext === ".cts") {
+        TsRunner.startRunner();
+    }
+    try {
+        return await import(pathToFileURL(Path.resolve(name)).href);
+    }
+    catch (e) {
+        const file = xsh.pathCwd.replace(name, ".");
+        const errMsg = ck `<red>Unable to load ${file}</>`;
+        //
+        // node strips TypeScript types natively, which covers ordinary task files. It cannot
+        // handle syntax that has to be transformed rather than erased - enums, namespaces,
+        // parameter properties - and says so with its own code. Name the limit rather than
+        // dumping a stack that does not explain it.
+        //
+        /* istanbul ignore next */
+        if (e.code === "ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX" ||
+            e.code === "ERR_UNKNOWN_FILE_EXTENSION" ||
+            e.code === "ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING") {
+            logger.error(ck `${errMsg}: node cannot load this TypeScript on its own.
+  It strips types, but enums, namespaces and parameter properties need a real transform.
+  Rewrite them, or run node with <yellow>--experimental-transform-types</>.
+  ${e.message}`);
+            return undefined;
+        }
+        logger.error(`${errMsg}: ${xsh.pathCwd.replace(e.stack, ".", "g")}`);
+        return undefined;
+    }
+}
+/**
+ * Process loaded tasks and register them with xrun
+ * @param {Object|Function} tasks - Tasks to process
+ * @param {string} loadMsg - Message to display when tasks are loaded
+ * @param {string} [ns="xrun"] - Namespace to load tasks into
+ */
+function processTasks(tasks, loadMsg, ns = "xrun") {
+    if (typeof tasks === "function") {
+        tasks(instance.xrun);
+        if (loadMsg) {
+            logger.log(`Loaded tasks by calling export function from ${loadMsg}`);
+        }
+    }
+    else if (typeof tasks === "object") {
+        if (tasks.default) {
+            processTasks(tasks.default, `${loadMsg} default export`, ns);
+        }
+        else if (Object.keys(tasks).length > 0) {
+            instance.xrun.load(ns, tasks);
+            logger.log(ck `Loaded tasks from ${loadMsg} into namespace <magenta>${ns}</>`);
+        }
+        else if (loadMsg) {
+            logger.log(`Loaded ${loadMsg}`);
+        }
+    }
+    else {
+        logger.log(ck `Unknown export type <yellow>${typeof tasks}</> from ${loadMsg}`);
+    }
+}
+/**
+ * Load tasks from files or required modules
+ * @param {ParseOptions} opts - Options for loading tasks
+ * @param {SearchResult} searchResult - Result from searching for task files
+ * @returns {boolean} Whether any tasks were loaded
+ */
+async function loadTasks(opts, searchResult) {
+    let loaded = false;
+    npmLoader(instance.xrun, opts);
+    if (opts.require) {
+        // a for-of rather than forEach: each file has to finish loading before the next starts,
+        // so tasks land in the order the user listed their modules
+        for (const xmod of opts.require) {
+            let file;
+            try {
+                file = createRequire(Path.join(WrapProcess.cwd(), "package.json")).resolve(xmod);
+            }
+            catch (err) {
+                logger.log(ck `<red>ERROR:</> <yellow>Unable to require module</> <cyan>'${xmod}'</> - <red>${err.message}</>`);
+                continue;
+            }
+            const tasks = await loadTaskFile(file);
+            /* istanbul ignore else */
+            if (tasks) {
+                const loadMsg = ck `<green>${xmod}</>`;
+                processTasks(tasks, loadMsg);
+                loaded = true;
+            }
+        }
+    }
+    else if (searchResult.xrunFile) {
+        const tasks = await loadTaskFile(searchResult.xrunFile);
+        /* istanbul ignore else */
+        if (tasks) {
+            processTasks(tasks, env.get(env.xrunTaskFile) !== searchResult.xrunFile
+                ? ck `<green>${xsh.pathCwd.replace(searchResult.xrunFile, ".")}</>`
+                : "");
+            env.set(env.xrunTaskFile, searchResult.xrunFile);
+            return (loaded = true);
+        }
+    }
+    return loaded;
+}
+export { updateCwd, searchTaskFile, loadTaskFile, processTasks, loadTasks };

package/dist/cli/ts-runner.d.ts

@@ -0,0 +1,2 @@
+declare const TsRunner: any;
+export default TsRunner;

package/dist/cli/ts-runner.js

@@ -0,0 +1,60 @@
+import { createRequire } from "node:module";
+import { makeOptionalRequire } from "optional-require";
+//
+// A require hook is the point here - TsRunner installs tsx / ts-node into require - so this
+// deliberately stays on require rather than moving to optional-import.
+//
+const optionalRequire = makeOptionalRequire(createRequire(import.meta.url));
+import env from "./env.js";
+import logger from "../lib/logger.js";
+import path from "path";
+import WrapProcess from "./wrap-process.js";
+const TsRunner = {
+    //
+    // `@fynjs/ts-resolve` is ESM-only, but it stays on this same require path: node's
+    // `require(esm)` is unflagged from 22.12, which is already this package's floor, and
+    // `./register` has no top-level await - the one graph `require(esm)` refuses. So it is
+    // required like the others and returns a (truthy) namespace object.
+    //
+    // It is first because it is the cheapest: a resolve hook feeding node's own type
+    // stripping, no transpiler and no native binary. Its only hard requirement is node
+    // >= 22.15 for `module.registerHooks`; below that the require throws, optional-require
+    // routes that to `fail`, and tsx / ts-node still get their turn.
+    //
+    "runner-ts-resolve": "@fynjs/ts-resolve/register",
+    "runner-ts-node": "ts-node/register/transpile-only",
+    loaded: undefined,
+    runner: undefined,
+    _require: optionalRequire,
+    load(name) {
+        const runner = TsRunner._require(TsRunner[`runner-${name}`], {
+            fail: e => (TsRunner[`error-${name}`] = e)
+        });
+        if (runner) {
+            TsRunner.loaded = name;
+            TsRunner.runner = runner;
+            const resolve = TsRunner._require.resolve;
+            TsRunner.path =
+                (resolve && ": " + path.relative(WrapProcess.cwd(), resolve(TsRunner[`runner-${name}`]))) ||
+                    "";
+        }
+        return runner;
+    },
+    startRunner() {
+        const runners = ["ts-resolve", "ts-node"];
+        for (const runner of runners) {
+            if (TsRunner.load(runner)) {
+                break;
+            }
+        }
+        if (!TsRunner.loaded) {
+            const errMsg = runners.map(r => r + ": " + TsRunner[`error-${r}`]).join("\n  ");
+            logger.log(`Unable to load a typescript runner:\n  ${errMsg}`);
+        }
+        else if (!env.get(env.xrunId)) {
+            /* if xrunId exist then we are already running as invocation from another xrun */
+            logger.log(`Loaded ${TsRunner.loaded} for TypeScript files${TsRunner.path}`);
+        }
+    }
+};
+export default TsRunner;

package/dist/cli/usage.d.ts

@@ -0,0 +1,2 @@
+declare const usage: string;
+export default usage;

package/dist/cli/wrap-process.d.ts

@@ -0,0 +1,10 @@
+/** @type {WrapProcess} */
+declare const WrapProcess: {
+    _process: NodeJS.Process;
+    exit(code: any): void;
+    cwd(): any;
+    chdir(dir: any): void;
+    argv: any;
+    env: any;
+};
+export default WrapProcess;

package/dist/cli/wrap-process.js

@@ -0,0 +1,26 @@
+/** @type {WrapProcess} */
+const WrapProcess = {
+    _process: process,
+    exit(code) {
+        this._process.exit(code);
+    },
+    cwd() {
+        return this._process.cwd();
+    },
+    chdir(dir) {
+        this._process.chdir(dir);
+    },
+    get argv() {
+        return this._process.argv;
+    },
+    set argv(value) {
+        this._process.argv = value;
+    },
+    get env() {
+        return this._process.env;
+    },
+    set env(value) {
+        this._process.env = value;
+    }
+};
+export default WrapProcess;

package/dist/cli/xrun-main.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Flush logger based on options
+ * @param {Object} opts - Options
+ */
+declare function flushLogger(opts: any): void;
+/**
+ * Handle process exit or callback
+ * @param {number} code - Exit code
+ * @param {Function} done - Optional callback
+ */
+declare function handleExitOrDone(code: any, done: any): boolean;
+/**
+ * Process environment options from command line
+ * @param {Object} opts - Options object containing env property
+ */
+declare function processEnvOptions(opts: any): void;
+/**
+ * List CLI options for shell auto completion
+ * @param {Array} argv - Command line arguments
+ * @param {number} offset - Argument offset
+ * @param {Function} done - Optional callback
+ * @returns {void}
+ */
+declare function handleCliOptions(argv: any, offset: any, done: any): boolean;
+/**
+ * Find and load the runner module
+ * @param {string} xrunPath - Path to xrun
+ * @returns {Object} Runner module and its path
+ */
+declare function findRunnerModule(xrunPath: any): {
+    runner: any;
+    foundPath: string;
+};
+/**
+ * Handle case when no tasks are found
+ * @param {CliContext} cliContext - Command context
+ * @param {string} cwd - Current working directory
+ * @param {Function} done - Optional callback
+ */
+declare function handleNoTasks(cliContext: any, cwd: any, done: any, opts: any): boolean;
+/**
+ * Handle task listing
+ * @param {Object} runner - Runner instance
+ * @param {Object} opts - Options
+ * @param {Function} done - Optional callback
+ * @returns {void}
+ */
+declare function handleTaskListing(runner: any, opts: any, done: any): boolean;
+/**
+ * Handle namespace listing
+ * @param {Object} runner - Runner instance
+ * @param {Object} opts - Options
+ * @param {Function} done - Optional callback
+ * @returns {void}
+ */
+declare function handleNamespaceListing(runner: any, opts: any, done: any): boolean;
+/**
+ * Handle help display
+ * @param {Object} runner - Runner instance
+ * @param {CliContext} cliContext - Command context
+ * @param {Object} opts - Options
+ * @param {string} cmdName - Command name
+ * @param {Function} done - Optional callback
+ * @returns {void}
+ */
+declare function handleHelp(runner: any, cliContext: any, opts: any, cmdName: any, done: any): boolean;
+/**
+ * Setup node_modules bin in PATH
+ * @param {Object} opts - Options
+ */
+declare function setupNodeModulesBin(opts: any): void;
+/**
+ * Setup environment variables
+ */
+declare function setupEnvironment(): void;
+/**
+ * Process task arguments
+ * @param {Array} tasks - Task arguments
+ * @param {Object} opts - Options
+ * @returns {Array} Processed tasks
+ */
+declare function processTasks(tasks: any, opts: any): any;
+/**
+ * Handle quiet flag setting in environment
+ * @param {Object} jsonMeta - Command metadata
+ * @param {Object} opts - Command options
+ * @returns {boolean} - Whether quiet mode is enabled
+ */
+declare function handleQuietFlag(jsonMeta: any, opts: any): any;
+/**
+ * Main entry point for xrun
+ * @param {Array} argv - Command line arguments
+ * @param {number} offset - Argument offset
+ * @param {string} xrunPath - Path to xrun
+ * @param {Function} done - Optional callback
+ * @returns {*} Runner result or void
+ */
+declare function xrunMain(argv: any, offset: any, xrunPath?: string, done?: any): Promise<any>;
+import { INTERNALS } from "../lib/defaults.js";
+export { xrunMain };
+declare const _default: {
+    xrunMain: typeof xrunMain;
+    [INTERNALS]: {
+        flushLogger: typeof flushLogger;
+        handleExitOrDone: typeof handleExitOrDone;
+        handleCliOptions: typeof handleCliOptions;
+        findRunnerModule: typeof findRunnerModule;
+        handleNoTasks: typeof handleNoTasks;
+        handleTaskListing: typeof handleTaskListing;
+        handleNamespaceListing: typeof handleNamespaceListing;
+        handleHelp: typeof handleHelp;
+        setupNodeModulesBin: typeof setupNodeModulesBin;
+        setupEnvironment: typeof setupEnvironment;
+        processTasks: typeof processTasks;
+        handleQuietFlag: typeof handleQuietFlag;
+        processEnvOptions: typeof processEnvOptions;
+    };
+};
+export default _default;