depflow 3.0.0-dev.1 → 3.0.0-dev.11

package/dist/cli/CLI.js

@@ -0,0 +1,214 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description The console interface the CLI is built on: it reads a command, runs it and answers it,
+ *              and it draws the help the global flags and the arguments of every command are told in.
+ * @license Apache-2.0
+ */
+import { Logger, ConsoleUI } from '@netfeez/vterm';
+/** The visible column the description of a flag or an argument starts at, in `help`. **/
+const HELP_COLUMN = 26;
+export class CLI {
+    /** What reads the input of the console interface. */
+    dataHandleInstance;
+    /** What is written before every command the interface reads. */
+    prompt;
+    /** The input the interface reads commands from. */
+    in;
+    /** The engine the interface answers through. */
+    out;
+    /** The commands the interface accepts, keyed by the name each one is invoked with. */
+    commandMap;
+    /** The terminal the prompt and the help are written to. */
+    console;
+    /** The flags that are not specific to a command, keyed by the name each one is declared under. */
+    globals;
+    /** The branded line the help opens with. */
+    title;
+    /**
+     * Wires a console interface to its terminal, its global flags and its commands.
+     * @param globals - The flags no command owns, declared as `Flags` declares them.
+     * @param config - How the interface presents itself: the name of its runs, its prompt and its title.
+     */
+    constructor(globals = {}, config = {}) {
+        this.dataHandleInstance = this.dataHandler.bind(this);
+        this.prompt = ConsoleUI.formatText(config.prompt ?? '&C5[CLI] << &C6&S');
+        this.in = process.stdin;
+        const logger = new Logger({ name: config.name ?? 'CLI' });
+        this.out = logger.engine;
+        this.console = logger.console;
+        this.globals = globals;
+        this.title = config.title ?? '&C1CLI';
+        this.commandMap = {};
+        this.addDefaultCommands();
+    }
+    /** Starts reading what is written to the input. **/
+    startReadIn() {
+        this.in.on('data', this.dataHandleInstance);
+        this.console.write(this.prompt);
+    }
+    /** Stops reading what is written to the input. **/
+    stopReadIn() { this.in.off('data', this.dataHandleInstance); }
+    /** Starts the console UI. **/
+    start() { this.startReadIn(); }
+    /** Stops the console UI. **/
+    stop() { this.stopReadIn(); }
+    /**
+     * Runs the command the input carries, and writes the prompt again unless the command leaves.
+     * @param data - What arrived in the input.
+     * @returns A promise of the command being over.
+     */
+    async dataHandler(data) {
+        const [cmd, ...args] = data.toString('utf-8').trim().split(' ');
+        this.out.log(`&C(80,0,80)command received: &C3${cmd}`, args);
+        try {
+            const command = this.commandMap[cmd];
+            if (command)
+                await command.exec.bind(this)(cmd, args);
+            else
+                this.out.error(`&C1Unknown command: &C3${cmd}`);
+        }
+        catch (error) {
+            this.out.error(`&C1Error executing command: &C3${cmd}`, error);
+        }
+        if (cmd !== 'exit-debug')
+            this.console.write(this.prompt);
+    }
+    /**
+     * The command of that name, when the map carries one.
+     * @param command - The name of the command.
+     * @returns The command, or undefined when the map carries no command of that name.
+     */
+    getCommand(command) { return this.commandMap[command]; }
+    /**
+     * Puts a command in the map.
+     * @param command - The name of the command.
+     * @param exec - What the command does when it is written.
+     * @param info - What `help` tells about it, the arguments it accepts among it.
+     * @returns This instance, so commands can be added one after another.
+     */
+    addCommand(command, exec, info) {
+        this.commandMap[command] = { name: command, exec, ...info };
+        return this;
+    }
+    /**
+     * Takes a command out of the map.
+     * @param command - The name of the command.
+     * @returns This instance, so commands can be removed one after another.
+     */
+    removeCommand(command) {
+        delete this.commandMap[command];
+        return this;
+    }
+    /**
+     * Puts the commands every console interface carries in the map.
+     **/
+    addDefaultCommands() {
+        this.addCommand('help', this.showHelp.bind(this), { description: '&C6Shows this help', usage: 'help' });
+        this.addCommand('exit', () => process.exit(), { description: '&C6Exits the process', usage: 'exit' });
+    }
+    /**
+     * Writes the banner, the global flags and every command of the map with its usage, its description
+     * and the arguments it accepts.
+     *
+     * @remarks The help belongs to the terminal and not to a run, so it is written as it is composed
+     * and it is not announced through the engine: no timestamp, level or name is put in front of it,
+     * and a line is only broken where this method breaks it.
+     **/
+    showHelp() {
+        const width = Math.max(40, Math.min(process.stdout.columns ?? 80, 100));
+        const box = '&C5';
+        const lines = [this.title, '', '&C6Global flags:'];
+        for (const [name, flag] of Object.entries(this.globals)) {
+            const key = CLI.flagKey(name, flag);
+            lines.push(...CLI.describe(key, flag.description ?? '', width));
+        }
+        lines.push('', '&C6Commands:');
+        for (const command of Object.values(this.commandMap)) {
+            lines.push(`&C3 > ${command.name}`);
+            if (command.usage)
+                lines.push(`   &C7Usage: &C6${command.usage}`);
+            if (command.description)
+                lines.push(...CLI.wrap(command.description, width - 5).map(line => `   ${line}`));
+            for (const [name, argument] of Object.entries(command.args ?? {})) {
+                lines.push(...CLI.describe(CLI.argumentKey(name, argument), argument.description, width, 5));
+            }
+            lines.push('');
+        }
+        const edge = `${box}╭${'─'.repeat(width - 2)}`;
+        this.console.log(edge);
+        for (const line of lines)
+            this.console.log(`${box}│ ${line}`);
+        this.console.log(`${box}╰${'─'.repeat(width - 2)}`);
+    }
+    /**
+     * The name of a flag as the help writes it, with the aliases it accepts and the value it takes.
+     * @param name - The name the flag is declared under.
+     * @param flag - The declared flag.
+     * @returns The name of the flag, colored.
+     */
+    static flagKey(name, flag) {
+        const names = [name, ...flag.aliases ?? []].map(alias => alias.length === 1 ? `-${alias}` : `--${alias}`);
+        const value = flag.type === 'boolean' ? '' : ' &C7<string>';
+        return `&C3${names.join(', ')}${value}`;
+    }
+    /**
+     * The name of an argument as the help writes it, telling an optional one and a variadic one apart.
+     * @param name - The name the argument is declared under.
+     * @param argument - The declared argument.
+     * @returns The name of the argument, colored.
+     */
+    static argumentKey(name, argument) {
+        const core = argument.variadic ? `${name}...` : name;
+        const written = (argument.required ?? true) ? `<${core}>` : `[${core}]`;
+        return `&C3${written}`;
+    }
+    /**
+     * Lays out a name and what it is for in the columns left after the name.
+     * @param key - The name, with the tokens that color it.
+     * @param description - What the name is for.
+     * @param width - The visible width every line is kept within.
+     * @param indent - The visible columns the entry starts at.
+     * @returns The lines of the entry, the description broken in as many lines as it needs.
+     */
+    static describe(key, description, width, indent = 3) {
+        const column = indent + HELP_COLUMN;
+        const lead = ' '.repeat(indent);
+        const padding = ' '.repeat(Math.max(1, column - indent - CLI.visibleWidth(key)));
+        const available = Math.max(20, width - column);
+        const wrapped = CLI.wrap(description, available);
+        if (wrapped.length === 0)
+            return [`${lead}${key}`];
+        return wrapped.map((line, index) => index === 0
+            ? `${lead}${key}${padding}&C7${line}`
+            : `${' '.repeat(column)}&C7${line}`);
+    }
+    /**
+     * Breaks a text in as many lines as it needs to fit a visible width, on its word boundaries.
+     * @param text - The text to break, without tokens in it.
+     * @param width - The visible width every line is kept within.
+     * @returns The lines the text was broken in.
+     */
+    static wrap(text, width) {
+        const lines = [];
+        let current = '';
+        for (const word of text.split(' ')) {
+            if (current && CLI.visibleWidth(current) + 1 + CLI.visibleWidth(word) > width) {
+                lines.push(current);
+                current = word;
+            }
+            else
+                current = current ? `${current} ${word}` : word;
+        }
+        if (current)
+            lines.push(current);
+        return lines;
+    }
+    /**
+     * The columns a text paints, with its tokens taken out.
+     * @param text - The text to measure, with the tokens of the grammar in it.
+     * @returns The number of visible columns it paints.
+     */
+    static visibleWidth(text) { return ConsoleUI.cleanFormat(text).length; }
+}
+export default CLI;
+//# sourceMappingURL=CLI.js.map

package/dist/cli/CLI.js.map

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

package/dist/cli/DepFLowCLI.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Main CLI surface: dependency management commands, builds and config conversions.
+ * @license Apache-2.0
+ */
+import CLI from "./CLI.js";
+import OutputPolicy from "../task/OutputPolicy.js";
+import Flags from "./Flags.js";
+/** The flags accepted by every command of the CLI. **/
+export declare const options: Flags<{
+    readonly flow: {
+        readonly type: "string";
+        readonly default: "depflow.yml";
+        readonly aliases: readonly ["p", "f"];
+        readonly description: "Path to the configuration file the command operates on.";
+    };
+    readonly watch: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly aliases: readonly ["w"];
+        readonly description: "Keeps watching the built files and rewrites their paths on every change.";
+    };
+    readonly cdn: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Resolves the dependency paths to their CDN target instead of their local one.";
+    };
+    readonly verbose: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly aliases: readonly ["v"];
+        readonly description: "Streams the output of every command as it runs, attributed to the command that wrote it, instead of only reporting how each of them ended. The indentation of that output is lost, and the complete buffer of every command reaches the evidence file whether this flag is given or not.";
+    };
+    readonly silent: {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly description: "Says only what failed, one line per failed command. It silences the progress of DepFlow itself, such as \"Installing dependencies...\", and not the help, which belongs to the console interface. The exit status and the evidence file are the same as in any other mode.";
+    };
+    readonly decorate: {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "Draws boxes, indentation, timestamps, levels and names around what is reported. --decorate=false leaves the content alone and keeps the color of the markers and the diagnostics, which carry information and are not decoration.";
+    };
+}>;
+export declare class DepFlowCLI extends CLI {
+    readonly configPath: string;
+    protected readonly projectRoot: string;
+    constructor(configPath?: string);
+    /** Absolute path of the flow directory (`.depflow`) under the project root. **/
+    protected get flowDirectory(): string;
+    /**
+     * The policy the run is presented through, built for the mode the flags asked for.
+     * @param flags - The flags of the command being run.
+     * @returns The policy of the run, never `null`: the evidence is written whether it is asked for or not.
+     *
+     * @remarks The policy is also what settles the channel the lifecycle of the CLI is reported through, so
+     * every command asks for it first and reports through `policy.report`: a `silent` run that said
+     * "Installing dependencies..." would not be silent, and an undecorated run would still draw boxes
+     * around lines that carry nothing but what they say.
+     *
+     * @remarks A command reports through the policy and not through `this.out`, which belongs to the
+     * console interface DepFlow was built on: the help, the prompt and the verdict of an invocation are
+     * drawn by surfaces DepFlow does not own, and they stay visible in every mode.
+     *
+     * @example
+     * ```ts
+     * const policy = this.policy(flags);
+     * const out = policy.report;
+     * if (policy.decoration === 'on') out.group(Group.create('#FFB4DC'));
+     * ```
+     */
+    protected policy(flags: DepFlowCLI.Options): OutputPolicy;
+    commandAdd(command: string, args: string[], flags?: DepFlowCLI.Options): Promise<void>;
+    commandRemove(command: string, args: string[], flags?: DepFlowCLI.Options): Promise<void>;
+    commandInstall(command: string, args: string[], flags?: DepFlowCLI.Options): Promise<void>;
+    commandRun(command: string, args: string[], flags?: DepFlowCLI.Options): Promise<void>;
+    list(command: string, args: string[], flags?: DepFlowCLI.Options): Promise<void>;
+    rewritePaths(command: string, args: string[], flags?: DepFlowCLI.Options): Promise<void>;
+    commandSync(command: string, args: string[], flags?: DepFlowCLI.Options, caller?: OutputPolicy): Promise<void>;
+    /**
+     * Converts the depflow config file between JSON and YAML.
+     * @param command - The invoked command name ('json-to-yaml' or 'yaml-to-json').
+     * @param args - Optional output file path.
+     * @param flags - The flags of the command being run, which settle how the conversion is reported.
+     */
+    convert(command: string, args: string[], flags?: DepFlowCLI.Options): Promise<void>;
+}
+export declare namespace DepFlowCLI {
+    type Exec = (this: DepFlowCLI, command: string, args: string[], flags: Options) => Promise<void> | void;
+    /** The values of the flags accepted by the CLI. **/
+    type Options = typeof options.infer;
+}
+export default DepFlowCLI;