@fynjs/run 1.0.0

package/lib/xqtree.js

@@ -0,0 +1,41 @@
+import XQItem from "./xqitem.js";
+
+class XQTree {
+  constructor() {
+    this.tree = {};
+    this._items = {};
+  }
+
+  create(options, parent) {
+    options = Object.assign({ parent }, options);
+
+    const x = new XQItem(options);
+    this._items[x.id] = x;
+
+    if (parent) {
+      parent.addChild(x);
+      x.level = parent.level !== undefined ? parent.level + 1 : 0;
+    } else {
+      this.tree[x.id] = x;
+      x.level = 0;
+    }
+
+    return x;
+  }
+
+  parent(qItem) {
+    const x = this._items[qItem.parentId];
+    return x;
+  }
+
+  parentName(qItem) {
+    const parent = this.parent(qItem);
+    return parent && parent.name;
+  }
+
+  item(id) {
+    return this._items[id];
+  }
+}
+
+export default XQTree;

package/lib/xrun-instance.js

@@ -0,0 +1,33 @@
+import XRun from "./xrun.js";
+import XReporterConsole from "../lib/reporters/console.js";
+import XTaskSpec from "./xtask-spec.js";
+
+function createXrunInstance() {
+  const xrun = new XRun({});
+  xrun[Symbol("reporter")] = new XReporterConsole(xrun);
+
+  xrun.load = xrun.load.bind(xrun);
+  xrun.run = xrun.run.bind(xrun);
+  xrun.asyncRun = xrun.asyncRun.bind(xrun);
+
+  xrun.XClap = XRun;
+  xrun.XRun = XRun;
+  xrun.XTaskSpec = XTaskSpec;
+  xrun.XReporterConsole = XReporterConsole;
+
+  return xrun;
+}
+
+const container = {
+  createXrunInstance,
+  _xrun: createXrunInstance(),
+  get xrun() {
+    return this._xrun || this.reset();
+  },
+  reset() {
+    return (this._xrun = createXrunInstance());
+  }
+};
+
+export { createXrunInstance };
+export default container;

package/lib/xrun.d.ts

@@ -0,0 +1,89 @@
+import { EventEmitter } from "events";
+
+// Type for task execution options
+interface TaskOptions {
+  flags?: string | string[];
+  [key: string]: any;
+}
+
+// Type for task specification
+interface TaskSpec {
+  cmd: string | string[];
+  flags?: string | string[];
+  [key: string]: any;
+}
+
+// Type for environment update options
+interface EnvUpdateOptions {
+  override?: boolean;
+  posix?: boolean;
+}
+
+// Type for namespace and tasks
+interface TasksDefinition {
+  [key: string]: any;
+}
+
+// Type for XTaskSpec class
+declare class XTaskSpec {
+  constructor(spec: TaskSpec);
+}
+
+// Type for XTasks class
+declare class XTasks {
+  constructor(namespace: string | object, tasks?: TasksDefinition);
+  load(tasks: TasksDefinition): void;
+  load(namespace: string | object, tasks: TasksDefinition, priority?: number): void;
+  hasFinally(): boolean;
+  count(): number;
+  fullNames(): string[];
+}
+
+// Type for XQTree class
+declare class XQTree {
+  create(options: { name: string; value?: any }): any;
+}
+
+// Type for the main XRun class
+declare class XRun extends EventEmitter {
+  constructor(namespace?: string | object, tasks?: TasksDefinition);
+
+  // Properties
+  failed: Error | null;
+  stopOnError: boolean | "soft" | "full" | "";
+
+  // Methods
+  load(tasks: TasksDefinition): this;
+  load(namespace: string | object, tasks: TasksDefinition, priority?: number): this;
+  run(tasks: string | any[], done?: (err?: Error | Error[]) => void): this;
+  asyncRun(tasks: string | any[]): Promise<any>;
+  printTasks(): this;
+  countTasks(): number;
+  getNamespaces(): object;
+  fail(err: Error): this;
+  waitAllPending(done: () => void): this;
+  stop(): symbol;
+  exec(spec: string | string[] | TaskSpec, options?: string | string[] | TaskOptions): XTaskSpec;
+  updateEnv(envValues: object, options?: EnvUpdateOptions): void;
+  env(spec: object, options?: EnvUpdateOptions): void;
+  concurrent(...tasks: any[]): any[];
+  parallel(...tasks: any[]): any[];
+  serial(...tasks: any[]): any[];
+
+  // Internal methods
+  private _exitOnError(err: Error | Error[]): void;
+  private _showSimilarTasks(res: { name: string }): void;
+  private exit(code: number): void;
+  private killTaskChildren(): void;
+  private actStop(): void;
+}
+
+// Type for the xrun instance
+declare const xrun: XRun & {
+  XClap: typeof XRun;
+  XRun: typeof XRun;
+  XTaskSpec: typeof XTaskSpec;
+  XReporterConsole: any;
+};
+
+export = xrun;

package/lib/xrun.js

@@ -0,0 +1,344 @@
+import assert from "assert";
+import defaults from "./defaults.js";
+import chalk from "./chalk.js";
+import XQtor from "./xqtor.js";
+import XTasks from "./xtasks.js";
+import XQTree from "./xqtree.js";
+import logger from "./logger.js";
+import EventEmitter from "events";
+import printTasks from "./print-tasks/index.js";
+import jaroWinkler from "jaro-winkler";
+import XTaskSpec from "./xtask-spec.js";
+import xsh from "xsh";
+import updateEnv from "./util/update-env.js";
+import myPkg from "../package.json" with { type: "json" };
+import { CliContext } from "./cli-context.js";
+import { exec } from "child_process";
+
+// full - full stop, interrupting all pending async tasks
+// soft - allow pending async tasks to complete, but no more new tasks
+// "" - march on
+const STOP_ON_ERROR = ["", "soft", "full"];
+
+function _decorateTasks(type, name, ...tasks) {
+  assert(tasks.length > 0, `${name} no tasks passed`);
+  tasks = tasks.filter(x => x);
+  if (tasks.length === 1) {
+    tasks = tasks[0];
+    // user passed single argument that's not an array
+    // assume it's a single task where serial/concurrent is N/A
+    if (!Array.isArray(tasks)) return tasks;
+  }
+
+  return [type].concat(tasks);
+}
+
+function _concurrent(...tasks) {
+  return _decorateTasks(defaults.CONCURRENT_SYM, "xrun.concurrent", ...tasks);
+}
+
+class XRun extends EventEmitter {
+  constructor(namespace, tasks) {
+    super();
+    this._tasks = new XTasks(namespace, tasks);
+    this.failed = null;
+    this.xqTree = new XQTree();
+    this._logger = logger;
+    this._pending = 0;
+    this._taskChildren = {};
+    this._isStop = false;
+    this._cliContext = new CliContext({});
+    this.on("spawn-async", () => this._pending++);
+    this.on("done-async", () => this._pending--);
+  }
+
+  get stopOnError() {
+    return this._stopOnError;
+  }
+
+  set stopOnError(v) {
+    if (v === false) {
+      this._stopOnError = "";
+    } else if (v === true) {
+      this._stopOnError = "full";
+    } else {
+      assert(
+        STOP_ON_ERROR.indexOf(v) >= 0,
+        `stopOnError must be true or false, or one of ${STOP_ON_ERROR.map(JSON.stringify).join(
+          ", "
+        )}`
+      );
+      this._stopOnError = v;
+    }
+  }
+
+  // priority: lower value => lower priority when searching namespace for a task
+  load(namespace, tasks, priority = 1) {
+    this._tasks.load(namespace, tasks, priority);
+    return this;
+  }
+
+  addTaskChild(child, sym) {
+    this._taskChildren[sym] = child;
+    return this._taskChildren;
+  }
+
+  removeTaskChild(child, sym) {
+    delete this._taskChildren[sym];
+    return this._taskChildren;
+  }
+
+  /**
+   * Kill a child process in a cross-platform manner and mark it as stopped
+   * @param {import('child_process').ChildProcess|any} child - Child process to kill
+   */
+  killChildProcess(child) {
+    /* istanbul ignore next */
+    if (!child) return;
+    /* istanbul ignore next */
+    if (process.platform === "win32" && child.pid) {
+      try {
+        /* istanbul ignore next */
+        exec(`taskkill /T /F /PID ${child.pid}`);
+      } catch (err) {
+        /* istanbul ignore next */
+        try {
+          child.kill();
+        } catch (e) {
+          // ignore
+        }
+      }
+    } else {
+      try {
+        child.kill();
+      } catch (err) {
+        // ignore
+      }
+    }
+    child[defaults.STOP_SYM] = true;
+  }
+
+  /**
+   * Set the CLI context for this XRun instance
+   * @param {CliContext} cliContext - Command context object
+   * @returns {XRun} This instance for chaining
+   */
+  setCliContext(cliContext) {
+    this._cliContext = cliContext;
+    return this;
+  }
+
+  /**
+   * Get the current CLI context
+   * @returns {CliContext|null} Current CLI context
+   */
+  getCliContext() {
+    return this._cliContext;
+  }
+
+  asyncRun(tasks) {
+    return new Promise((resolve, reject) => {
+      this.run(tasks, (err, result) => {
+        if (err) reject(err);
+        else resolve(result);
+      });
+    });
+  }
+
+  run(tasks, done) {
+    if (this.stopOnError === undefined) {
+      this.stopOnError = true;
+    }
+    if (this._tasks.hasFinally() && this.stopOnError === "full") {
+      this.emit("warn-finally");
+    }
+    done = done || this._exitOnError.bind(this);
+    const xqtor = new XQtor({ tasks: this._tasks, done, xrun: this });
+
+    try {
+      if (typeof tasks === "string") {
+        this.emit("run", { name: tasks });
+        xqtor.pushItem(this.xqTree.create({ name: tasks }));
+      } else {
+        this.emit("run", { tasks: tasks });
+        xqtor.pushItem(this.xqTree.create({ name: "run", value: tasks }));
+      }
+      xqtor.next();
+    } catch (err) {
+      done([err]);
+    }
+    return this;
+  }
+
+  printTasks() {
+    printTasks(this._tasks);
+    return this;
+  }
+
+  countTasks() {
+    return this._tasks.count();
+  }
+
+  getNamespaces() {
+    return this._tasks._namespaces;
+  }
+
+  fail(err) {
+    if (!this.failed) {
+      this.failed = err;
+    } else {
+      this.failed.more = this.failed.more || [];
+      this.failed.more.push(err);
+    }
+    return this;
+  }
+
+  waitAllPending(done) {
+    const wait = () => {
+      if (this._pending === 0) {
+        return done();
+      }
+      setTimeout(wait, 10);
+    };
+    process.nextTick(wait);
+    return this;
+  }
+
+  _showSimilarTasks(res) {
+    const names = this._tasks.fullNames();
+    const distances = names
+      .map(name => {
+        name = name.split("/")[1];
+        if (name.startsWith(".")) return false;
+        const dis = jaroWinkler(res.name, name) * 100000;
+        return { dis, name };
+      })
+      .filter(x => x)
+      .sort((a, b) => b.dis - a.dis);
+    const similars = distances.slice(0, 5).map(x => chalk.cyan(x.name));
+    console.log(`  Maybe try: ${similars.join(", ")}`);
+  }
+
+  _exitOnError(err) {
+    if (!err) {
+      return;
+    }
+
+    console.log(chalk.bold.red.inverse(" Execution Failed - Errors: "));
+    const errors = [].concat(err, err.more).filter(x => x);
+    errors.forEach((e, x) => {
+      const idx = chalk.bold.red.inverse(` ${x + 1} `);
+      if (!e.stack) {
+        console.log(idx, e);
+        return;
+      }
+      const lines = e.stack.split("\n");
+      console.log(idx, e.message);
+      if (e.name && e.name.indexOf("AssertionError") >= 0) return;
+      if (e.code === "TASK_NOT_FOUND") {
+        this._showSimilarTasks(e.res);
+        return;
+      }
+      if (lines.length < 2) return;
+      if (lines[1].indexOf("xsh/lib/exec.js") >= 0) return;
+      const cleaned = lines.filter(l => {
+        return (
+          // exclude stack for node.js internal modules and xrun's own files
+          !l.includes(`(internal/`) &&
+          !l.includes("/node_modules/xclap/lib/") &&
+          !l.includes(`/node_modules/${myPkg.name}/lib`)
+        );
+      });
+      // start at 1 to exclude the message that's the first line in stack output
+      for (let i = 1; i < cleaned.length; i++) {
+        console.log(
+          chalk.gray(
+            /* istanbul ignore next */
+            process.cwd().length > 2 ? xsh.pathCwd.replace(cleaned[i], ".", "g") : cleaned[i]
+          )
+        );
+      }
+    });
+    this.exit(1);
+  }
+
+  exit(code) {
+    if (this.stopOnError) {
+      // Check if there are any child processes to clean up
+      const hasChildren = Object.getOwnPropertySymbols(this._taskChildren).length > 0;
+
+      if (hasChildren) {
+        // Kill all tracked child processes before exiting
+        this.killTaskChildren();
+        // Give kill operations time to complete (especially on Windows with taskkill)
+        setTimeout(() => {
+          process.exit(code);
+        }, 100);
+      } else {
+        // No children to clean up, exit immediately
+        process.exit(code);
+      }
+    }
+  }
+
+  killTaskChildren() {
+    setTimeout(() => {
+      const children = this._taskChildren;
+      this._taskChildren = {};
+      const symbols = Object.getOwnPropertySymbols(children);
+      symbols.forEach(sym => {
+        const child = children[sym];
+        this.killChildProcess(child);
+      });
+    }, 10);
+  }
+
+  actStop() {
+    this.killTaskChildren();
+    this._isStop = true;
+  }
+
+  stop() {
+    return defaults.STOP_SYM;
+  }
+
+  exec(spec, options) {
+    if (Array.isArray(spec) || typeof spec === "string") {
+      if (typeof options === "string" || Array.isArray(options)) {
+        options = { flags: options };
+      }
+      return new XTaskSpec(Object.assign({ cmd: spec }, options));
+    } else if (typeof spec === "object") {
+      return new XTaskSpec(spec);
+    } else {
+      throw new Error(
+        `xrun.exec - unknown spec type ${typeof spec}: must be a string, array, or an object`
+      );
+    }
+  }
+
+  updateEnv(envValues, options = {}) {
+    return updateEnv(envValues, options.target || process.env, options.override);
+  }
+
+  env(spec, options) {
+    return new XTaskSpec(Object.assign({ ...options, type: "env", env: spec }));
+  }
+
+  // concurrent([task1, task2, ...]) or concurrent(task1, task2, ...)
+  concurrent(...tasks) {
+    return _concurrent(...tasks);
+  }
+
+  // alias for concurrent
+  parallel(...tasks) {
+    return _concurrent(...tasks);
+  }
+
+  // serial([task1, task2, ...]) or concurrent(task1, task2, ...)
+  serial(...tasks) {
+    return _decorateTasks(defaults.SERIAL_SYM, "xrun.serial", ...tasks);
+  }
+}
+
+export default XRun;

package/lib/xtask-spec.js

@@ -0,0 +1,63 @@
+import { mkCmd } from "xsh";
+
+class XTaskSpec {
+  constructor(spec) {
+    this.type = spec.type || "exec";
+
+    const cmd = spec.cmd || spec.command;
+    if (Array.isArray(cmd)) {
+      this.cmd = mkCmd(...cmd);
+    } else {
+      this.cmd = cmd;
+    }
+
+    // gather execOptions from spec
+    const execOptions = Object.assign({}, spec.execOptions);
+    const env = Object.assign({}, execOptions.env, spec.env);
+    if (Object.keys(env).length) {
+      execOptions.env = env;
+    }
+    this.options = execOptions;
+    if (this.type === "env") {
+      this.options.override = spec.override;
+    }
+    //
+    this.flags = spec.flags || {};
+    this.xrun = Object.assign({ delayRunMs: 0 }, spec.xrun || spec.xclap);
+  }
+
+  toString(trailing) {
+    const makeEnvStr = s => {
+      let envStr = "";
+      const env = this.options.env;
+      if (env) {
+        envStr = `${s}{${Object.keys(env)
+          .map(k => `${k}=${env[k]}`)
+          .join(";")}}`;
+      }
+      return envStr;
+    };
+    if (this.type === "exec") {
+      let flags = this.flags;
+
+      if (Array.isArray(flags)) {
+        flags = flags.join(",");
+      } else if (typeof flags === "object") {
+        flags = Object.keys(flags).join(",");
+      }
+
+      if (flags) {
+        flags = `(${flags})`;
+      }
+
+      const _t = (trailing && ` ${trailing}`) || "";
+      return `exec${flags}${makeEnvStr(" ")} '${this.cmd}${_t}'`;
+    } else if (this.type === "env") {
+      return `env${makeEnvStr("")}`;
+    }
+
+    return `XTaskSpec - Unknown type ${this.type}`;
+  }
+}
+
+export default XTaskSpec;

package/lib/xtasks.js

@@ -0,0 +1,137 @@
+import assert from "assert";
+import defaults from "./defaults.js";
+import NSOrder from "./ns-order.js";
+
+class XTasks {
+  constructor(namespace, tasks) {
+    this._tasks = { [defaults.NAMESPACE]: {} };
+    this._nsOrder = new NSOrder();
+    if (namespace) {
+      this.load(namespace, tasks);
+    } else {
+      this._namespaces = [defaults.NAMESPACE];
+    }
+  }
+
+  load(namespace, tasks, priority = 1) {
+    let overrides;
+    if (tasks === undefined) {
+      tasks = namespace;
+      namespace = defaults.NAMESPACE;
+    } else if (typeof namespace === "object") {
+      overrides = namespace.overrides;
+      namespace = namespace.namespace;
+    }
+
+    assert(tasks && typeof tasks === "object", "Invalid tasks");
+
+    if (this._tasks[namespace] === undefined) {
+      this._tasks[namespace] = {};
+    }
+
+    if (namespace !== defaults.NAMESPACE) {
+      this._nsOrder.add(namespace, overrides, priority);
+    }
+
+    this._namespaces = [defaults.NAMESPACE].concat(this._nsOrder._namespaces);
+
+    Object.assign(this._tasks[namespace], tasks);
+  }
+
+  count() {
+    return this._namespaces.reduce((x, ns) => {
+      return x + Object.keys(this._tasks[ns]).length;
+    }, 0);
+  }
+
+  names(ns) {
+    return (ns || this._namespaces).reduce((x, ns) => {
+      return x.concat(Object.keys(this._getNsTasks(ns)));
+    }, []);
+  }
+
+  fullNames(ns) {
+    return (ns || this._namespaces).reduce((x, ns) => {
+      const nsTasks = this._getNsTasks(ns);
+      return x.concat(
+        Object.keys(nsTasks).map(t =>
+          ns === defaults.NAMESPACE ? `${defaults.NS_SEP}${t}` : `${ns}${defaults.NS_SEP}${t}`
+        )
+      );
+    }, []);
+  }
+
+  lookup(name) {
+    const invalidName = "Empty task name is invalid";
+    assert(name, invalidName);
+    name = name.trim();
+
+    let optional = false;
+    // If there's a prefix ? then the execution is optional
+    if (name.startsWith("?")) {
+      optional = true;
+      name = name.substr(1).trim();
+    }
+    assert(name, invalidName);
+    let res = { name };
+    const nsSepIdx = name.indexOf(defaults.NS_SEP);
+    // no NS_SEP found
+    if (nsSepIdx < 0) {
+      res = this._searchNamespaces(name);
+    } else {
+      if (nsSepIdx === 0) {
+        res.ns = defaults.NAMESPACE;
+        res.name = name.substr(1);
+      } else {
+        res.ns = name.substring(0, nsSepIdx).trim();
+        assert(res.ns, `Invalid namespace in task name ${name}`);
+        res.name = name.substring(nsSepIdx + 1);
+      }
+      const nsTasks = this._getNsTasks(res.ns);
+      assert(res.name, `Empty task name from '${name}' is invalid`);
+      res.item = nsTasks[res.name];
+    }
+    if (!res.item) {
+      const opt = optional ? "Optional " : "";
+      const err = new Error(
+        `${opt}Task ${res.name}${res.ns ? " in namespace " + res.ns : ""} not found`
+      );
+      err.optional = optional;
+      err.res = res;
+      err.code = "TASK_NOT_FOUND";
+      throw err;
+    }
+    return res;
+  }
+
+  hasFinally() {
+    for (const ns of this._namespaces) {
+      const tasks = this._tasks[ns];
+      for (const name in tasks) {
+        if (tasks[name].hasOwnProperty("finally")) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  _getNsTasks(ns) {
+    const x = this._tasks[ns];
+    assert(x, `No task namespace ${ns} exist`);
+    return x;
+  }
+
+  _searchNamespaces(name) {
+    const ns = this._namespaces;
+    for (var i = 0; i < ns.length; i++) {
+      const x = this._tasks[ns[i]][name];
+      if (x) {
+        return { ns: ns[i], name, item: x, search: true };
+      }
+    }
+    return { name };
+  }
+}
+
+export default XTasks;