@twin.org/cli-core 0.0.1-next.1

package/dist/types/cliBase.d.ts

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import type { ICliOptions } from "./models/ICliOptions";
+/**
+ * The main entry point for the CLI.
+ */
+export declare abstract class CLIBase {
+    /**
+     * Execute the command line processing.
+     * @param options The options for the CLI.
+     * @param localesDirectory The path to load the locales from.
+     * @param argv The process arguments.
+     * @returns The exit code.
+     */
+    execute(options: ICliOptions, localesDirectory: string, argv: string[]): Promise<number>;
+    /**
+     * Configure any options or actions at the root program level.
+     * @param program The root program command.
+     */
+    protected configureRoot(program: Command): void;
+    /**
+     * Get the commands for the CLI, override in derived class to supply your own.
+     * @param program The main program that the commands will be added to.
+     * @returns The commands for the CLI.
+     */
+    protected getCommands(program: Command): Command[];
+}

package/dist/types/cliDisplay.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Display utilities for the CLI.
+ */
+export declare class CLIDisplay {
+    /**
+     * The default output method for writing standard messages.
+     * @param buffer The message to output.
+     */
+    static write: (buffer: string | Uint8Array) => void;
+    /**
+     * The default output method for writing error messages.
+     * @param buffer The message to output.
+     */
+    static writeError: (buffer: string | Uint8Array) => void;
+    /**
+     * The default output method for clearing the current line.
+     */
+    static clearLine: () => void;
+    /**
+     * Display the header for the CLI.
+     * @param title The title of the CLI.
+     * @param version The version of the CLI.
+     * @param icon The icon for the CLI.
+     */
+    static header(title: string, version: string, icon: string): void;
+    /**
+     * Display an error message.
+     * @param error The error to display.
+     * @param lineBreaks Whether to add a line break after the error.
+     */
+    static error(error: unknown, lineBreaks?: boolean): void;
+    /**
+     * Display a section.
+     * @param label The label for the section.
+     */
+    static section(label: string): void;
+    /**
+     * Display a value with a label.
+     * @param label The label for the value.
+     * @param value The value to display.
+     * @param indentLevel The level of indentation.
+     */
+    static value(label: string, value: unknown, indentLevel?: number): void;
+    /**
+     * Display a task with a label.
+     * @param label The label for the value.
+     * @param task The task to display.
+     */
+    static task(label: string, task?: string): void;
+    /**
+     * Display a break.
+     */
+    static break(): void;
+    /**
+     * Display formatted and colorized JSON.
+     * @param obj The object to display.
+     */
+    static json(obj: unknown): void;
+    /**
+     * Display the processing is done.
+     */
+    static done(): void;
+    /**
+     * Start the spinner.
+     * @param i18nMessage The message to display with the spinner.
+     * @param spinnerCharacters The characters to use in the spinner.
+     * @param interval The interval for the spinner.
+     */
+    static spinnerStart(i18nMessage?: string, spinnerCharacters?: string[], interval?: number): void;
+    /**
+     * Stop the spinner.
+     */
+    static spinnerStop(): void;
+}

package/dist/types/cliOptions.d.ts

@@ -0,0 +1,23 @@
+import type { Command } from "commander";
+/**
+ * Utilities for getting standard options.
+ */
+export declare class CLIOptions {
+    /**
+     * Get the options for output.
+     * @param command The command to add the options to.
+     * @param opts The options of what to include.
+     * @param opts.noConsole Do not output to the console.
+     * @param opts.json Output to a JSON file.
+     * @param opts.env Output to an environment file.
+     * @param opts.mergeJson Merge existing JSON file.
+     * @param opts.mergeEnv Merge existing environment file.
+     */
+    static output(command: Command, opts: {
+        noConsole: boolean;
+        json: boolean;
+        env: boolean;
+        mergeJson: boolean;
+        mergeEnv: boolean;
+    }): void;
+}

package/dist/types/cliParam.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Parameter utilities for the CLI.
+ */
+export declare class CLIParam {
+    /**
+     * Check the option to see if it exists.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static env(optionName: string, optionValue: string | undefined, allowEnvVar: boolean): string | undefined;
+    /**
+     * Check the option to see if it exists.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static stringValue(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean): string;
+    /**
+     * Check the option to see if it a url.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static url(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean): string;
+    /**
+     * Check the option to see if it exists and is a number.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @param minValue The minimum value.
+     * @param maxValue The maximum value.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static number(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean, minValue?: number, maxValue?: number): number;
+    /**
+     * Check the option to see if it exists and is an integer.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @param minValue The minimum value.
+     * @param maxValue The maximum value.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static integer(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean, minValue?: number, maxValue?: number): number;
+    /**
+     * Check the option to see if it exists and is a big number.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @param minValue The minimum value.
+     * @param maxValue The maximum value.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static bigint(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean, minValue?: bigint, maxValue?: bigint): bigint;
+    /**
+     * Check the option to see if it exists and is a boolean.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static boolean(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean): boolean;
+    /**
+     * Check the option to see if it exists and is hex.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static hex(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean): Uint8Array;
+    /**
+     * Check the option to see if it exists and is base64.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static base64(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean): Uint8Array;
+    /**
+     * Check the option to see if it exists and is hex or base64.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static hexBase64(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean): Uint8Array;
+    /**
+     * Check the option to see if it exists and is bech32.
+     * @param optionName The name of the option.
+     * @param optionValue The option value.
+     * @param allowEnvVar Allow the option to be read from an env var.
+     * @returns The final option value.
+     * @throws An error if the option is invalid.
+     */
+    static bech32(optionName: string, optionValue: string | undefined, allowEnvVar?: boolean): string;
+}

package/dist/types/cliUtils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Utilities function for helping in the CLI.
+ */
+export declare class CLIUtils {
+    /**
+     * Does the specified file exist.
+     * @param filename The filename to check for existence.
+     * @returns True if the file exists.
+     */
+    static fileExists(filename: string): Promise<boolean>;
+    /**
+     * Does the specified file exist, synchronously.
+     * @param filename The filename to check for existence.
+     * @returns True if the file exists.
+     */
+    static fileExistsSync(filename: string): boolean;
+    /**
+     * Check if the dir exists.
+     * @param dir The directory to check.
+     * @returns True if the dir exists.
+     */
+    static dirExists(dir: string): Promise<boolean>;
+    /**
+     * Check if the dir exists, synchronously.
+     * @param dir The directory to check.
+     * @returns True if the dir exists.
+     */
+    static dirExistsSync(dir: string): boolean;
+    /**
+     * Read a JSON file and parse it.
+     * @param filename The filename to read.
+     * @returns The parsed JSON.
+     */
+    static readJsonFile<T = unknown>(filename: string): Promise<T | undefined>;
+    /**
+     * Read a JSON file and parse it, synchronously.
+     * @param filename The filename to read.
+     * @returns The parsed JSON.
+     */
+    static readJsonFileSync<T = unknown>(filename: string): T | undefined;
+    /**
+     * Read a file as lines.
+     * @param filename The filename to read.
+     * @returns The lines.
+     */
+    static readLinesFile(filename: string): Promise<string[] | undefined>;
+    /**
+     * Read a file as lines, synchronously.
+     * @param filename The filename to read.
+     * @returns The lines.
+     */
+    static readLinesFileSync(filename: string): string[] | undefined;
+    /**
+     * Find the NPM root based on a package.json path.
+     * @param rootFolder The path to the package.json.
+     * @returns The root path.
+     */
+    static findNpmRoot(rootFolder: string): Promise<string>;
+    /**
+     * Run a shell app.
+     * @param app The app to run in the shell.
+     * @param args The args for the app.
+     * @param cwd The working directory to execute the command in.
+     * @returns Promise to wait for command execution to complete.
+     */
+    static runShellCmd(app: string, args: string[], cwd: string): Promise<void>;
+    /**
+     * Write a JSON file.
+     * @param jsonFilename The filename to write.
+     * @param data The data to write.
+     * @param append Append to the file.
+     */
+    static writeJsonFile<T = unknown>(jsonFilename: string | undefined, data: T, append: boolean): Promise<void>;
+    /**
+     * Write an env file.
+     * @param envFilename The filename to write.
+     * @param data The data to write.
+     * @param append Append to the file.
+     */
+    static writeEnvFile(envFilename: string | undefined, data: string[], append: boolean): Promise<void>;
+}

package/dist/types/commands/global.d.ts

@@ -0,0 +1,13 @@
+import type { Command } from "commander";
+/**
+ * Initialize the global options.
+ * @param localesDirectory The path to load the locales from.
+ */
+export declare function initGlobalOptions(localesDirectory: string): void;
+/**
+ * Add the global options.
+ * @param program The program to add the options to.
+ * @param supportsLang Whether the CLI supports different languages.
+ * @param supportsEnvFiles Whether the CLI supports loading env files
+ */
+export declare function addGlobalOptions(program: Command, supportsLang: boolean, supportsEnvFiles: boolean): void;

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./cliBase";
+export * from "./cliDisplay";
+export * from "./cliOptions";
+export * from "./cliParam";
+export * from "./cliUtils";
+export * from "./commands/global";
+export * from "./models/ICliOptions";
+export * from "./models/ICliOutputOptionsConsole";
+export * from "./models/ICliOutputOptionsEnv";
+export * from "./models/ICliOutputOptionsJson";
+export * from "./models/cliOutputOptions";

package/dist/types/models/ICliOptions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Options for the CLI.
+ */
+export interface ICliOptions {
+    /**
+     * The title of the CLI.
+     */
+    title: string;
+    /**
+     * The name of the app used to execute it.
+     */
+    appName: string;
+    /**
+     * The version of the app.
+     */
+    version: string;
+    /**
+     * The icon for the CLI as an emoji character.
+     */
+    icon: string;
+    /**
+     * Supports different languages.
+     */
+    supportsLang?: boolean;
+    /**
+     * Supports the loading of env files.
+     */
+    supportsEnvFiles?: boolean;
+}

package/dist/types/models/ICliOutputOptionsConsole.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Options for the CLI Output for console.
+ */
+export interface ICliOutputOptionsConsole {
+    /**
+     * Flag to display on the console.
+     */
+    console: boolean;
+}

package/dist/types/models/ICliOutputOptionsEnv.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for the CLI Output for env.
+ */
+export interface ICliOutputOptionsEnv {
+    /**
+     * Output the data to an environment file.
+     */
+    env?: string;
+    /**
+     * Merge the data to an environment file.
+     */
+    mergeEnv: boolean;
+}

package/dist/types/models/ICliOutputOptionsJson.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Options for the CLI Output for JSON.
+ */
+export interface ICliOutputOptionsJson {
+    /**
+     * Output the data to an JSON file.
+     */
+    json?: string;
+    /**
+     * Merge the data to a JSON file.
+     */
+    mergeJson: boolean;
+}

package/dist/types/models/cliOutputOptions.d.ts

@@ -0,0 +1,7 @@
+import type { ICliOutputOptionsConsole } from "./ICliOutputOptionsConsole";
+import type { ICliOutputOptionsEnv } from "./ICliOutputOptionsEnv";
+import type { ICliOutputOptionsJson } from "./ICliOutputOptionsJson";
+/**
+ * Options for the CLI Output.
+ */
+export type CliOutputOptions = ICliOutputOptionsConsole & ICliOutputOptionsEnv & ICliOutputOptionsJson;

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/cli-core - Changelog
+
+## v0.0.1
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/cli-core - Examples

package/docs/reference/classes/CLIBase.md

@@ -0,0 +1,83 @@
+[**@twin.org/cli-core**](../overview.md) • **Docs**
+
+***
+
+# Class: `abstract` CLIBase
+
+The main entry point for the CLI.
+
+## Constructors
+
+### new CLIBase()
+
+> **new CLIBase**(): [`CLIBase`](CLIBase.md)
+
+#### Returns
+
+[`CLIBase`](CLIBase.md)
+
+## Methods
+
+### execute()
+
+> **execute**(`options`, `localesDirectory`, `argv`): `Promise`\<`number`\>
+
+Execute the command line processing.
+
+#### Parameters
+
+• **options**: [`ICliOptions`](../interfaces/ICliOptions.md)
+
+The options for the CLI.
+
+• **localesDirectory**: `string`
+
+The path to load the locales from.
+
+• **argv**: `string`[]
+
+The process arguments.
+
+#### Returns
+
+`Promise`\<`number`\>
+
+The exit code.
+
+***
+
+### configureRoot()
+
+> `protected` **configureRoot**(`program`): `void`
+
+Configure any options or actions at the root program level.
+
+#### Parameters
+
+• **program**: `Command`
+
+The root program command.
+
+#### Returns
+
+`void`
+
+***
+
+### getCommands()
+
+> `protected` **getCommands**(`program`): `Command`[]
+
+Get the commands for the CLI, override in derived class to supply your own.
+
+#### Parameters
+
+• **program**: `Command`
+
+The main program that the commands will be added to.
+
+#### Returns
+
+`Command`[]
+
+The commands for the CLI.