@flowscripter/dynamic-cli-framework 1.7.3 → 1.7.4

package/dist/src/cli/DefaultRuntimeCLI.js

@@ -0,0 +1,20 @@
+import process from "node:process";
+import BaseCLI from "./BaseCLI.js";
+import { Writable } from "node:stream";
+import TtyTerminal from "../terminal/TtyTerminal.js";
+import TtyKeyReader from "../terminal/TtyKeyReader.js";
+import TtyStyler from "../terminal/TtyStyler.js";
+import supportsColor from "supports-color";
+import supportsHyperlinks from "../terminal/supportsHyperlinks.js";
+/**
+ * Default Bun implementation of a {@link CLI} using `process.stdout`, `process.stderr` and `process.argv`.
+ */
+export default class DefaultRuntimeCLI extends BaseCLI {
+    constructor(cliConfig, options) {
+        super(cliConfig, Writable.toWeb(process.stdout), Writable.toWeb(process.stderr), supportsColor.stdout !== false, supportsColor.stderr !== false, new TtyTerminal(process.stdout), new TtyTerminal(process.stderr), new TtyStyler(supportsColor.stderr === false ? 1 : supportsColor.stderr.level, supportsHyperlinks(process.stderr)), new TtyKeyReader(process.stdin), { promptingEnabled: process.stdin.isTTY === true, ...options });
+    }
+    async run() {
+        const runResult = await super.run(process.argv.slice(2));
+        process.exit(runResult.runState);
+    }
+}

package/dist/src/cli/DynamicPluginRuntimeCLI.js

@@ -0,0 +1,50 @@
+import { RunState } from "../api/RunResult.js";
+import DefaultRuntimeCLI from "./DefaultRuntimeCLI.js";
+import DefaultPluginServiceProvider from "../service/plugin/DefaultPluginServiceProvider.js";
+import { DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT } from "../api/plugin/CommandFactory.js";
+import { DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT } from "../api/plugin/ServiceProviderFactory.js";
+import process from "node:process";
+/**
+ * Extension of {@link DefaultRuntimeCLI} that discovers and loads installed plugins before running.
+ *
+ * On each invocation of {@link run}, all locally installed plugins are discovered via the
+ * {@link MarketplacePluginManager}. Commands provided by {@link CommandFactory} extensions and
+ * service providers provided by {@link ServiceProviderFactory} extensions are registered before
+ * the runner starts, so they participate in the full initialization lifecycle.
+ */
+export default class DynamicPluginRuntimeCLI extends DefaultRuntimeCLI {
+    #pluginManager;
+    constructor(cliConfig, pluginManager, options) {
+        super(cliConfig, options);
+        this.#pluginManager = pluginManager;
+        this.addServiceProvider(new DefaultPluginServiceProvider(pluginManager));
+    }
+    async run() {
+        try {
+            await this.loadPlugins();
+        }
+        catch (err) {
+            console.error(err);
+            process.exit(RunState.RUNTIME_ERROR);
+        }
+        return super.run();
+    }
+    async loadPlugins() {
+        await this.#pluginManager.registerExtensions(DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT);
+        await this.#pluginManager.registerExtensions(DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT);
+        const commandFactoryExtensions = await this.#pluginManager.getRegisteredExtensions(DYNAMIC_CLI_FRAMEWORK_COMMAND_FACTORY_EXTENSION_POINT);
+        for (const ext of commandFactoryExtensions) {
+            const factory = (await this.#pluginManager.instantiate(ext.extensionHandle));
+            for (const command of factory.getCommands()) {
+                this.addCommand(command);
+            }
+        }
+        const spFactoryExtensions = await this.#pluginManager.getRegisteredExtensions(DYNAMIC_CLI_FRAMEWORK_SERVICE_PROVIDER_FACTORY_EXTENSION_POINT);
+        for (const ext of spFactoryExtensions) {
+            const factory = (await this.#pluginManager.instantiate(ext.extensionHandle));
+            for (const sp of factory.getServiceProviders()) {
+                this.addServiceProvider(sp);
+            }
+        }
+    }
+}

package/dist/src/command/MultiCommandCliHelpCommand.js

@@ -0,0 +1,238 @@
+import { ArgumentValueTypeName, } from "../api/argument/ArgumentValueTypes.js";
+import { findPossibleCommandNames, getCommandArgsHelpSections, getCommandExamplesHelpSections, getGlobalArgumentHelpEntry, getMultiCommandAppSyntax, getSubCommandArgumentsSyntax, printHelpSections, } from "../util/helpHelper.js";
+import { Icon, PRINTER_SERVICE_ID } from "../api/service/core/PrinterService.js";
+import { TABLE_GENERATOR_SERVICE_ID } from "../api/service/core/TableGeneratorService.js";
+/**
+ * Provides common implementation for both {@link MultiCommandCliHelpGlobalCommand} and {@link MultiCommandCliHelpSubCommand}.
+ */
+class MultiCommandCliAbstractHelpCommand {
+    name = "help";
+    description = "Display application help";
+    #includeEnvVars;
+    #commandRegistry;
+    constructor(includeEnvVars, commandRegistry) {
+        this.#includeEnvVars = includeEnvVars;
+        this.#commandRegistry = commandRegistry;
+    }
+    #getGlobalCommandsHelpSection(context, title, globalCommands) {
+        const globalCommandsSection = {
+            title,
+            helpEntries: [],
+        };
+        globalCommands.forEach((globalCommand) => {
+            const { syntax, description } = getGlobalArgumentHelpEntry(context.cliConfig, this.#includeEnvVars, globalCommand);
+            globalCommandsSection.helpEntries.push({
+                syntax: `--${globalCommand.name} ${syntax}`,
+                description,
+            });
+            if (globalCommand.shortAlias !== undefined) {
+                globalCommandsSection.helpEntries.push({
+                    syntax: `-${globalCommand.shortAlias} ${syntax}`,
+                    description,
+                });
+            }
+        });
+        globalCommandsSection.helpEntries.sort((a, b) => a.syntax.localeCompare(b.syntax));
+        return globalCommandsSection;
+    }
+    #getGenericHelpSections(context, globalModifierCommands, globalCommands, groupCommands, subCommands) {
+        const globalPrefix = groupCommands.length > 0 || subCommands.length > 0 ? "Global " : "";
+        const helpSections = [];
+        if (globalModifierCommands.length > 0) {
+            helpSections.push(this.#getGlobalCommandsHelpSection(context, `${globalPrefix}Options`, globalModifierCommands));
+        }
+        if (globalCommands.length > 0) {
+            helpSections.push(this.#getGlobalCommandsHelpSection(context, `${globalPrefix}Commands`, globalCommands));
+        }
+        groupCommands.forEach((groupCommand) => {
+            const visibleMemberSubCommands = groupCommand.memberSubCommands.filter((memberCommand) => !memberCommand.disableGenericHelpDisplay);
+            if (visibleMemberSubCommands.length === 0)
+                return;
+            const topicSection = {
+                title: `${groupCommand.name.charAt(0).toUpperCase() + groupCommand.name.slice(1)} Commands`,
+                helpEntries: [],
+            };
+            visibleMemberSubCommands.forEach((memberCommand) => {
+                topicSection.helpEntries.push({
+                    syntax: `${groupCommand.name}:${memberCommand.name}`,
+                    description: memberCommand.description,
+                });
+            });
+            topicSection.helpEntries.sort((a, b) => a.syntax.localeCompare(b.syntax));
+            helpSections.push(topicSection);
+        });
+        if (subCommands.length > 0) {
+            const subCommandsByTopic = new Map();
+            const otherSubCommands = [];
+            subCommands.forEach((subCommand) => {
+                if (subCommand.helpTopic === undefined) {
+                    otherSubCommands.push(subCommand);
+                }
+                else {
+                    const commands = subCommandsByTopic.get(subCommand.helpTopic) || [];
+                    commands.push(subCommand);
+                    subCommandsByTopic.set(subCommand.helpTopic, commands);
+                }
+            });
+            for (const key of subCommandsByTopic.keys()) {
+                const topicCommands = subCommandsByTopic.get(key);
+                if (topicCommands !== undefined) {
+                    const topicSection = {
+                        title: `${key.charAt(0).toUpperCase() + key.slice(1)} Commands`,
+                        helpEntries: [],
+                    };
+                    topicCommands.sort((a, b) => a.name.localeCompare(b.name));
+                    topicCommands.forEach((subCommand) => {
+                        topicSection.helpEntries.push({
+                            syntax: subCommand.name,
+                            description: subCommand.description,
+                        });
+                    });
+                    helpSections.push(topicSection);
+                }
+            }
+            if (otherSubCommands.length > 0) {
+                const topicSection = {
+                    title: subCommandsByTopic.size > 0 || groupCommands.length > 0
+                        ? "Other Commands"
+                        : "Sub-Commands",
+                    helpEntries: [],
+                };
+                otherSubCommands.sort((a, b) => a.name.localeCompare(b.name));
+                otherSubCommands.forEach((subCommand) => {
+                    topicSection.helpEntries.push({
+                        syntax: subCommand.name,
+                        description: subCommand.description,
+                    });
+                });
+                helpSections.push(topicSection);
+            }
+        }
+        return helpSections;
+    }
+    async printGenericHelp(context) {
+        const printerService = context.getServiceById(PRINTER_SERVICE_ID);
+        const tableGeneratorService = context.getServiceById(TABLE_GENERATOR_SERVICE_ID);
+        const globalModifierCommands = this.#commandRegistry
+            .getGlobalModifierCommands()
+            .filter((command) => !command.disableGenericHelpDisplay);
+        const globalCommands = this.#commandRegistry
+            .getGlobalCommands()
+            .filter((command) => !command.disableGenericHelpDisplay);
+        const groupCommands = this.#commandRegistry
+            .getGroupCommands()
+            .filter((command) => !command.disableGenericHelpDisplay);
+        const subCommands = this.#commandRegistry
+            .getSubCommands()
+            .filter((command) => !command.disableGenericHelpDisplay);
+        const helpSections = [];
+        helpSections.push({
+            title: "Usage",
+            helpEntries: [
+                {
+                    syntax: getMultiCommandAppSyntax(context, globalModifierCommands, globalCommands, groupCommands, subCommands),
+                },
+            ],
+        });
+        helpSections.push(...this.#getGenericHelpSections(context, globalModifierCommands, globalCommands, groupCommands, subCommands));
+        await printHelpSections(printerService, tableGeneratorService, helpSections);
+    }
+    async printUsageHelp(context, commandName) {
+        const printerService = context.getServiceById(PRINTER_SERVICE_ID);
+        const tableGeneratorService = context.getServiceById(TABLE_GENERATOR_SERVICE_ID);
+        const groupCommands = this.#commandRegistry
+            .getGroupCommands()
+            .filter((command) => !command.disableGenericHelpDisplay);
+        const subCommands = this.#commandRegistry
+            .getSubCommands()
+            .filter((command) => !command.disableGenericHelpDisplay);
+        // find sub-command or group sub-command
+        let subCommand = this.#commandRegistry.getSubCommandByName(commandName);
+        let groupCommand;
+        if (subCommand === undefined) {
+            const result = this.#commandRegistry.getGroupCommandAndMemberSubCommandByJoinedName(commandName);
+            if (result !== undefined) {
+                groupCommand = result.groupCommand;
+                subCommand = result.command;
+            }
+        }
+        if (subCommand === undefined) {
+            await printerService.print(`Unknown command: ${printerService.red(commandName)}\n\n`, Icon.FAILURE);
+            // look for other possible matches
+            const possibleCommandNames = findPossibleCommandNames(commandName, groupCommands, subCommands);
+            if (possibleCommandNames.length > 0) {
+                await printerService.print(`Possible matches: ${possibleCommandNames.join(", ")}\n\n`, Icon.INFORMATION);
+            }
+            await this.printGenericHelp(context);
+            return;
+        }
+        // display command help
+        const name = groupCommand === undefined ? subCommand.name : `${groupCommand.name}:${subCommand.name}`;
+        const helpSections = [];
+        if (subCommand.description !== undefined && subCommand.description.length > 0) {
+            helpSections.push({
+                title: "Command",
+                helpEntries: [
+                    {
+                        syntax: subCommand.name,
+                        description: subCommand.description,
+                    },
+                ],
+            });
+        }
+        helpSections.push({
+            title: "Usage",
+            helpEntries: [
+                {
+                    syntax: `${context.cliConfig.name}${name.length > 0 ? ` ${name}` : ""}${getSubCommandArgumentsSyntax(subCommand)}`,
+                },
+            ],
+        });
+        helpSections.push(...getCommandArgsHelpSections(context.cliConfig, this.#includeEnvVars, subCommand, false));
+        helpSections.push(...getCommandExamplesHelpSections(printerService, context, subCommand));
+        await printHelpSections(printerService, tableGeneratorService, helpSections);
+    }
+}
+/**
+ * Implementation of multi-command CLI help available via `myCli --help`, `myCli -h`, `myCli --help <command>` or `myCli -h <command>`.
+ */
+export class MultiCommandCliHelpGlobalCommand extends MultiCommandCliAbstractHelpCommand {
+    shortAlias = "h";
+    argument = {
+        name: "command",
+        type: ArgumentValueTypeName.STRING,
+        isOptional: true,
+    };
+    async execute(context, argumentValue) {
+        const commandName = argumentValue;
+        if (commandName !== undefined) {
+            await this.printUsageHelp(context, commandName);
+        }
+        else {
+            await this.printGenericHelp(context);
+        }
+    }
+}
+/**
+ * Implementation of multi-command CLI help available via `myCli help` or `myCli help <command>`.
+ */
+export class MultiCommandCliHelpSubCommand extends MultiCommandCliAbstractHelpCommand {
+    options = [];
+    positionals = [
+        {
+            name: "command",
+            type: ArgumentValueTypeName.STRING,
+            isVarargOptional: true,
+            description: "Display help for the specific <command>",
+        },
+    ];
+    async execute(context, argumentValues) {
+        const commandName = argumentValues["command"];
+        if (commandName !== undefined) {
+            await this.printUsageHelp(context, commandName);
+        }
+        else {
+            await this.printGenericHelp(context);
+        }
+    }
+}

package/dist/src/command/SingleCommandCliHelpCommand.js

@@ -0,0 +1,104 @@
+import { getCommandArgsHelpSections, getCommandExamplesHelpSections, getGlobalArgumentHelpEntry, getSubCommandArgumentsSyntax, printHelpSections, } from "../util/helpHelper.js";
+import { PRINTER_SERVICE_ID } from "../api/service/core/PrinterService.js";
+import { TABLE_GENERATOR_SERVICE_ID } from "../api/service/core/TableGeneratorService.js";
+/**
+ * Provides common implementation for both {@link SingleCommandCliHelpGlobalCommand} and {@link SingleCommandCliHelpSubCommand}.
+ */
+class SingleCommandCliAbstractHelpCommand {
+    #includeEnvVars;
+    #defaultCommand;
+    #commandRegistry;
+    constructor(includeEnvVars, defaultCommand, commandRegistry) {
+        this.#includeEnvVars = includeEnvVars;
+        this.#defaultCommand = defaultCommand;
+        this.#commandRegistry = commandRegistry;
+    }
+    name = "help";
+    description = "Display application help";
+    #getAmalgamatedGenericHelpSection(context, globalModifierCommands, globalCommands, groupCommands, subCommands) {
+        const helpSection = {
+            title: "Other Arguments",
+            helpEntries: [],
+        };
+        if (globalModifierCommands.length > 0) {
+            globalModifierCommands.forEach((globalModifierCommand) => {
+                const { syntax, description } = getGlobalArgumentHelpEntry(context.cliConfig, this.#includeEnvVars, globalModifierCommand);
+                helpSection.helpEntries.push({
+                    syntax: `--${globalModifierCommand.name} ${syntax}`,
+                    description,
+                });
+                if (globalModifierCommand.shortAlias !== undefined) {
+                    helpSection.helpEntries.push({
+                        syntax: `-${globalModifierCommand.shortAlias} ${syntax}`,
+                        description,
+                    });
+                }
+            });
+        }
+        if (globalCommands.length > 0) {
+            globalCommands.forEach((globalCommand) => {
+                const { syntax, description } = getGlobalArgumentHelpEntry(context.cliConfig, this.#includeEnvVars, globalCommand);
+                helpSection.helpEntries.push({
+                    syntax: `--${globalCommand.name} ${syntax}`,
+                    description,
+                });
+                if (globalCommand.shortAlias !== undefined) {
+                    helpSection.helpEntries.push({
+                        syntax: `-${globalCommand.shortAlias} ${syntax}`,
+                        description,
+                    });
+                }
+            });
+        }
+        groupCommands.forEach((groupCommand) => {
+            groupCommand.memberSubCommands.forEach((memberCommand) => {
+                helpSection.helpEntries.push({
+                    syntax: `${groupCommand.name}:${memberCommand.name}`,
+                    description: memberCommand.description,
+                });
+            });
+        });
+        if (subCommands.length > 0) {
+            subCommands.forEach((subCommand) => {
+                helpSection.helpEntries.push({
+                    syntax: subCommand.name,
+                    description: subCommand.description,
+                });
+            });
+        }
+        helpSection.helpEntries.sort((a, b) => a.syntax.localeCompare(b.syntax));
+        return helpSection;
+    }
+    async execute(context) {
+        const helpSections = [];
+        helpSections.push({
+            title: "Usage",
+            helpEntries: [
+                {
+                    syntax: `${context.cliConfig.name || ""}${getSubCommandArgumentsSyntax(this.#defaultCommand)}`,
+                },
+            ],
+        });
+        helpSections.push(...getCommandArgsHelpSections(context.cliConfig, this.#includeEnvVars, this.#defaultCommand, true));
+        const globalModifierCommands = this.#commandRegistry.getGlobalModifierCommands();
+        const globalCommands = this.#commandRegistry.getGlobalCommands();
+        helpSections.push(this.#getAmalgamatedGenericHelpSection(context, globalModifierCommands, globalCommands, [], []));
+        const printerService = context.getServiceById(PRINTER_SERVICE_ID);
+        const tableGeneratorService = context.getServiceById(TABLE_GENERATOR_SERVICE_ID);
+        helpSections.push(...getCommandExamplesHelpSections(printerService, context, this.#defaultCommand));
+        await printHelpSections(printerService, tableGeneratorService, helpSections);
+    }
+}
+/**
+ * Implementation of default command CLI help available via `myCli --help` or `myCli -h`.
+ */
+export class SingleCommandCliHelpGlobalCommand extends SingleCommandCliAbstractHelpCommand {
+    shortAlias = "h";
+}
+/**
+ * Implementation of default-command CLI help available via `myCli help`.
+ */
+export class SingleCommandCliHelpSubCommand extends SingleCommandCliAbstractHelpCommand {
+    options = [];
+    positionals = [];
+}

package/dist/src/command/UsageCommand.js

@@ -0,0 +1,16 @@
+import { PRINTER_SERVICE_ID } from "../api/service/core/PrinterService.js";
+/**
+ * Command printing basic CLI usage.
+ */
+export default class UsageCommand {
+    name = "usage";
+    description = "Show usage information";
+    #helpCommand;
+    constructor(helpCommand) {
+        this.#helpCommand = helpCommand;
+    }
+    async execute(context) {
+        const printerService = context.getServiceById(PRINTER_SERVICE_ID);
+        await printerService.print(`${printerService.secondary("Try running:")}\n\n  ${printerService.primary(context.cliConfig.name)} --${printerService.primary(this.#helpCommand.name)}\n\n`);
+    }
+}

package/dist/src/command/VersionCommand.js

@@ -0,0 +1,13 @@
+import { PRINTER_SERVICE_ID } from "../api/service/core/PrinterService.js";
+/**
+ * Implementation of a {@link GlobalCommand} which outputs the version of the CLI.
+ */
+export default class VersionCommand {
+    name = "version";
+    description = "Show version information";
+    shortAlias = "v";
+    async execute(context) {
+        const printerService = context.getServiceById(PRINTER_SERVICE_ID);
+        await printerService.print(`${context.cliConfig.version}\n`);
+    }
+}

package/dist/src/launcher.js

@@ -0,0 +1,61 @@
+import process from "node:process";
+import path from "node:path";
+import DefaultRuntimeCLI from "./cli/DefaultRuntimeCLI.js";
+import DynamicPluginRuntimeCLI from "./cli/DynamicPluginRuntimeCLI.js";
+export async function launchSingleCommandCLI(command, description, name, version, serviceProviders, options) {
+    if (!name) {
+        name = path.basename(process.execPath);
+    }
+    const cliConfig = {
+        description,
+        name,
+        version: version || "N/A",
+    };
+    const mergedOptions = {
+        ...options,
+        validateAllCommands: (options?.validateAllCommands ?? false) ||
+            process.env.DYNAMIC_CLI_FRAMEWORK_VALIDATE_ALL !== undefined,
+    };
+    const cli = new DefaultRuntimeCLI(cliConfig, mergedOptions);
+    cli.addCommand(command);
+    serviceProviders?.forEach((service) => cli.addServiceProvider(service));
+    return await cli.run();
+}
+export async function launchMultiCommandCLI(commands, description, name, version, serviceProviders, options) {
+    if (!name) {
+        name = path.basename(process.execPath);
+    }
+    const cliConfig = {
+        description,
+        name,
+        version: version || "N/A",
+    };
+    const mergedOptions = {
+        ...options,
+        validateAllCommands: (options?.validateAllCommands ?? false) ||
+            process.env.DYNAMIC_CLI_FRAMEWORK_VALIDATE_ALL !== undefined,
+    };
+    const cli = new DefaultRuntimeCLI(cliConfig, mergedOptions);
+    commands.forEach((command) => cli.addCommand(command));
+    serviceProviders?.forEach((service) => cli.addServiceProvider(service));
+    return await cli.run();
+}
+export async function launchDynamicPluginMultiCommandCLI(pluginManager, commands, description, name, version, serviceProviders, options) {
+    if (!name) {
+        name = path.basename(process.execPath);
+    }
+    const cliConfig = {
+        description,
+        name,
+        version: version || "N/A",
+    };
+    const mergedOptions = {
+        ...options,
+        validateAllCommands: (options?.validateAllCommands ?? false) ||
+            process.env.DYNAMIC_CLI_FRAMEWORK_VALIDATE_ALL !== undefined,
+    };
+    const cli = new DynamicPluginRuntimeCLI(cliConfig, pluginManager, mergedOptions);
+    commands.forEach((command) => cli.addCommand(command));
+    serviceProviders?.forEach((service) => cli.addServiceProvider(service));
+    return await cli.run();
+}

package/dist/src/runtime/DefaultContext.js

@@ -0,0 +1,25 @@
+/**
+ * Default implementation of a {@link Context}.
+ */
+export default class DefaultContext {
+    cliConfig;
+    #serviceInstancesById = new Map();
+    constructor(cliConfig) {
+        this.cliConfig = cliConfig;
+    }
+    addServiceInstance(id, serviceInstance) {
+        if (this.#serviceInstancesById.has(id)) {
+            throw new Error(`Service ID: ${id} duplicates the ID of an existing service`);
+        }
+        this.#serviceInstancesById.set(id, serviceInstance);
+    }
+    getServiceById(id) {
+        if (!this.#serviceInstancesById.has(id)) {
+            throw new Error(`Service with ID: ${id} does not exist`);
+        }
+        return this.#serviceInstancesById.get(id);
+    }
+    doesServiceExist(id) {
+        return this.#serviceInstancesById.has(id);
+    }
+}

package/dist/src/runtime/argument/ArgumentTypeGuards.js

@@ -0,0 +1,3 @@
+export function isComplexOption(argument) {
+    return argument.properties !== undefined;
+}

package/dist/src/runtime/command/CommandTypeGuards.js

@@ -0,0 +1,12 @@
+export function isGroupCommand(command) {
+    return command.memberSubCommands !== undefined;
+}
+export function isSubCommand(command) {
+    return command.options !== undefined;
+}
+export function isGlobalModifierCommand(command) {
+    return command.executePriority !== undefined;
+}
+export function isGlobalCommand(command) {
+    return !isGroupCommand(command) && !isSubCommand(command) && !isGlobalModifierCommand(command);
+}