@fynjs/run 1.1.0 → 1.1.1

package/{lib → dist/lib}/defaults.js

@@ -1,6 +1,5 @@
 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];
@@ -12,21 +11,19 @@ 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
+    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/dist/lib/gen-xqid.d.ts

@@ -0,0 +1,2 @@
+export default _default;
+declare function _default(tag?: any): string;

package/dist/lib/gen-xqid.js

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

package/dist/lib/index.d.ts

@@ -0,0 +1,3 @@
+declare const xrun: any;
+export default xrun;
+export { xrun as "module.exports" };

package/{lib → dist/lib}/index.js

@@ -1,9 +1,6 @@
 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

package/dist/lib/logger.d.ts

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

package/dist/lib/logger.js

@@ -0,0 +1,95 @@
+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(...args) {
+        const msg = args.join(" ");
+        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/dist/lib/my-pkg.d.ts

@@ -0,0 +1,4 @@
+/** directory of this package's own manifest - the root of this copy of @fynjs/run */
+export declare const myPkgDir: string;
+declare const _default: any;
+export default _default;

package/dist/lib/my-pkg.js

@@ -0,0 +1,42 @@
+import Fs from "fs";
+import Path from "path";
+//
+// This package's own manifest, and the directory holding it.
+//
+// It used to be `import myPkg from "../package.json" with { type: "json" }` in six files. That
+// cannot survive the build: tsc pulls the JSON into the program and emits a COPY at
+// dist/package.json, and that copy - name "@fynjs/run", `main` "./dist/lib/index.js" - then
+// becomes what node's self-reference resolution finds when anything inside dist/ requires
+// "@fynjs/run". It resolved to dist/dist/lib/index.js and the bin died before printing anything.
+//
+// Walking up to the first manifest that is actually ours works from source (lib/) and from the
+// build (dist/lib/) alike, and emits no JSON.
+//
+const findOwnPkg = () => {
+    let dir = import.meta.dirname;
+    for (;;) {
+        const file = Path.join(dir, "package.json");
+        if (Fs.existsSync(file)) {
+            try {
+                const json = JSON.parse(Fs.readFileSync(file, "utf8"));
+                if (json.name === "@fynjs/run") {
+                    return { json, dir };
+                }
+            }
+            catch {
+                // unreadable or malformed - keep walking rather than dying at import time
+            }
+        }
+        const parent = Path.dirname(dir);
+        // walking past the filesystem root means this file is not inside its own package at all
+        /* istanbul ignore next */
+        if (parent === dir) {
+            return { json: {}, dir: import.meta.dirname };
+        }
+        dir = parent;
+    }
+};
+const own = findOwnPkg();
+/** directory of this package's own manifest - the root of this copy of @fynjs/run */
+export const myPkgDir = own.dir;
+export default own.json;

package/dist/lib/ns-order.d.ts

@@ -0,0 +1,7 @@
+declare class NSOrder {
+    _namespaces: any;
+    _overrides: any;
+    constructor();
+    add(name: any, overrides: any, priority?: number): any;
+}
+export default NSOrder;

package/dist/lib/ns-order.js

@@ -0,0 +1,62 @@
+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
+        for (const [ns, ov] of Object.entries(this._overrides)) {
+            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
+        for (const v of Object.values(this._overrides)) {
+            v.value = v.initValue;
+        }
+        // assign value base on override map
+        let done;
+        let n = 0;
+        do {
+            done = true;
+            for (const ov of Object.values(this._overrides)) {
+                if (ov.others.length === 0)
+                    continue;
+                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/dist/lib/print-tasks/index.d.ts

@@ -0,0 +1,2 @@
+declare function printTasks(xtasks: any): void;
+export default printTasks;

package/dist/lib/print-tasks/index.js

@@ -0,0 +1,100 @@
+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/dist/lib/reporters/console.d.ts

@@ -0,0 +1,20 @@
+declare class XReporterConsole {
+    _logger: any;
+    _sep: any;
+    _tags: any;
+    _xrun: any;
+    constructor(xrun: any);
+    _log(qItem: any, msg: any): void;
+    _indent(qItem: any, sep?: any): string;
+    _onExecute(data: any): void;
+    _depMsg(qItem: any): "" | "'s dependency";
+    _onExeType_env(data: any): void;
+    _onExeType_shell(data: any): void;
+    _onExeType_lookup(_data: any): void;
+    _onExeType_serial_arr(data: any): void;
+    _onExeType_concurrent_arr(data: any): void;
+    _onExeType_function(data: any): void;
+    _itemDisplayName(qItem: any): string;
+    _onDoneItem(data: any): void;
+}
+export default XReporterConsole;

package/dist/lib/reporters/console.js

@@ -0,0 +1,119 @@
+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/dist/lib/stringify.d.ts

@@ -0,0 +1,2 @@
+export default _default;
+declare function _default(data: any): string;

package/dist/lib/stringify.js

@@ -0,0 +1,19 @@
+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/dist/lib/util/parse-array.d.ts

@@ -0,0 +1,2 @@
+import * as stringArray from "string-array";
+export default function pa(str: any): stringArray.StringArray[];

package/dist/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/dist/lib/util/task-options.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Normalize task option specifications into @fynjs/cli-args compatible OptionSpec.
+ * Supports:
+ * - Native @fynjs/cli-args spec: { required: true, args: "<val string>", alias: "f" }
+ * - Shorthand args without value name: { args: "<string>" } -> { args: "<val string>" }
+ * - Legacy format: { require: true, type: "string", alias: "f" }
+ * - Legacy array format: { type: "array" } -> { args: "[val string..]" }
+ * - Legacy count format: { type: "count" } -> { counting: Infinity }
+ *
+ * @param {Record<string, any>} rawOpts - Raw options dictionary
+ * @returns {Record<string, any>} Normalized options dictionary
+ */
+export declare function normalizeTaskOptions(rawOpts?: Record<string, any>): Record<string, any>;
+/**
+ * Normalize subcommand definitions so nested options and commands are properly structured.
+ *
+ * @param {Record<string, any>} rawCmds - Raw commands dictionary
+ * @returns {Record<string, any>} Normalized commands dictionary
+ */
+export declare function normalizeTaskCommands(rawCmds?: Record<string, any>): Record<string, any>;
+/**
+ * Extract and normalize option specifications for a given task definition.
+ *
+ * @param {any} task - Task item or task object
+ * @returns {{ options: Record<string, any>, commands: Record<string, any>, allowUnknownOption?: boolean }}
+ */
+export declare function getTaskOptionSpec(task: any): {
+    options: Record<string, any>;
+    commands: Record<string, any>;
+    allowUnknownOption?: boolean;
+};
+declare const _default: {
+    normalizeTaskOptions: typeof normalizeTaskOptions;
+    normalizeTaskCommands: typeof normalizeTaskCommands;
+    getTaskOptionSpec: typeof getTaskOptionSpec;
+};
+export default _default;