depflow 3.0.0-dev.10 → 3.0.0-dev.11

package/dist/cli/Flags.js

@@ -0,0 +1,125 @@
+export class Flags {
+    /** The declared flags, kept at their declared type so the parsed values are inferred from them. */
+    declaration;
+    /** Maps every accepted name, canonical or alias, to the name of the flag declaring it. */
+    names;
+    /**
+     * Declares the flags accepted by a command line.
+     * @param declaration - The declared flags, keyed by the name each one is declared under.
+     * @throws { Error } When a name is declared or aliased twice, or when an alias carries a dash prefix.
+     */
+    constructor(declaration) {
+        this.declaration = declaration;
+        this.names = Flags.index(declaration);
+    }
+    /** The values a parsed command line carries when a flag is absent, taken from the declared defaults. **/
+    get defaults() {
+        const values = {};
+        for (const [name, flag] of Object.entries(this.declaration)) {
+            if ('default' in flag)
+                values[name] = flag.default;
+        }
+        return values;
+    }
+    /** The values parsed from a command line. Type-only: accessing it at runtime throws. **/
+    get infer() { throw new Error('Flags.infer is type-only.'); }
+    /**
+     * Extracts the positional arguments and the flag values of a command line.
+     * @param args - The command-line arguments.
+     * @returns The positional arguments and the values of the declared flags.
+     * @throws { Error } When a flag is not declared, or when a boolean flag carries a value other than "true" or "false".
+     *
+     * @remarks
+     * A flag is the whole token, so short clusters are not expanded: `-abc` is the single flag `-abc`.
+     * Names are matched without their dash prefix, so `-f` and `--flow` reach the same declaration.
+     * A boolean flag never consumes the following argument and only accepts `=true` or `=false` inline.
+     * A value flag takes the following argument as its value when that argument is not a flag; when it is,
+     * the value has to be written inline as `--flag=value`. The `--` terminator moves every remaining token
+     * to the positional arguments, and the last occurrence of a flag wins.
+     *
+     * @example
+     * ```ts
+     * const options = new Flags({
+     *     flow: { type: 'string', default: 'depflow.yml', aliases: [ 'f' ] },
+     *     cdn: { type: 'boolean', default: false }
+     * });
+     *
+     * const { args, flags } = options.parse([ '-f', 'depflow.yml', 'install', '--cdn' ]);
+     * // args  → [ 'install' ]
+     * // flags → { flow: 'depflow.yml', cdn: true }
+     * ```
+     */
+    parse(args) {
+        const positionals = [];
+        const values = {};
+        let parsing = true;
+        let index = 0;
+        while (parsing && index < args.length) {
+            const arg = args[index++];
+            if (arg === '--') {
+                parsing = false;
+                continue;
+            }
+            if (!Flags.isFlag(arg)) {
+                positionals.push(arg);
+                continue;
+            }
+            const separator = arg.indexOf('=');
+            const name = this.resolve(separator < 0 ? arg : arg.slice(0, separator));
+            if (name === undefined)
+                throw new Error(`Unknown flag: ${arg}`);
+            if (this.isBoolean(name)) {
+                const value = separator < 0 ? 'true' : arg.slice(separator + 1);
+                if (value !== 'true' && value !== 'false')
+                    throw new Error(`Invalid boolean value: ${arg}`);
+                values[name] = value === 'true';
+            }
+            else if (separator >= 0)
+                values[name] = arg.slice(separator + 1);
+            else if (index < args.length && !Flags.isFlag(args[index]))
+                values[name] = args[index++];
+        }
+        while (index < args.length)
+            positionals.push(args[index++]);
+        return { args: positionals, flags: { ...this.defaults, ...values } };
+    }
+    /**
+     * Resolves the token of a flag to the name of the flag declaring it.
+     * @param token - The token of the flag, without its inline value.
+     * @returns The name the flag is declared under, or `undefined` when no declaration accepts the token.
+     */
+    resolve(token) {
+        return this.names.get(token.replace(/^--?/, ''));
+    }
+    /**
+     * Whether a declared flag carries a boolean value, meaning it never consumes the following argument.
+     * @param name - The name the flag is declared under.
+     * @returns Whether the flag is declared as a boolean.
+     */
+    isBoolean(name) {
+        return this.declaration[name].type === 'boolean';
+    }
+    /** Whether an argument is a flag token, meaning a dash prefix longer than a single dash. **/
+    static isFlag(arg) { return arg.length > 1 && arg.startsWith('-'); }
+    /**
+     * Builds the lookup of every accepted name, canonical or alias, to the name of the flag declaring it.
+     * @param declaration - The declared flags.
+     * @returns The lookup of accepted names to declared names.
+     * @throws { Error } When a name is declared or aliased twice, or when an alias carries a dash prefix.
+     */
+    static index(declaration) {
+        const names = new Map();
+        for (const [name, flag] of Object.entries(declaration)) {
+            for (const alias of [name, ...flag.aliases ?? []]) {
+                if (alias.startsWith('-'))
+                    throw new Error(`Flag name must not carry a dash prefix: ${alias}`);
+                if (names.has(alias))
+                    throw new Error(`Duplicated flag name: ${alias}`);
+                names.set(alias, name);
+            }
+        }
+        return names;
+    }
+}
+export default Flags;
+//# sourceMappingURL=Flags.js.map

package/dist/cli/Flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Flags.js","sourceRoot":"","sources":["../../src/cli/Flags.ts"],"names":[],"mappings":"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"}

package/dist/cli/bin.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Command-line entry point: parses arguments and dispatches the invoked command to the CLI.
+ * @license Apache-2.0
+ */
+import Logger from "@netfeez/vterm";
+import DepFlowCLI, { options } from "./DepFLowCLI.js";
+const skip = 2;
+const [commandName, ...argsList] = process.argv.slice(skip);
+/**
+ * Reports a failure to the user and marks the process as failed.
+ *
+ * @remarks The failure is reported as one line through the logger, and not as a box painted with
+ * literals: the box was a second implementation of the decoration of vterm, it disappeared with
+ * `--decorate=false` while this one did not, and the summary it printed is not a per-command diagnostic,
+ * so the policy never printed it and nothing was duplicated.
+ *
+ * @remarks The channel is the one of the console interface, which every mode leaves visible: a verdict
+ * that fails while the screen says nothing at all is a verdict nobody can see, and the exit status is
+ * the signal of a user who is not looking.
+ *
+ * @remarks The status is marked with `process.exitCode` and not forced with `process.exit`, and this is
+ * the only way the evidence of a failing run reaches the `.vlog`: `vterm` feeds that file from a queue
+ * it flushes without anyone awaiting it, and a forced exit kills the process while the complete buffer
+ * of the commands is still in it. The status a user observes is the same one in both, because the run
+ * is already over by the time this is called; what changes is whether the transcript survives it.
+ *
+ * @param out - The logger or engine the failure is reported to.
+ * @param error - The failure, either an error or a message.
+ * @returns void
+ */
+function fail(out, error) {
+    out.error(`&C1${error?.message || error}`);
+    process.exitCode = 1;
+}
+let parsed;
+try {
+    parsed = options.parse(argsList);
+}
+catch (error) {
+    fail(new Logger(), error);
+}
+// A failed parse leaves nothing to dispatch: the invocation was never understood, so there is no command
+// to run and no CLI to run it with. The process still ends here, with the status `fail` marked.
+if (parsed !== undefined) {
+    const { args, flags } = parsed;
+    const cli = new DepFlowCLI(flags.flow);
+    try {
+        if (commandName !== null) {
+            const command = cli.getCommand(commandName);
+            if (command) {
+                const exec = command.exec;
+                await exec.call(cli, commandName, args, flags);
+            }
+            else {
+                cli.out.error(`Unknown command: ${commandName}`);
+                cli.getCommand('help')?.exec.call(cli, 'help', []);
+            }
+        }
+        else
+            cli.start();
+    }
+    catch (error) {
+        fail(cli.out, error);
+    }
+}
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA;;;;GAIG;AACH,OAAO,MAAuB,MAAM,gBAAgB,CAAC;AAErD,OAAO,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAGtD,MAAM,IAAI,GAAG,CAAC,CAAC;AACf,MAAM,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAS,IAAI,CAAC,GAAoB,EAAE,KAAU;IAC1C,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,EAAE,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,IAAI,MAAoD,CAAC;AACzD,IAAI,CAAC;IAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAAC,CAAC;AACzC,OAAO,KAAU,EAAE,CAAC;IAAC,IAAI,CAAC,IAAI,MAAM,EAAE,EAAE,KAAK,CAAC,CAAC;AAAC,CAAC;AAEjD,yGAAyG;AACzG,gGAAgG;AAChG,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;IACvB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC;IAC/B,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,CAAC;QACD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;YAC5C,IAAI,OAAO,EAAE,CAAC;gBACV,MAAM,IAAI,GAAG,OAAO,CAAC,IAAuB,CAAC;gBAC7C,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACnD,CAAC;iBAAM,CAAC;gBACJ,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,WAAW,EAAE,CAAC,CAAC;gBACjD,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;YACvD,CAAC;QACL,CAAC;;YAAM,GAAG,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QAClB,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzB,CAAC;AACL,CAAC"}