@fynjs/run 1.0.0

package/bin/qrun.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+process.env.XRUN_QUIET = "1";
+import "./xrun.js";

package/bin/xrun.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import Path from "path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Find the directory holding the CLI code to run.
+ *
+ * A project can install its own @fynjs/run, and that copy should win over whichever one this bin
+ * happens to live in - so look from the project's cwd first, then from this file. Looking from
+ * this file also covers package managers that symlink node_modules/.bin straight at the bin
+ * script, which bypasses node's `--preserve-symlinks` handling.
+ *
+ * Every branch returns an absolute path. Probing by name and then requiring by name would use two
+ * different resolution bases - cwd for the probe, this file for the require - so they could land
+ * on different copies, or the require could fail outright when only the probe matched.
+ *
+ * @returns absolute path to the cli directory
+ */
+function resolveCliDir() {
+  for (const paths of [[process.cwd()], [import.meta.dirname]]) {
+    try {
+      return Path.dirname(require.resolve("@fynjs/run/cli/xrun", { paths }));
+    } catch (err) {
+      //
+    }
+  }
+
+  // not installed under either - running from this package's own checkout
+  return Path.join(import.meta.dirname, "..", "cli");
+}
+
+//
+// resolve xrun and ck from the same install so they cannot come from different copies
+//
+const cliDir = resolveCliDir();
+
+const { default: xrun } = await import(pathToFileURL(Path.join(cliDir, "xrun.js")).href);
+
+await xrun();

package/cli/check-global.js

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

package/cli/ck.js

@@ -0,0 +1,6 @@
+//
+// chalker is the tagged-template color formatter used across the CLI. It is ESM with a
+// top-level await, which a CJS package could not require - hence the async loader and
+// marker-stripping fallback this module used to carry. As ESM we simply import it.
+//
+export { default } from "chalker";

package/cli/cli-options.js

@@ -0,0 +1,98 @@
+import assert from "assert";
+import chalk from "../lib/chalk.js";
+import myPkg from "../package.json" with { type: "json" };
+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/cli/config.js

@@ -0,0 +1,8 @@
+import myPkg from "../package.json" with { type: "json" };
+
+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/cli/env.js

@@ -0,0 +1,33 @@
+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/cli/npm-loader.js

@@ -0,0 +1,56 @@
+import logger from "../lib/logger.js";
+import chalk from "../lib/chalk.js";
+import readPkgUp from "read-pkg-up";
+import myPkg from "../package.json" with { type: "json" };
+import config from "./config.js";
+import env from "./env.js";
+
+export default (xrun, options) => {
+  const readPkg = readPkgUp.sync();
+
+  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/cli/parse-cmd-args.js

@@ -0,0 +1,156 @@
+/**
+ * @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 "../package.json" with { type: "json" };
+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";
+
+/**
+ * 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
+    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
+  const parsed = nc.parse(argv, start);
+  const 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);
+
+  // Extract tasks from commands
+  const tasks = Object.keys(parsed.command.subCmdNodes);
+
+  // user has no tasks or explicitly enable searching for provider modules
+  if (loaded === false || pkgConfig.loadProviderModules) {
+    loadProviderPackages(Pkg, saveCwd, opts);
+  }
+
+  return {
+    opts,
+    tasks,
+    parsed,
+    searchResult
+  };
+}
+
+export {
+  parseArgs,
+  updateCwd,
+  searchTaskFile,
+  loadTaskFile,
+  processTasks
+};
+export default {
+  parseArgs,
+  updateCwd,
+  searchTaskFile,
+  loadTaskFile,
+  processTasks
+};

package/cli/provider-packages.js

@@ -0,0 +1,73 @@
+import { makeOptionalRequire } from "optional-require";
+import { processTasks } from "./task-file.js";
+import WrapProcess from "./wrap-process.js";
+import myPkg from "../package.json" with { type: "json" };
+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/cli/search-up-task-file.js

@@ -0,0 +1,92 @@
+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 };