@fynjs/run 1.0.1 → 1.1.1

package/bin/qrun.js

@@ -1,3 +1,8 @@
 #!/usr/bin/env node
 process.env.XRUN_QUIET = "1";
-import "./xrun.js";
+
+//
+// dynamic import - a static `import "./xrun.js"` is hoisted and its module body (which ends in
+// a top level `await xrun()`) runs BEFORE the assignment above, so xrun never sees XRUN_QUIET.
+//
+await import("./xrun.js");

package/bin/xrun.js

@@ -29,7 +29,7 @@ function resolveCliDir() {
   }
 
   // not installed under either - running from this package's own checkout
-  return Path.join(import.meta.dirname, "..", "cli");
+  return Path.join(import.meta.dirname, "..", "dist", "cli");
 }
 
 //

package/dist/cli/check-global.d.ts

@@ -0,0 +1 @@
+export default function checkGlobal(): boolean;

package/{cli → dist/cli}/check-global.js

@@ -1,6 +1,6 @@
 /* istanbul ignore file */
 /* this file here for backward compatibility with xrun@1.x */
-
 export default function checkGlobal() {
-  return false;
-};
+    return false;
+}
+;

package/dist/cli/ck.d.ts

@@ -0,0 +1 @@
+export { default } from "chalker";

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

@@ -0,0 +1,80 @@
+declare const _default: {
+    cwd: {
+        alias: string;
+        desc: string;
+        args: string;
+        requireArg: boolean;
+    };
+    dir: {
+        alias: string;
+        desc: string;
+        args: string;
+        requireArg: boolean;
+    };
+    npm: {
+        alias: string;
+        desc: string;
+        args: string;
+        argDefault: string;
+    };
+    nmbin: {
+        alias: string;
+        desc: string;
+        args: string;
+        argDefault: string;
+    };
+    list: {
+        alias: string;
+        desc: string;
+        args: string;
+        argDefault: string;
+    };
+    full: {
+        type: string;
+        alias: string;
+        desc: string;
+        counting: number;
+    };
+    ns: {
+        alias: string;
+        desc: string;
+        args: string;
+    };
+    soe: {
+        alias: string;
+        desc: string;
+        args: string;
+        argDefault: string;
+        customTypes: {
+            enum: (v: any) => any;
+        };
+    };
+    quiet: {
+        alias: string;
+        desc: string;
+        args: string;
+        argDefault: string;
+    };
+    serial: {
+        alias: string[];
+        desc: string;
+        args: string;
+        argDefault: string;
+    };
+    concurrent: {
+        alias: string[];
+        desc: string;
+        args: string;
+        argDefault: string;
+    };
+    env: {
+        desc: string;
+        args: string;
+    };
+    require: {
+        alias: string;
+        desc: string;
+        args: string;
+    };
+};
+export default _default;

package/dist/cli/cli-options.js

@@ -0,0 +1,95 @@
+import assert from "assert";
+import chalk from "../lib/chalk.js";
+import myPkg from "../lib/my-pkg.js";
+import config from "./config.js";
+export default {
+    cwd: {
+        alias: "w",
+        desc: `Set ${myPkg.name}'s ${chalk.magenta("CWD")}`,
+        args: "<path string>",
+        requireArg: true
+    },
+    dir: {
+        alias: "d",
+        desc: `Set dir to look for ${chalk.green(config.taskFile)} (default is ${chalk.magenta("CWD")})`,
+        args: "<path string>",
+        requireArg: true
+    },
+    npm: {
+        alias: "n",
+        desc: `load npm scripts into namespace ${chalk.magenta("npm")} (--no-npm to disable)`,
+        args: "[ boolean]",
+        argDefault: "true"
+    },
+    nmbin: {
+        alias: "b",
+        desc: `add ${chalk.magenta("CWD/node_modules/.bin")} to ${chalk.blue("PATH")}`,
+        args: "[ boolean]",
+        argDefault: "true"
+    },
+    list: {
+        alias: "l",
+        desc: "List tasks names from list of comma separated namespaces (default is all namespaces)",
+        args: "[namespaces string]",
+        argDefault: ""
+    },
+    full: {
+        type: "count",
+        alias: "f",
+        desc: "--list show tasks names with namespace",
+        counting: Infinity
+    },
+    ns: {
+        alias: "m",
+        desc: "List all namespaces",
+        args: "[ boolean]"
+    },
+    soe: {
+        alias: "e",
+        desc: `Stop on errors - one of: no, soft, full`,
+        args: "[mode enum]",
+        argDefault: "full",
+        customTypes: {
+            enum: v => {
+                /* istanbul ignore next */
+                if (v === undefined) {
+                    return "full";
+                }
+                /* istanbul ignore next */
+                if (!v || v === "no") {
+                    /* istanbul ignore next */
+                    return "";
+                }
+                assert(v === "soft" || v === "full", `option soe value must be one of: no, soft, full`);
+                return v;
+            }
+        }
+    },
+    quiet: {
+        alias: "q",
+        desc: "Do not output any logs",
+        args: "[ boolean]",
+        argDefault: "false"
+    },
+    serial: {
+        alias: ["s", "x", "ser"],
+        desc: "Execute tasks from command line serially",
+        args: "[ boolean]",
+        argDefault: "false"
+    },
+    concurrent: {
+        alias: ["c", "conc"],
+        desc: "Execute tasks from command line concurrently (default)",
+        args: "[ boolean]",
+        argDefault: "true"
+    },
+    env: {
+        desc: "Set env. ie: --env NODE_ENV=development FOO=BAR -.",
+        args: "[env string...]"
+    },
+    require: {
+        alias: "r",
+        desc: `require module for tasks instead of loading ${config.taskFile}. require from path is CWD`,
+        args: "[modules string...]"
+    }
+};

package/dist/cli/config.d.ts

@@ -0,0 +1,7 @@
+declare const _default: {
+    taskFile: string;
+    taskFileExt: string[];
+    search: string[];
+    getPkgOpt: (pkg: any) => any;
+};
+export default _default;

package/dist/cli/config.js

@@ -0,0 +1,7 @@
+import myPkg from "../lib/my-pkg.js";
+export default {
+    taskFile: "xrun-tasks.js",
+    taskFileExt: ["js", "cjs", "ts", "mts", "cts", "mjs"],
+    search: ["xrun-tasks", "xrun", "xclap.", "clapfile.", "clap.", "gulpfile."],
+    getPkgOpt: pkg => ["xclap", "xrun", myPkg.name].find(f => pkg.hasOwnProperty(f))
+};

package/dist/cli/env.d.ts

@@ -0,0 +1,17 @@
+declare const lib: {
+    container: any;
+    xrunTaskFile: string;
+    xrunPackagePath: string;
+    xrunId: string;
+    forceColor: string;
+    xrunCwd: string;
+    xrunVersion: string;
+    xrunBinDir: string;
+    xrunNodeBin: string;
+    xrunQuiet: string;
+    get(key: any): any;
+    set(key: any, val: any): void;
+    has(key: any): any;
+    del(key: any): void;
+};
+export default lib;

package/dist/cli/env.js

@@ -0,0 +1,31 @@
+import assert from "assert";
+import WrapProcess from "./wrap-process.js";
+const lib = {
+    container: WrapProcess.env,
+    xrunTaskFile: "XRUN_TASKFILE",
+    xrunPackagePath: "XRUN_PACKAGE_PATH",
+    xrunId: "XRUN_ID",
+    forceColor: "FORCE_COLOR",
+    xrunCwd: "XRUN_CWD",
+    xrunVersion: "XRUN_VERSION",
+    xrunBinDir: "XRUN_BIN_DIR",
+    xrunNodeBin: "XRUN_NODE_BIN",
+    xrunQuiet: "XRUN_QUIET",
+    get(key) {
+        assert(key, `env.get invalid key: ${key}`);
+        return lib.container[key];
+    },
+    set(key, val) {
+        assert(key, `env.set invalid key: ${key}`);
+        lib.container[key] = `${val}`;
+    },
+    has(key) {
+        assert(key, `env.has invalid key: ${key}`);
+        return lib.container.hasOwnProperty(key);
+    },
+    del(key) {
+        assert(key, `env.del invalid key: ${key}`);
+        delete lib.container[key];
+    }
+};
+export default lib;

package/dist/cli/npm-loader.d.ts

@@ -0,0 +1,2 @@
+export default _default;
+declare function _default(xrun: any, options: any): void;

package/dist/cli/npm-loader.js

@@ -0,0 +1,43 @@
+import logger from "../lib/logger.js";
+import chalk from "../lib/chalk.js";
+import { readPackageUpSync } from "read-package-up";
+import myPkg from "../lib/my-pkg.js";
+import config from "./config.js";
+import env from "./env.js";
+export default (xrun, options) => {
+    const readPkg = readPackageUpSync();
+    if (!readPkg) {
+        return;
+    }
+    const Pkg = readPkg.packageJson;
+    const pkgName = chalk.magenta(readPkg.path.replace(process.cwd(), "."));
+    if (Pkg.scripts && options.npm !== false) {
+        const scripts = {};
+        for (const k in Pkg.scripts) {
+            if (!k.startsWith("pre") && !k.startsWith("post")) {
+                const pre = `pre${k}`;
+                const post = `post${k}`;
+                scripts[k] = xrun.serial(Pkg.scripts.hasOwnProperty(pre) && pre, xrun.exec(Pkg.scripts[k], "npm"), Pkg.scripts.hasOwnProperty(post) && post);
+            }
+            else {
+                scripts[k] = xrun.exec(Pkg.scripts[k], "npm");
+            }
+        }
+        xrun.load("npm", scripts);
+        /* istanbul ignore else */
+        if (env.get(env.xrunPackagePath) !== readPkg.path) {
+            logger.log(`Loaded npm scripts from ${pkgName} into namespace ${chalk.magenta("npm")}`);
+        }
+        env.set(env.xrunPackagePath, readPkg.path);
+    }
+    const pkgOptField = config.getPkgOpt(Pkg);
+    const pkgConfig = pkgOptField && Pkg[pkgOptField];
+    if (pkgConfig) {
+        const tasks = Object.assign({}, pkgConfig.tasks);
+        /* istanbul ignore else */
+        if (Object.keys(tasks).length > 0) {
+            xrun.load("pkg", tasks);
+            logger.log(`Loaded ${myPkg.name} tasks from ${pkgName} into namespace ${chalk.magenta("pkg")}`);
+        }
+    }
+};

package/dist/cli/parse-cmd-args.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @typedef {Object} SearchResult
+ * @property {boolean} found - Whether a task file was found
+ * @property {boolean} foundPkg - Whether a package.json was found
+ * @property {string} [xrunFile] - Path to the found task file
+ * @property {string} dir - Directory where the file was found
+ */
+import { updateCwd, searchTaskFile, loadTaskFile, processTasks } from "./task-file.js";
+/**
+ * Parse command line arguments
+ * @param {string[]} argv - Command line arguments
+ * @param {number} start - Index to start parsing from
+ * @returns {ParseResult} Parsed arguments and tasks
+ */
+declare function parseArgs(argv: any, start: any): Promise<{
+    opts: Record<string, import("@fynjs/cli-args").OptionValue>;
+    tasks: any[];
+    parsed: any;
+    searchResult: any;
+} | {
+    opts: Record<string, import("@fynjs/cli-args").OptionValue>;
+    tasks: string[];
+    parsed: import("@fynjs/cli-args").ParseResult;
+    searchResult: any;
+}>;
+export { parseArgs, updateCwd, searchTaskFile, loadTaskFile, processTasks };
+declare const _default: {
+    parseArgs: typeof parseArgs;
+    updateCwd: typeof updateCwd;
+    searchTaskFile: typeof searchTaskFile;
+    loadTaskFile: typeof loadTaskFile;
+    processTasks: typeof processTasks;
+};
+export default _default;

package/dist/cli/parse-cmd-args.js

@@ -0,0 +1,199 @@
+/**
+ * @typedef {Object} SearchResult
+ * @property {boolean} found - Whether a task file was found
+ * @property {boolean} foundPkg - Whether a package.json was found
+ * @property {string} [xrunFile] - Path to the found task file
+ * @property {string} dir - Directory where the file was found
+ */
+/**
+ * @typedef {Object} ParseOptions
+ * @property {string} [cwd] - Current working directory
+ * @property {string} [dir] - Directory to search in
+ * @property {string[]} [require] - Modules to require
+ * @property {boolean} [npm] - Whether to load npm tasks
+ */
+/**
+ * @typedef {Object} ParseResult
+ * @property {string[]} tasks - List of tasks to run
+ * @property {Object} parsed - Parsed command line arguments
+ * @property {SearchResult} searchResult - Result of searching for task files
+ */
+import Path from "path";
+import cliOptions from "./cli-options.js";
+import { NixClap } from "@fynjs/cli-args";
+import xsh from "xsh";
+import usage from "./usage.js";
+import logger from "../lib/logger.js";
+import myPkg from "../lib/my-pkg.js";
+import ck from "./ck.js";
+import config from "./config.js";
+import env from "./env.js";
+import fs from "fs";
+import { updateCwd, searchTaskFile, loadTaskFile, processTasks, loadTasks } from "./task-file.js";
+import { loadProviderPackages } from "./provider-packages.js";
+import WrapProcess from "./wrap-process.js";
+import ownInstance from "../lib/xrun-instance.js";
+import { getTaskOptionSpec } from "../lib/util/task-options.js";
+/**
+ * Read and parse package.json from a directory
+ * @param {string} dir - Directory containing package.json
+ * @returns {Object} Parsed package.json contents
+ */
+function readPackageJson(dir) {
+    try {
+        const pkgData = fs.readFileSync(Path.join(dir, "package.json"), "utf-8");
+        return JSON.parse(pkgData);
+    }
+    catch {
+        /* istanbul ignore next */
+        return {};
+    }
+}
+/**
+ * Parse command line arguments
+ * @param {string[]} argv - Command line arguments
+ * @param {number} start - Index to start parsing from
+ * @returns {ParseResult} Parsed arguments and tasks
+ */
+async function parseArgs(argv, start) {
+    const nc = new NixClap({
+        allowUnknownCommand: true, // Allow task names as commands
+        allowUnknownOption: true, // Allow task-specific options
+        /* istanbul ignore next */
+        exit: code => {
+            WrapProcess.exit(code);
+        },
+        handlers: {
+            /* istanbul ignore next */
+            exit: code => {
+                WrapProcess.exit(code);
+            }
+        }
+    })
+        .version(myPkg.version)
+        .usage(usage)
+        .init(cliOptions, {} // no xrun commands
+    );
+    // Parse all arguments at once - @fynjs/cli-args handles command/option separation
+    let parsed = nc.parse(argv, start);
+    let opts = parsed.command.opts;
+    const myDir = xsh.pathCwd.replace(Path.dirname(import.meta.dirname), ".");
+    /* istanbul ignore next */
+    if (env.get(env.xrunVersion) !== myPkg.version || env.get(env.xrunBinDir) !== myDir) {
+        logger.log(ck `<green>${myPkg.name}</> version ${myPkg.version} at <magenta>${myDir}</>`);
+    }
+    /* istanbul ignore next */
+    if (env.get(env.xrunNodeBin) !== process.execPath) {
+        logger.log(ck `<green>node.js</> version ${process.version} at <magenta>${process.execPath}</>`);
+    }
+    env.set(env.xrunVersion, myPkg.version);
+    env.set(env.xrunBinDir, myDir);
+    env.set(env.xrunNodeBin, process.execPath);
+    // don't search if user has explicitly set CWD
+    const search = !opts.cwd;
+    const saveCwd = env.get(env.xrunCwd);
+    opts.cwd = updateCwd(opts.cwd);
+    let searchResult = {};
+    /* istanbul ignore next */
+    if (!opts.require) {
+        searchResult = searchTaskFile(search, opts);
+    }
+    const Pkg = readPackageJson(opts.cwd);
+    const pkgOptField = config.getPkgOpt(Pkg);
+    let pkgConfig = {};
+    if (pkgOptField) {
+        pkgConfig = Object.assign(pkgConfig, Pkg[pkgOptField]);
+        delete pkgConfig.cwd; // not allow pkg config to override cwd
+        delete pkgConfig.tasks;
+        // nc.applyConfig(pkgConfig, parsed);
+        const pkgName = ck `<magenta>./package.json</>`;
+        logger.log(ck `Applied <green>${pkgOptField}</> options from ${pkgName}`);
+    }
+    const loaded = await loadTasks(opts, searchResult);
+    // user has no tasks or explicitly enable searching for provider modules
+    if (loaded === false || pkgConfig.loadProviderModules) {
+        loadProviderPackages(Pkg, saveCwd, opts);
+    }
+    // Register loaded tasks into subcommand definitions for proper argument & option parsing
+    const subCommands = {};
+    if (ownInstance.xrun?._tasks) {
+        const names = ownInstance.xrun._tasks.names();
+        const fullNames = ownInstance.xrun._tasks.fullNames();
+        const allTaskNames = new Set([...names, ...fullNames]);
+        for (const name of allTaskNames) {
+            try {
+                const lookupRes = ownInstance.xrun._tasks.lookup(name);
+                const taskSpec = getTaskOptionSpec(lookupRes?.item);
+                if (Object.keys(taskSpec.options).length > 0 ||
+                    Object.keys(taskSpec.commands).length > 0) {
+                    subCommands[name] = {
+                        desc: lookupRes?.item?.desc || "",
+                        options: taskSpec.options,
+                        subCommands: taskSpec.commands,
+                        commands: taskSpec.commands,
+                        ...(taskSpec.allowUnknownOption !== undefined
+                            ? { allowUnknownOption: taskSpec.allowUnknownOption }
+                            : {})
+                    };
+                }
+            }
+            catch {
+                // ignore lookup errors for invalid task names
+            }
+        }
+    }
+    if (Object.keys(subCommands).length > 0) {
+        const nc2 = new NixClap({
+            allowUnknownCommand: true,
+            allowUnknownOption: true,
+            /* istanbul ignore next */
+            exit: code => {
+                WrapProcess.exit(code);
+            },
+            handlers: {
+                /* istanbul ignore next */
+                exit: code => {
+                    WrapProcess.exit(code);
+                }
+            }
+        })
+            .version(myPkg.version)
+            .usage(usage);
+        try {
+            nc2.init(cliOptions, subCommands);
+            parsed = nc2.parse(argv, start);
+            const savedCwd = opts.cwd;
+            opts = parsed.command.opts;
+            opts.cwd = savedCwd;
+        }
+        catch (err) {
+            logger.log(ck `<red>ERROR</>: ${err.message}`);
+            WrapProcess.exit(1);
+            return {
+                opts,
+                tasks: [],
+                parsed: {
+                    command: { opts, subCmdNodes: {} },
+                    errorNodes: [{ errors: [err] }]
+                },
+                searchResult
+            };
+        }
+    }
+    // Extract tasks from commands
+    const tasks = Object.keys(parsed.command.subCmdNodes);
+    return {
+        opts,
+        tasks,
+        parsed,
+        searchResult
+    };
+}
+export { parseArgs, updateCwd, searchTaskFile, loadTaskFile, processTasks };
+export default {
+    parseArgs,
+    updateCwd,
+    searchTaskFile,
+    loadTaskFile,
+    processTasks
+};

package/dist/cli/provider-packages.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Search for provider packages in the node_modules directory.
+ *
+ * When does xrun load provider packages?
+ *
+ * 1. When the user has no tasks loaded
+ * 2. When the user sets the `loadProviderModules` option in their package.json under the `xrun` key
+ *
+ * What's considered a provider package?
+ *
+ * 1. The package sets the `xrunProvider` config in its package.json
+ * 2. The package has @fynjs/run listed in its dependencies
+ *
+ * What module does xrun require from the provider package to look for tasks?
+ *
+ * 1. The provider package sets `module` prop under the `xrunProvider` config in its package.json
+ * 2. Otherwise, xrun will require the provider package using its name
+ *
+ * How does xrun load tasks from the provider package?
+ *
+ * 1. If the provider module has a `loadTasks` export function, it will be used to load tasks
+ *
+ * @param {*} userPkg - the user's package.json object, typically the one in CWD
+ * @param {*} saveCwd - the CWD when xrun started, before xrun updated it to user specified CWD
+ * @param {*} opts - the command line options
+ */
+declare function loadProviderPackages(userPkg: any, saveCwd: any, opts: any): void;
+export { loadProviderPackages };

package/dist/cli/provider-packages.js

@@ -0,0 +1,62 @@
+import { makeOptionalRequire } from "optional-require";
+import { processTasks } from "./task-file.js";
+import WrapProcess from "./wrap-process.js";
+import myPkg from "../lib/my-pkg.js";
+import path from "path";
+/**
+ * Search for provider packages in the node_modules directory.
+ *
+ * When does xrun load provider packages?
+ *
+ * 1. When the user has no tasks loaded
+ * 2. When the user sets the `loadProviderModules` option in their package.json under the `xrun` key
+ *
+ * What's considered a provider package?
+ *
+ * 1. The package sets the `xrunProvider` config in its package.json
+ * 2. The package has @fynjs/run listed in its dependencies
+ *
+ * What module does xrun require from the provider package to look for tasks?
+ *
+ * 1. The provider package sets `module` prop under the `xrunProvider` config in its package.json
+ * 2. Otherwise, xrun will require the provider package using its name
+ *
+ * How does xrun load tasks from the provider package?
+ *
+ * 1. If the provider module has a `loadTasks` export function, it will be used to load tasks
+ *
+ * @param {*} userPkg - the user's package.json object, typically the one in CWD
+ * @param {*} saveCwd - the CWD when xrun started, before xrun updated it to user specified CWD
+ * @param {*} opts - the command line options
+ */
+function loadProviderPackages(userPkg, saveCwd, opts) {
+    const optionalRequire = makeOptionalRequire(opts.cwd || WrapProcess.cwd());
+    const providers = Object.keys(Object.assign({}, userPkg.optionalDependencies, userPkg.devDependencies, userPkg.dependencies));
+    providers.forEach(pkgName => {
+        const providerPath = optionalRequire.resolvePath(pkgName);
+        const pkgJsonPath = providerPath &&
+            path.join(providerPath.substring(0, pkgName.length + providerPath.indexOf(pkgName)), `package.json`);
+        const providerPkg = pkgJsonPath && optionalRequire(pkgJsonPath);
+        if (!providerPkg) {
+            return;
+        }
+        const provider = providerPkg.xrunProvider;
+        // accept both the current name (@fynjs/run) and the legacy name (@xarc/run) so
+        // providers published before the rename are still detected
+        const XRUN_DEP_NAMES = [myPkg.name, "@xarc/run"];
+        if (!provider && !XRUN_DEP_NAMES.some(n => providerPkg.dependencies?.[n])) {
+            // module is not marked as a provider and doesn't have xrun as dep, assume not
+            // a provider
+            return;
+        }
+        // module looks like a provider and user does not have tasks loaded, continue
+        // to see if module exports `loadTasks`
+        const req = (provider?.module && `/${provider.module}`) || "";
+        const providerMod = optionalRequire(`${pkgName}${req}`);
+        if (providerMod?.loadTasks) {
+            const loadMsg = saveCwd !== opts.cwd ? `provider package ${pkgName}` : "";
+            processTasks(providerMod.loadTasks, loadMsg);
+        }
+    });
+}
+export { loadProviderPackages };

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

@@ -0,0 +1,8 @@
+declare function searchUpTaskFile(xrunDir: any, search: any): any;
+declare function findTaskFile(xrunDir: any): {
+    found: boolean;
+    foundPkg: boolean;
+    xrunFile: string;
+    dir: any;
+};
+export { searchUpTaskFile, findTaskFile };