@fynjs/run 1.0.0

package/cli/xrun.js

@@ -0,0 +1,8 @@
+import { xrunMain } from "./xrun-main.js";
+
+//
+// Async: task files load through `import()` so a task file can use top-level await, which
+// `require` can never support. Callers must await this - bin/xrun.js does, and so must any
+// programmatic caller that wants to observe the run.
+//
+export default xrunMain;

package/lib/chalk.js

@@ -0,0 +1,11 @@
+//
+// chalk is ESM-only. This package is ESM too, so importing it is unremarkable - this module
+// stays only because a dozen call sites already point at it, and it is the one place to change
+// if the color library is ever swapped.
+//
+// Bound explicitly rather than `export { default } from "chalk"`: a bare re-export can reach
+// consumers as a module namespace, and call sites assign to `chalk.level`.
+//
+import chalk from "chalk";
+
+export default chalk;

package/lib/cli-context.js

@@ -0,0 +1,145 @@
+/**
+ * CliContext encapsulates all CLI-related information from command line parsing
+ * This provides a clean interface for accessing command arguments, options, and metadata
+ * throughout the execution pipeline without tight coupling to CLI parsing details.
+ */
+class CliContext {
+  constructor(cmdArgs) {
+    // Full cmdArgs from CLI parsing
+    this._cmdArgs = cmdArgs;
+    this._parsed = cmdArgs.parsed;
+    this._subCmdNodes = cmdArgs.cmdNodes || cmdArgs.parsed?.command?.subCmdNodes || {};
+    this._opts = cmdArgs.opts;
+    this._tasks = cmdArgs.tasks || [];
+    this._searchResult = cmdArgs.searchResult;
+    this._remainingArgs = cmdArgs.parsed?._ || [];
+  }
+
+  /**
+   * Get command information for a specific task
+   * @param {string} taskName - Name of the task
+   * @returns {Object} Task command object with argv, opts, etc.
+   */
+  getTaskCommand(taskName) {
+    return this._subCmdNodes[taskName] || {};
+  }
+
+  /**
+   * Get argv array for a specific task
+   * @param {string} taskName - Name of the task
+   * @returns {Array} Task arguments array
+   */
+  getTaskArgv(taskName) {
+    return this.getTaskCommand(taskName).argv || [];
+  }
+
+  /**
+   * Get global command line options
+   * @returns {Object} Global options object
+   */
+  getGlobalOptions() {
+    return this._opts;
+  }
+
+  /**
+   * Get command metadata (jsonMeta)
+   * @returns {Object} Command metadata
+   */
+  getMetadata() {
+    return this._parsed?.command?.jsonMeta || {};
+  }
+
+  /**
+   * Get the list of tasks to execute
+   * @returns {Array} Tasks array
+   */
+  getTasks() {
+    return this._tasks;
+  }
+
+  /**
+   * Get search result information
+   * @returns {Object} Search result with found files, directories, etc.
+   */
+  getSearchResult() {
+    return this._searchResult;
+  }
+
+  /**
+   * Check if quiet mode is enabled
+   * @returns {boolean} True if quiet mode
+   */
+  isQuiet() {
+    return this._opts.quiet;
+  }
+
+  /**
+   * Check if serial execution is requested
+   * @returns {boolean} True if serial execution
+   */
+  isSerial() {
+    return this._opts.serial;
+  }
+
+  /**
+   * Get stop on error setting
+   * @returns {string|boolean} Stop on error setting
+   */
+  getStopOnError() {
+    return this._opts.soe;
+  }
+
+  /**
+   * Get arguments that came after "--" in the CLI
+   * These are stored in parsed._ by @fynjs/cli-args
+   * @returns {Array} Arguments after "--"
+   */
+  getRemainingArgs() {
+    return this._remainingArgs;
+  }
+
+  /**
+   * Check if there are any remaining arguments after "--"
+   * @returns {boolean} True if there are remaining arguments
+   */
+  hasRemainingArgs() {
+    return this._remainingArgs && this._remainingArgs.length > 0;
+  }
+
+  /**
+   * Get raw command args for backward compatibility
+   * @returns {Object} Raw command args object
+   */
+  getRawCmdArgs() {
+    return this._cmdArgs;
+  }
+
+  /**
+   * Get raw parsed command for backward compatibility
+   * @returns {Object} Raw parsed command object
+   */
+  getRawParsed() {
+    return this._parsed;
+  }
+
+  /**
+   * Get all task names that have command nodes
+   * @returns {Array} Array of task names
+   */
+  getAllTaskNames() {
+    return Object.keys(this._subCmdNodes);
+  }
+
+  /**
+   * Check if a given task is the last task from CLI arguments
+   * This is used to determine where to append remaining args
+   * @param {string} taskName - Name of the task to check
+   * @param {string} taskType - Type of task (e.g., 'shell', 'function')
+   * @returns {boolean} True if this is the last CLI task and it's a shell task
+   */
+  isLastTask(taskName) {
+    return this._tasks.at(-1) === taskName;
+  }
+}
+
+export { CliContext };

package/lib/defaults.js

@@ -0,0 +1,32 @@
+const SERIAL_SYM = Symbol("serial");
+const CONCURRENT_SYM = Symbol("concurrent");
+
+export const NAMESPACE = "/";
+export const NS_SEP = "/";
+export const SERIAL_SIG = [".", "-s", "--serial", "--ser", SERIAL_SYM];
+export const CONCURRENT_SIG = ["--concurrent", "-c", "--conc", CONCURRENT_SYM];
+export const ANON_SHELL_SIG = ["~$", "~@"];
+export const ANON_SHELL_OPT_SIG = [`~(`];
+export const ANON_SHELL_OPT_CLOSE_SIG = [`)$`, ")@"];
+export const SHELL_FLAGS = ["tty", "spawn", "sync", "noenv", "npm"];
+export const STR_ARRAY_SIG = "~[";
+export const STOP_SYM = Symbol("xrun.stop");
+export const INTERNALS = Symbol("xrun.internals");
+
+export { CONCURRENT_SYM, SERIAL_SYM };
+
+export default {
+  NAMESPACE,
+  NS_SEP,
+  SERIAL_SIG,
+  CONCURRENT_SIG,
+  ANON_SHELL_SIG,
+  ANON_SHELL_OPT_SIG,
+  ANON_SHELL_OPT_CLOSE_SIG,
+  SHELL_FLAGS,
+  STR_ARRAY_SIG,
+  CONCURRENT_SYM,
+  SERIAL_SYM,
+  STOP_SYM,
+  INTERNALS
+};

package/lib/gen-xqid.js

@@ -0,0 +1,10 @@
+export default tag => {
+  return (
+    (tag ? `${tag}_` : "") +
+    Math.random()
+      .toString(36)
+      .substring(2, 12) +
+    "_" +
+    Date.now().toString(36)
+  );
+};

package/lib/index.js

@@ -0,0 +1,12 @@
+import container from "./xrun-instance.js";
+
+const xrun = container.xrun;
+
+export default xrun;
+
+//
+// Keep `require("@fynjs/run")` returning the xrun instance itself rather than the module
+// namespace, so a CommonJS task file - still a first class way to use this - does not have to
+// learn about `.default` because the package moved to ESM.
+//
+export { xrun as "module.exports" };

package/lib/logger.js

@@ -0,0 +1,105 @@
+import chalk from "./chalk.js";
+const MSEC_IN_SECOND = 1000;
+const MSEC_IN_MINUTE = 60 * MSEC_IN_SECOND;
+
+const pad2 = x => {
+  return (x < 10 ? "0" : "") + x;
+};
+
+class Logger {
+  constructor() {
+    this.coloring(true);
+    this.buffering(true);
+    this.quiet(true);
+  }
+
+  quiet(q) {
+    this._quiet = q;
+  }
+
+  buffering(f) {
+    if (f) {
+      if (!this._buf) this._buf = [];
+    } else {
+      this._buf = undefined;
+    }
+  }
+
+  resetBuffer(flush, buffering) {
+    if (this._buf) {
+      const buf = this._buf;
+      this._buf = [];
+      if (flush && !this._quiet) {
+        buf.forEach(l => this.write(`${l}\n`));
+      }
+      this.buffering(buffering);
+    }
+  }
+
+  coloring(f) {
+    if (f) {
+      this._L = `${chalk.magenta("[")}`;
+      this._R = `${chalk.magenta("]")}`;
+      this._c = true;
+    } else {
+      this._L = `[`;
+      this._R = `]`;
+      this._c = false;
+    }
+  }
+
+  get buffer() {
+    return this._buf || [];
+  }
+
+  timestamp() {
+    const d = new Date();
+    const ts = `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+    return ts;
+  }
+
+  _ts() {
+    return this._c
+      ? `${this._L}${chalk.gray(this.timestamp())}${this._R}`
+      : `${this._L}${this.timestamp()}${this._R}`;
+  }
+
+  formatElapse(elapse) {
+    if (elapse >= MSEC_IN_MINUTE) {
+      const min = elapse / MSEC_IN_MINUTE;
+      return `${min.toFixed(2)} min`;
+    } else if (elapse >= MSEC_IN_SECOND) {
+      const sec = elapse / MSEC_IN_SECOND;
+      return `${sec.toFixed(2)} sec`;
+    } else {
+      return `${elapse} ms`;
+    }
+  }
+
+  log() {
+    const msg = Array.prototype.join.call(arguments, " ");
+    const output = `${this._ts()} ${msg}`;
+
+    if (this._buf) {
+      this._buf.push(output);
+    } else if (!this._quiet) {
+      this.write(`${output}\n`);
+    }
+  }
+
+  error(...args) {
+    const x = this._quiet;
+    this._quiet = false;
+    this.log(...args);
+    this.quiet(x);
+  }
+
+  write(output) {
+    process.stdout.write(output);
+  }
+}
+
+const logger = new Logger();
+logger.pad2 = pad2;
+
+export default logger;

package/lib/ns-order.js

@@ -0,0 +1,76 @@
+import each from "lodash.foreach";
+import assert from "assert";
+
+class NSOrder {
+  constructor() {
+    this._namespaces = [];
+    this._overrides = {};
+  }
+
+  //
+  // make name order before overrides (string or array of string)
+  //
+  // the ordering is kept by an integer
+  // each new namespace is reset with a init value (default 1)
+  // then the max of values of its overrides is looked up
+  // if its value is not > max, then it's set to max + 1
+  // process repeated until all override max are smaller
+  //
+  // finally sort namespace by order value
+  //
+  add(name, overrides, priority = 1) {
+    let overrideMap = this._overrides[name];
+    if (!overrideMap) {
+      overrideMap = this._overrides[name] = { initValue: priority, others: [] };
+      this._namespaces.push(name);
+    }
+
+    if (!overrides) {
+      overrides = [];
+    } else if (!Array.isArray(overrides)) {
+      overrides = [overrides];
+    }
+
+    overrideMap.others = overrideMap.others.concat(overrides);
+
+    // do a first level circular check
+    each(this._overrides, (ov, ns) => {
+      if (ns !== name && overrideMap.others.indexOf(ns) >= 0 && ov.others.indexOf(name) >= 0) {
+        throw new Error(`circular namespace override between '${name}' and '${ns}'`);
+      }
+    });
+
+    // reset all values
+    each(this._overrides, v => (v.value = v.initValue));
+
+    // assign value base on override map
+    let done;
+    let n = 0;
+    do {
+      done = true;
+      each(this._overrides, ov => {
+        if (ov.others.length === 0) return;
+        const max = ov.others.reduce(
+          (max, oname) =>
+            Math.max((this._overrides[oname] && this._overrides[oname].value) || 0, max),
+          1
+        );
+        if (ov.value <= max) {
+          done = false;
+          ov.value = 1 + max;
+        }
+      });
+      n++;
+      assert(
+        n < 10,
+        "calculating namespace order looped too many times, there may be circular overrides"
+      );
+    } while (!done);
+
+    this._namespaces.sort((a, b) => this._overrides[b].value - this._overrides[a].value);
+
+    return this._namespaces;
+  }
+}
+
+export default NSOrder;

package/lib/print-tasks/index.js

@@ -0,0 +1,105 @@
+import stringify from "../stringify.js";
+import chalk from "../chalk.js";
+import assert from "assert";
+import Path from "path";
+import xsh from "xsh";
+
+const replaceCwd = p => xsh.pathCwdNm.replace(p, null, "g");
+
+const stringifyTask = x => {
+  x = stringify(x);
+  /* istanbul ignore next */
+  if (Path.sep === "\\") {
+    /* istanbul ignore next */
+    x = x.replace(/\\\\/g, "\\");
+  }
+  return replaceCwd(x);
+};
+
+const printNSTasks = (title, names, tasks) => {
+  let guideChar = ".";
+  let nameColor = "cyan";
+
+  const taskType = task => task !== null && task !== undefined && task.constructor.name;
+
+  const maxNameLen =
+    2 +
+    names.reduce((l, x) => {
+      const task = tasks[x];
+      if (taskType(task) === "Object" && !task.desc) {
+        return l;
+      }
+      return x.length > l ? x.length : l;
+    }, 0);
+
+  const printTask = name => {
+    const task = tasks[name];
+    const tof = taskType(task);
+
+    const paddedArr = new Array(Math.max(1, maxNameLen - name.length));
+    const paddedName = chalk[nameColor](`  ${name} ${paddedArr.join(guideChar)}`);
+    if (tof === "String") {
+      console.log(paddedName, chalk.magenta(replaceCwd(task)));
+    } else if (tof === "Array") {
+      console.log(paddedName, chalk.green(`${stringifyTask(task)}`));
+    } else if (tof === "Object") {
+      if (!task.desc) {
+        return;
+      }
+      console.log(paddedName, chalk.yellow(task.desc));
+      const spacePad = new Array(maxNameLen + 4).join(" ");
+      if (task.task) {
+        console.log(chalk.dim.green(`${spacePad}  tasks: ${stringifyTask(task.task)}`));
+      }
+      if (task.dep) {
+        console.log(chalk.dim.cyan(`${spacePad}  deps: ${stringifyTask(task.dep)}`));
+      }
+    } else if (tof === "Function") {
+      console.log(paddedName, "function", task.name);
+    } else if (tof === "XTaskSpec") {
+      console.log(paddedName, chalk.magenta(replaceCwd(task.toString())));
+    } else {
+      console.log(paddedName, chalk.red(`Unknown task type ${tof}`));
+    }
+    guideChar = guideChar === "." ? "-" : ".";
+    nameColor = nameColor === "cyan" ? "blue" : "cyan";
+  };
+
+  console.log(chalk.underline(title));
+  console.log("");
+
+  names.sort().forEach(printTask);
+  console.log("");
+};
+
+function printTasks(xtasks) {
+  const namespaces = xtasks._namespaces;
+  const tasks = xtasks._tasks;
+  namespaces.forEach(n => {
+    const nTasks = tasks[n];
+    assert(nTasks, `Task namespace ${n} is falsy`);
+    if (Object.keys(nTasks).length === 0) {
+      return;
+    }
+    console.log(chalk.inverse.bold.red(`Namespace '${n}'`));
+    const taskNames = Object.keys(nTasks).reduce((an, tn) => {
+      let lbl;
+      if (tn.match(/(^\.)|([$~])/)) {
+        lbl = "Hidden";
+      } else if (tn.match(/^[a-zA-Z_0-9]+$/)) {
+        lbl = "Primary";
+      } else {
+        lbl = "Other";
+      }
+      an[lbl] = an[lbl] || [];
+      an[lbl].push(tn);
+      return an;
+    }, {});
+    const isEmpty = x => !x || x.length === 0;
+    ["Primary", "Other"]
+      .filter(tt => !isEmpty(taskNames[tt]))
+      .forEach(tt => printNSTasks(chalk.bold(`${tt} Tasks`), taskNames[tt], nTasks));
+  });
+}
+
+export default printTasks;

package/lib/reporters/console.js

@@ -0,0 +1,133 @@
+import chalk from "../chalk.js";
+import logger from "../logger.js";
+import stringify from "../stringify.js";
+import assert from "assert";
+import defaults from "../defaults.js";
+import xsh from "xsh";
+
+class XReporterConsole {
+  constructor(xrun) {
+    this._xrun = xrun;
+    xrun.on("execute", data => this._onExecute(data));
+    xrun.on("done-item", data => this._onDoneItem(data));
+    xrun.on("run", () => (this._sep = ""));
+    xrun.on("not-found", err => {
+      this._logger.log(err.message);
+    });
+    xrun.once("warn-finally", () => {
+      logger.log(chalk.yellow("NOTE: finally hook is unreliable when stopOnError is set to full"));
+    });
+    this._tags = {};
+    this._logger = logger;
+  }
+
+  _log(qItem, msg) {
+    this._logger.log(`${this._indent(qItem)}${msg}`);
+    this._tags[qItem.id] = { sep: this._sep, msg };
+  }
+
+  _indent(qItem, sep) {
+    if (sep === undefined) {
+      this._sep = this._sep === "." ? "-" : ".";
+      sep = this._sep;
+    }
+    if (qItem.level) {
+      return chalk.magenta(new Array(qItem.level + 1).join(sep));
+    } else {
+      return "";
+    }
+  }
+
+  _onExecute(data) {
+    const m = `_onExeType_${data.type.replace(/-/g, "_")}`;
+    this[m](data);
+  }
+
+  _depMsg(qItem) {
+    const depDee = qItem.value().depDee;
+    const dep = depDee ? "'s dependency" : "";
+    return dep;
+  }
+
+  _onExeType_env(data) {
+    const qItem = data.qItem;
+    const name = this._itemDisplayName(qItem);
+    const str = data.cmdVal.toString();
+    const msg = `Execute ${name} setting ${chalk.blue(str)}`;
+    this._log(qItem, msg);
+  }
+
+  _onExeType_shell(data) {
+    const qItem = data.qItem;
+    const name = this._itemDisplayName(qItem);
+    let cmd;
+    if (data.cmdVal.constructor.name === "XTaskSpec") {
+      cmd = xsh.pathCwd.replace(data.cmdVal.toString(data.cmd2), ".", "g");
+    } else {
+      cmd = xsh.pathCwd.replace(data.cmd, ".", "g");
+    }
+    const msg = data.anon
+      ? `Execute ${chalk.cyan(cmd)}`
+      : `Execute ${name}${this._depMsg(qItem)} ${chalk.blue(cmd)}`;
+    this._log(qItem, msg);
+  }
+
+  _onExeType_lookup(_data) {
+    // do nothing
+  }
+
+  _onExeType_serial_arr(data) {
+    const qItem = data.qItem;
+    const name = this._itemDisplayName(qItem);
+    const ts = chalk.blue(stringify(data.array));
+    const msg = `Process ${name}${this._depMsg(qItem)} serial array ${ts}`;
+    this._log(qItem, msg);
+  }
+
+  _onExeType_concurrent_arr(data) {
+    const qItem = data.qItem;
+    const name = this._itemDisplayName(qItem);
+    const ts = chalk.blue(xsh.pathCwd.replace(stringify(data.array), ".", "g"));
+    const msg = `Process ${name}${this._depMsg(qItem)} concurrent array ${ts}`;
+    this._log(qItem, msg);
+  }
+
+  _onExeType_function(data) {
+    const qItem = data.qItem;
+    const name = this._itemDisplayName(qItem);
+    const anon = qItem.anon ? " anonymous " : " as ";
+    const msg = `Execute ${name}${this._depMsg(qItem)}${anon}function`;
+    this._log(qItem, msg);
+  }
+
+  _itemDisplayName(qItem) {
+    let ns = "";
+    const ix = qItem.name.indexOf(defaults.NS_SEP);
+    if (ix < 0) {
+      if (qItem.ns === defaults.NAMESPACE) {
+        ns = chalk.dim.cyan(qItem.ns);
+      } else if (qItem.ns) {
+        ns = chalk.dim.cyan(`${qItem.ns}${defaults.NS_SEP}`);
+      }
+    }
+    const finallyMsg = qItem.isFinally ? chalk.magenta(":finally") : "";
+    return `${ns}${chalk.cyan(qItem.name)}${finallyMsg}`;
+  }
+
+  _onDoneItem(data) {
+    // const qItem = data.qItem;
+    const xqItem = data.xqItem;
+    const elapseStr = `(${logger.formatElapse(data.elapse)})`;
+    const failed = !!this._xrun.failed || !!xqItem.err;
+    const result = xqItem.err ? "Failed" : "Done";
+    const status = failed ? chalk.red(result) : chalk.green(result);
+    const tag = this._tags[xqItem.id];
+    assert(tag, `console reporter no tag found for ${xqItem.name}`);
+
+    this._logger.log(
+      `${this._indent(xqItem, ">")}${status} ${tag.msg} ${chalk.magenta(elapseStr)}`
+    );
+  }
+}
+
+export default XReporterConsole;

package/lib/stringify.js

@@ -0,0 +1,16 @@
+export default data => {
+  try {
+    return JSON.stringify(data, (key, value) => {
+      if (typeof value === "function") {
+        return "func";
+      } else if (value.constructor.name === "XTaskSpec") {
+        return value.toString();
+      } else if (typeof value === "symbol") {
+        return `<${value.toString().match(/\(([^)]+)\)/)[1]}>`;
+      }
+      return value;
+    });
+  } catch (err) {
+    return `ERROR: ${err.message}`;
+  }
+};

package/lib/util/parse-array.js

@@ -0,0 +1,5 @@
+import * as stringArray from "string-array";
+
+export default function pa(str) {
+  return stringArray.parse(str, true, true).array; // noPrefix and noExtra
+};

package/lib/util/update-env.js

@@ -0,0 +1,16 @@
+export default function(env, target, override = true) {
+  target = target || process.env;
+  if (env) {
+    Object.keys(env).forEach(k => {
+      if (override === false && target.hasOwnProperty(k)) {
+        return;
+      }
+      if (env[k] === undefined || env[k] === null) {
+        delete target[k];
+      } else {
+        target[k] = env[k];
+      }
+    });
+  }
+  return target;
+};