@decaf-ts/cli 0.6.0 → 0.8.0

package/lib/types/CliWrapper.d.cts

@@ -0,0 +1,156 @@
+import { Command } from "commander";
+import { LoggedClass } from "@decaf-ts/logging";
+/**
+ * @description Utility class to handle CLI functionality from all Decaf modules
+ * @summary This class provides a wrapper around Commander.js to handle CLI commands from different Decaf modules.
+ * It crawls the filesystem to find CLI modules, loads them, and registers their commands.
+ *
+ * @param {string} [basePath] The base path to look for modules in. Defaults to `./`
+ * @param {number} [crawlLevels] Number of folder levels to crawl to find modules from the basePath. Defaults to 4
+ *
+ * @example
+ * // Create a new CLI wrapper and run it with custom options
+ * const cli = new CliWrapper('./src', 2);
+ * cli.run(process.argv).then(() => {
+ *   console.log('CLI commands executed successfully');
+ * });
+ *
+ * @class CliWrapper
+ */
+export declare class CliWrapper extends LoggedClass {
+    private basePath;
+    private crawlLevels;
+    private _command?;
+    private modules;
+    private includedModuleNames;
+    private readonly rootPath;
+    private moduleSlogans;
+    private globalSlogans;
+    private readonly logLevelAttached;
+    private bannerPrinted;
+    private static env;
+    constructor(basePath?: string, crawlLevels?: number);
+    /**
+     * @description Retrieves and initializes the Commander Command object
+     * @summary Lazy-loads the Command object, initializing it with the package name, description, and version
+     * @return {Command} The initialized Command object
+     * @private
+     */
+    private get command();
+    /**
+     * @description Loads and registers a module from a file
+     * @summary Dynamically imports a CLI module from the specified file path, initializes it, and registers it in the modules collection
+     *
+     * @param {string} filePath Path to the module file to load
+     * @param {string} rootPath Repository root path to find the package.json
+     * @return {Promise<string>} A promise that resolves to the module name
+     *
+     * @private
+     * @mermaid
+     * sequenceDiagram
+     *   participant CliWrapper
+     *   participant CLIUtils
+     *   participant Module
+     *
+     *   CliWrapper->>CLIUtils: loadFromFile(filePath)
+     *   CLIUtils-->>CliWrapper: module
+     *   CliWrapper->>CliWrapper: Get module name
+     *   CliWrapper->>Command: new Command()
+     *   Command-->>CliWrapper: cmd
+     *   CliWrapper->>CLIUtils: initialize(cmd, path.dirname(rootPath))
+     *   CliWrapper->>Module: module()
+     *   Note over CliWrapper,Module: Handle Promise if needed
+     *   Module-->>CliWrapper: Command instance
+     *   CliWrapper->>CliWrapper: Store in modules[name]
+     *   CliWrapper-->>CliWrapper: Return name
+     */
+    private load;
+    private registerModule;
+    /**
+     * @description Finds and loads all CLI modules in the basePath
+     * @summary Uses the crawl method to find all CLI modules in the specified base path,
+     * then loads and registers each module as a subcommand
+     *
+     * @return {Promise<void>} A promise that resolves when all modules are loaded
+     *
+     * @private
+     * @mermaid
+     * sequenceDiagram
+     *   participant CliWrapper
+     *   participant Filesystem
+     *   participant Module
+     *
+     *   CliWrapper->>Filesystem: Join basePath with cwd
+     *   CliWrapper->>CliWrapper: crawl(basePath, crawlLevels)
+     *   CliWrapper-->>CliWrapper: modules[]
+     *   loop For each module
+     *     alt Not @decaf-ts/cli
+     *       CliWrapper->>CliWrapper: load(module, cwd)
+     *       CliWrapper-->>CliWrapper: name
+     *       CliWrapper->>CliWrapper: Check if command exists
+     *       alt Command doesn't exist
+     *         CliWrapper->>Command: command(name).addCommand(modules[name])
+     *       end
+     *     end
+     *   end
+     *   CliWrapper->>Console: Log loaded modules
+     */
+    private boot;
+    private loadIncludedModules;
+    private loadModulesFromPath;
+    private getScopePackageRoots;
+    private findEnclosingNodeModules;
+    private getSiblingPackageRoots;
+    private getHostPath;
+    private getPackageNameFromRoot;
+    private ensureLogLevelSupport;
+    private updateLogLevel;
+    private resolveLogLevel;
+    /**
+     * @description Recursively searches for CLI module files in the directory structure
+     * @summary Crawls the basePath up to the specified number of folder levels to find files named according to CLI_FILE_NAME
+     *
+     * @param {string} basePath The absolute base path to start searching in
+     * @param {number} [levels=2] The maximum number of directory levels to crawl
+     * @return {string[]} An array of file paths to CLI modules
+     *
+     * @private
+     */
+    private crawl;
+    private findModuleRoot;
+    protected getSlogan(priorityModule?: string): string;
+    private otherSlogans;
+    private buildBalancedSloganPool;
+    private repeatToLength;
+    private ensureGlobalSlogans;
+    private collectSlogansFromPath;
+    private collectSlogansFromScope;
+    private collectSlogansFromSiblingPackages;
+    private extractSloganStrings;
+    private isCommandInstance;
+    protected printBanner(args?: string[]): () => void;
+    private getPriorityModule;
+    /**
+     * @description Executes the CLI with the provided arguments
+     * @summary Boots the CLI by loading all modules, then parses and executes the command specified in the arguments
+     *
+     * @param {string[]} [args=process.argv] Command line arguments to parse and execute
+     * @return {Promise<void>} A promise that resolves when the command execution is complete
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client
+     *   participant CliWrapper
+     *   participant Command
+     *
+     *   Client->>CliWrapper: run(args)
+     *   CliWrapper->>CliWrapper: boot()
+     *   Note over CliWrapper: Loads all modules
+     *   CliWrapper->>Command: parseAsync(args)
+     *   Command-->>CliWrapper: result
+     *   CliWrapper-->>Client: result
+     */
+    run(args?: string[]): Promise<Command>;
+    static accumulateEnvironment(obj: object): void;
+    static getEnv(): any;
+}

package/lib/types/CliWrapper.d.mts

@@ -0,0 +1,156 @@
+import { Command } from "commander";
+import { LoggedClass } from "@decaf-ts/logging";
+/**
+ * @description Utility class to handle CLI functionality from all Decaf modules
+ * @summary This class provides a wrapper around Commander.js to handle CLI commands from different Decaf modules.
+ * It crawls the filesystem to find CLI modules, loads them, and registers their commands.
+ *
+ * @param {string} [basePath] The base path to look for modules in. Defaults to `./`
+ * @param {number} [crawlLevels] Number of folder levels to crawl to find modules from the basePath. Defaults to 4
+ *
+ * @example
+ * // Create a new CLI wrapper and run it with custom options
+ * const cli = new CliWrapper('./src', 2);
+ * cli.run(process.argv).then(() => {
+ *   console.log('CLI commands executed successfully');
+ * });
+ *
+ * @class CliWrapper
+ */
+export declare class CliWrapper extends LoggedClass {
+    private basePath;
+    private crawlLevels;
+    private _command?;
+    private modules;
+    private includedModuleNames;
+    private readonly rootPath;
+    private moduleSlogans;
+    private globalSlogans;
+    private readonly logLevelAttached;
+    private bannerPrinted;
+    private static env;
+    constructor(basePath?: string, crawlLevels?: number);
+    /**
+     * @description Retrieves and initializes the Commander Command object
+     * @summary Lazy-loads the Command object, initializing it with the package name, description, and version
+     * @return {Command} The initialized Command object
+     * @private
+     */
+    private get command();
+    /**
+     * @description Loads and registers a module from a file
+     * @summary Dynamically imports a CLI module from the specified file path, initializes it, and registers it in the modules collection
+     *
+     * @param {string} filePath Path to the module file to load
+     * @param {string} rootPath Repository root path to find the package.json
+     * @return {Promise<string>} A promise that resolves to the module name
+     *
+     * @private
+     * @mermaid
+     * sequenceDiagram
+     *   participant CliWrapper
+     *   participant CLIUtils
+     *   participant Module
+     *
+     *   CliWrapper->>CLIUtils: loadFromFile(filePath)
+     *   CLIUtils-->>CliWrapper: module
+     *   CliWrapper->>CliWrapper: Get module name
+     *   CliWrapper->>Command: new Command()
+     *   Command-->>CliWrapper: cmd
+     *   CliWrapper->>CLIUtils: initialize(cmd, path.dirname(rootPath))
+     *   CliWrapper->>Module: module()
+     *   Note over CliWrapper,Module: Handle Promise if needed
+     *   Module-->>CliWrapper: Command instance
+     *   CliWrapper->>CliWrapper: Store in modules[name]
+     *   CliWrapper-->>CliWrapper: Return name
+     */
+    private load;
+    private registerModule;
+    /**
+     * @description Finds and loads all CLI modules in the basePath
+     * @summary Uses the crawl method to find all CLI modules in the specified base path,
+     * then loads and registers each module as a subcommand
+     *
+     * @return {Promise<void>} A promise that resolves when all modules are loaded
+     *
+     * @private
+     * @mermaid
+     * sequenceDiagram
+     *   participant CliWrapper
+     *   participant Filesystem
+     *   participant Module
+     *
+     *   CliWrapper->>Filesystem: Join basePath with cwd
+     *   CliWrapper->>CliWrapper: crawl(basePath, crawlLevels)
+     *   CliWrapper-->>CliWrapper: modules[]
+     *   loop For each module
+     *     alt Not @decaf-ts/cli
+     *       CliWrapper->>CliWrapper: load(module, cwd)
+     *       CliWrapper-->>CliWrapper: name
+     *       CliWrapper->>CliWrapper: Check if command exists
+     *       alt Command doesn't exist
+     *         CliWrapper->>Command: command(name).addCommand(modules[name])
+     *       end
+     *     end
+     *   end
+     *   CliWrapper->>Console: Log loaded modules
+     */
+    private boot;
+    private loadIncludedModules;
+    private loadModulesFromPath;
+    private getScopePackageRoots;
+    private findEnclosingNodeModules;
+    private getSiblingPackageRoots;
+    private getHostPath;
+    private getPackageNameFromRoot;
+    private ensureLogLevelSupport;
+    private updateLogLevel;
+    private resolveLogLevel;
+    /**
+     * @description Recursively searches for CLI module files in the directory structure
+     * @summary Crawls the basePath up to the specified number of folder levels to find files named according to CLI_FILE_NAME
+     *
+     * @param {string} basePath The absolute base path to start searching in
+     * @param {number} [levels=2] The maximum number of directory levels to crawl
+     * @return {string[]} An array of file paths to CLI modules
+     *
+     * @private
+     */
+    private crawl;
+    private findModuleRoot;
+    protected getSlogan(priorityModule?: string): string;
+    private otherSlogans;
+    private buildBalancedSloganPool;
+    private repeatToLength;
+    private ensureGlobalSlogans;
+    private collectSlogansFromPath;
+    private collectSlogansFromScope;
+    private collectSlogansFromSiblingPackages;
+    private extractSloganStrings;
+    private isCommandInstance;
+    protected printBanner(args?: string[]): () => void;
+    private getPriorityModule;
+    /**
+     * @description Executes the CLI with the provided arguments
+     * @summary Boots the CLI by loading all modules, then parses and executes the command specified in the arguments
+     *
+     * @param {string[]} [args=process.argv] Command line arguments to parse and execute
+     * @return {Promise<void>} A promise that resolves when the command execution is complete
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Client
+     *   participant CliWrapper
+     *   participant Command
+     *
+     *   Client->>CliWrapper: run(args)
+     *   CliWrapper->>CliWrapper: boot()
+     *   Note over CliWrapper: Loads all modules
+     *   CliWrapper->>Command: parseAsync(args)
+     *   Command-->>CliWrapper: result
+     *   CliWrapper-->>Client: result
+     */
+    run(args?: string[]): Promise<Command>;
+    static accumulateEnvironment(obj: object): void;
+    static getEnv(): any;
+}

package/lib/types/banners.d.cts

@@ -0,0 +1,3 @@
+export declare const mainBanner = "";
+export declare const banners: string[];
+export declare const colorPalettes: Record<string, string[]>;

package/lib/types/banners.d.mts

@@ -0,0 +1,3 @@
+export declare const mainBanner = "";
+export declare const banners: string[];
+export declare const colorPalettes: Record<string, string[]>;

package/lib/types/bin/cli.d.cts

@@ -0,0 +1,25 @@
+/**
+ * BIN_CALL_PLACEHOLDER - DO NOT REMOVE
+ */
+/**
+ * @description Decaf-ts' CLI entry point
+ * @summary This file serves as the main executable entry point for the Decaf CLI. It creates a CliWrapper instance
+ * and runs it with the process arguments. The CLI will crawl the current working directory for files called
+ * CLI_FILE_NAME within the @decaf-ts namespace and load them as subcommands.
+ *
+ * @example
+ * // Run a module command
+ * $ npx decaf <module name> <module command> ...<module command options>
+ *
+ * // Get help for a specific module
+ * $ npx decaf help <module name>
+ *
+ * // List all imported modules
+ * $ npx decaf list
+ *
+ * // Get general CLI help
+ * $ npx decaf help
+ *
+ * @memberOf module:CLI
+ */
+export {};

package/lib/types/bin/cli.d.mts

@@ -0,0 +1,25 @@
+/**
+ * BIN_CALL_PLACEHOLDER - DO NOT REMOVE
+ */
+/**
+ * @description Decaf-ts' CLI entry point
+ * @summary This file serves as the main executable entry point for the Decaf CLI. It creates a CliWrapper instance
+ * and runs it with the process arguments. The CLI will crawl the current working directory for files called
+ * CLI_FILE_NAME within the @decaf-ts namespace and load them as subcommands.
+ *
+ * @example
+ * // Run a module command
+ * $ npx decaf <module name> <module command> ...<module command options>
+ *
+ * // Get help for a specific module
+ * $ npx decaf help <module name>
+ *
+ * // List all imported modules
+ * $ npx decaf list
+ *
+ * // Get general CLI help
+ * $ npx decaf help
+ *
+ * @memberOf module:CLI
+ */
+export {};

package/lib/types/build-module/cli-module.d.cts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function buildModule(): Command;

package/lib/types/build-module/cli-module.d.mts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function buildModule(): Command;

package/lib/types/constants.d.cts

@@ -0,0 +1,8 @@
+/**
+ * @description The filename that identifies Decaf CLI modules
+ * @summary The standard filename for CLI module files where each library must export a single CliModule function
+ *
+ * @const CLI_FILE_NAME
+ * @memberOf module:CLI
+ */
+export declare const CLI_FILE_NAME = "cli-module";

package/lib/types/constants.d.mts

@@ -0,0 +1,8 @@
+/**
+ * @description The filename that identifies Decaf CLI modules
+ * @summary The standard filename for CLI module files where each library must export a single CliModule function
+ *
+ * @const CLI_FILE_NAME
+ * @memberOf module:CLI
+ */
+export declare const CLI_FILE_NAME = "cli-module";

package/lib/types/environment.d.cts

@@ -0,0 +1,7 @@
+import { LoggingConfig } from "@decaf-ts/logging";
+export type DecafCliEnvironment = LoggingConfig & {
+    banner: boolean;
+    cliModuleRoot: string;
+};
+export declare const DefaultCliEnvironment: DecafCliEnvironment;
+export declare const DecafCLieEnvironment: any;

package/lib/types/environment.d.mts

@@ -0,0 +1,7 @@
+import { LoggingConfig } from "@decaf-ts/logging";
+export type DecafCliEnvironment = LoggingConfig & {
+    banner: boolean;
+    cliModuleRoot: string;
+};
+export declare const DefaultCliEnvironment: DecafCliEnvironment;
+export declare const DecafCLieEnvironment: any;

package/lib/types/index.d.cts

@@ -0,0 +1,16 @@
+export * from "./CliWrapper.cjs";
+export * from "./environment.cjs";
+/**
+ * @description Decaf-ts' CLI module
+ * @summary This file will crawl the current working directory for files called {@link CLI_FILE_NAME}
+ * within the @decaf-ts namespace and load them as subcommands. It serves as the main entry point
+ * for the CLI functionality, exporting the CliWrapper class and VERSION constant.
+ *
+ * @example
+ * run module command     - $ npx decaf <module name> <module command> ...<module command options>
+ * get module help        - $ npx decaf help <module name>;
+ * list imported modules  - $ npx decaf list;
+ * get cli help           - $ npx decaf help;
+ *
+ * @module CLI
+ */

package/lib/types/index.d.mts

@@ -0,0 +1,16 @@
+export * from "./CliWrapper.js";
+export * from "./environment.js";
+/**
+ * @description Decaf-ts' CLI module
+ * @summary This file will crawl the current working directory for files called {@link CLI_FILE_NAME}
+ * within the @decaf-ts namespace and load them as subcommands. It serves as the main entry point
+ * for the CLI functionality, exporting the CliWrapper class and VERSION constant.
+ *
+ * @example
+ * run module command     - $ npx decaf <module name> <module command> ...<module command options>
+ * get module help        - $ npx decaf help <module name>;
+ * list imported modules  - $ npx decaf list;
+ * get cli help           - $ npx decaf help;
+ *
+ * @module CLI
+ */

package/lib/types/logging.d.cts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { Logger } from "@decaf-ts/logging";
+export declare function getCmdLogger(cmd: Command): Logger;

package/lib/types/logging.d.mts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { Logger } from "@decaf-ts/logging";
+export declare function getCmdLogger(cmd: Command): Logger;

package/lib/types/release-module/cli-module.d.cts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function releaseModule(): Command;

package/lib/types/release-module/cli-module.d.mts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function releaseModule(): Command;

package/lib/types/slogans.d.cts

@@ -0,0 +1,40 @@
+import { Logger } from "@decaf-ts/logging";
+/**
+ * @description Reads and parses slogans from workdocs/assets/slogans.json.
+ * @summary Attempts to read a slogans.json file from the workdocs/assets directory at the given base path and returns its parsed contents as an array.
+ *
+ * @param {string} basePath - The base directory path where workdocs/assets/slogans.json should exist.
+ * @return {any[] | undefined} The parsed array from slogans.json, or undefined if the file doesn't exist.
+ *
+ * @function readSlogans
+ *
+ * @memberOf module:utils
+ */
+export declare function readSlogans(log: Logger, basePath: string): {
+    Slogan: string;
+}[] | undefined;
+/**
+ * @description Collects slogans from a base path and all @decaf scoped packages.
+ * @summary Recursively collects slogans.json files from the given base path and all subdirectories under node_modules/@decaf/*. Results are stored in an object keyed by the package name (from package.json).
+ *
+ * @param {string} basePath - The base directory path to start collecting from.
+ * @return {Record<string, any[]>} An object mapping package names to their slogans arrays.
+ *
+ * @function collectSlogans
+ *
+ * @memberOf module:utils
+ */
+export declare function collectSlogans(log: Logger, basePath: string): Record<string, any[]>;
+/**
+ * @description Flattens collected slogans with weighted selection for a priority package.
+ * @summary Given a collection of slogans and a priority package name, returns a flat array where slogans from the priority package have a 30-40% chance of appearing at any given position.
+ *
+ * @param {Record<string, any[]>} slogansMap - Object mapping package names to slogan arrays.
+ * @param {string} priorityPackage - The package name whose slogans should be prioritized.
+ * @return {any[]} A flat array of all slogans with weighted distribution.
+ *
+ * @function flattenSlogansWithPriority
+ *
+ * @memberOf module:utils
+ */
+export declare function flattenSlogansWithPriority(log: Logger, slogansMap: Record<string, any[]>, priorityPackage: string): any[];

package/lib/types/slogans.d.mts

@@ -0,0 +1,40 @@
+import { Logger } from "@decaf-ts/logging";
+/**
+ * @description Reads and parses slogans from workdocs/assets/slogans.json.
+ * @summary Attempts to read a slogans.json file from the workdocs/assets directory at the given base path and returns its parsed contents as an array.
+ *
+ * @param {string} basePath - The base directory path where workdocs/assets/slogans.json should exist.
+ * @return {any[] | undefined} The parsed array from slogans.json, or undefined if the file doesn't exist.
+ *
+ * @function readSlogans
+ *
+ * @memberOf module:utils
+ */
+export declare function readSlogans(log: Logger, basePath: string): {
+    Slogan: string;
+}[] | undefined;
+/**
+ * @description Collects slogans from a base path and all @decaf scoped packages.
+ * @summary Recursively collects slogans.json files from the given base path and all subdirectories under node_modules/@decaf/*. Results are stored in an object keyed by the package name (from package.json).
+ *
+ * @param {string} basePath - The base directory path to start collecting from.
+ * @return {Record<string, any[]>} An object mapping package names to their slogans arrays.
+ *
+ * @function collectSlogans
+ *
+ * @memberOf module:utils
+ */
+export declare function collectSlogans(log: Logger, basePath: string): Record<string, any[]>;
+/**
+ * @description Flattens collected slogans with weighted selection for a priority package.
+ * @summary Given a collection of slogans and a priority package name, returns a flat array where slogans from the priority package have a 30-40% chance of appearing at any given position.
+ *
+ * @param {Record<string, any[]>} slogansMap - Object mapping package names to slogan arrays.
+ * @param {string} priorityPackage - The package name whose slogans should be prioritized.
+ * @return {any[]} A flat array of all slogans with weighted distribution.
+ *
+ * @function flattenSlogansWithPriority
+ *
+ * @memberOf module:utils
+ */
+export declare function flattenSlogansWithPriority(log: Logger, slogansMap: Record<string, any[]>, priorityPackage: string): any[];

package/lib/types/types.d.cts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+/**
+ * @description Function type for Decaf CLI modules
+ * @summary Defines the signature for CLI module functions that each Decaf module must export under the CLI_FILE_NAME file
+ * The function should return a Command object or a Promise that resolves to a Command object
+ *
+ * @typedef {Function} CliModule
+ * @return {Command|Promise<Command>} A Command object or Promise that resolves to a Command object
+ * @memberOf module:CLI
+ */
+export type CliModule = () => Command | Promise<Command>;

package/lib/types/types.d.mts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+/**
+ * @description Function type for Decaf CLI modules
+ * @summary Defines the signature for CLI module functions that each Decaf module must export under the CLI_FILE_NAME file
+ * The function should return a Command object or a Promise that resolves to a Command object
+ *
+ * @typedef {Function} CliModule
+ * @return {Command|Promise<Command>} A Command object or Promise that resolves to a Command object
+ * @memberOf module:CLI
+ */
+export type CliModule = () => Command | Promise<Command>;

package/lib/types/utils/command-forwarder.d.cts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+export type OptionSpec = {
+    name: string;
+    flag: string;
+    type: "boolean" | "string";
+    allowFalse?: boolean;
+};
+export declare function parseOptionalBoolean(value?: string): boolean;
+export declare function buildValueMap(command: Command, specs: OptionSpec[]): Record<string, unknown>;
+export declare function runUtilsCommand(utilsCommand: object, values: Record<string, unknown>, invoker: Command): Promise<void>;

package/lib/types/utils/command-forwarder.d.mts

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+export type OptionSpec = {
+    name: string;
+    flag: string;
+    type: "boolean" | "string";
+    allowFalse?: boolean;
+};
+export declare function parseOptionalBoolean(value?: string): boolean;
+export declare function buildValueMap(command: Command, specs: OptionSpec[]): Record<string, unknown>;
+export declare function runUtilsCommand(utilsCommand: object, values: Record<string, unknown>, invoker: Command): Promise<void>;

package/lib/types/utils-module/cli-module.d.cts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function utils(): Command;

package/lib/types/utils-module/cli-module.d.mts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export default function utils(): Command;