@decaf-ts/utils 1.1.0 → 1.2.0

package/lib/types/cli/commands/tag-release.d.mts

@@ -0,0 +1,105 @@
+import { Command } from "../command.js";
+import { DefaultCommandValues } from "../index.js";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare const options: {
+    ci: {
+        type: string;
+        default: boolean;
+    };
+    message: {
+        type: string;
+        short: string;
+    };
+    tag: {
+        type: string;
+        short: string;
+        default: undefined;
+    };
+};
+/**
+ * @class ReleaseScript
+ * @extends {Command}
+ * @cavegory scripts
+ * @description A command-line script for managing releases and version updates.
+ * @summary This script automates the process of creating and pushing new releases. It handles version updates,
+ * commit messages, and optionally publishes to NPM. The script supports semantic versioning and can work in both CI and non-CI environments.
+ *
+ * @param {Object} options - Configuration options for the script
+ * @param {boolean} options.ci - Whether the script is running in a CI environment (default: true)
+ * @param {string} options.message - The release message (short: 'm')
+ * @param {string} options.tag - The version tag to use (short: 't', default: undefined)
+ */
+export declare class ReleaseScript extends Command<typeof options, void> {
+    constructor();
+    /**
+     * @description Prepares the version for the release.
+     * @summary This method validates the provided tag or prompts the user for a new one if not provided or invalid.
+     * It also displays the latest git tags for reference.
+     * @param {string} tag - The version tag to prepare
+     * @returns {Promise<string>} The prepared version tag
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant R as ReleaseScript
+     *   participant T as TestVersion
+     *   participant U as UserInput
+     *   participant G as Git
+     *   R->>T: testVersion(tag)
+     *   alt tag is valid
+     *     T-->>R: return tag
+     *   else tag is invalid or not provided
+     *     R->>G: List latest git tags
+     *     R->>U: Prompt for new tag
+     *     U-->>R: return new tag
+     *   end
+     */
+    prepareVersion(tag?: string): Promise<string>;
+    /**
+     * @description Tests if the provided version is valid.
+     * @summary This method checks if the version is a valid semantic version or a predefined update type (PATCH, MINOR, MAJOR).
+     * @param {string} version - The version to test
+     * @returns {string | undefined} The validated version or undefined if invalid
+     */
+    testVersion(version: string): string | undefined;
+    /**
+     * @description Prepares the release message.
+     * @summary This method either returns the provided message or prompts the user for a new one if not provided.
+     * @param {string} [message] - The release message
+     * @returns {Promise<string>} The prepared release message
+     */
+    prepareMessage(message?: string): Promise<string>;
+    /**
+     * @description Runs the release script.
+     * @summary This method orchestrates the entire release process, including version preparation, message creation,
+     * git operations, and npm publishing (if not in CI environment).
+     * @param {ParseArgsResult} args - The parsed command-line arguments
+     * @returns {Promise<void>}
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant R as ReleaseScript
+     *   participant V as PrepareVersion
+     *   participant M as PrepareMessage
+     *   participant N as NPM
+     *   participant G as Git
+     *   participant U as UserInput
+     *   R->>V: prepareVersion(tag)
+     *   R->>M: prepareMessage(message)
+     *   R->>N: Run prepare-release script
+     *   R->>G: Check git status
+     *   alt changes exist
+     *     R->>U: Ask for confirmation
+     *     U-->>R: Confirm
+     *     R->>G: Add and commit changes
+     *   end
+     *   R->>N: Update npm version
+     *   R->>G: Push changes and tags
+     *   alt not CI environment
+     *     R->>N: Publish to npm
+     *   end
+     */
+    run(args: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof typeof options]: unknown;
+    }): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,75 @@
+/**
+ * @description Default command options for CLI commands.
+ * @summary Defines the structure and default values for common command-line options used across various CLI commands.
+ * @const DefaultCommandOptions
+ * @typedef {Object} DefaultCommandOptions
+ * @property {Object} verbose - Verbosity level option.
+ * @property {string} verbose.type - The type of the verbose option (number).
+ * @property {string} verbose.short - The short flag for the verbose option (V).
+ * @property {number} verbose.default - The default value for verbosity (0).
+ * @property {Object} version - Version display option.
+ * @property {string} version.type - The type of the version option (boolean).
+ * @property {string} version.short - The short flag for the version option (v).
+ * @property {undefined} version.default - The default value for version display (undefined).
+ * @property {Object} help - Help display option.
+ * @property {string} help.type - The type of the help option (boolean).
+ * @property {string} help.short - The short flag for the help option (h).
+ * @property {boolean} help.default - The default value for help display (false).
+ * @property {Object} logLevel - Log level option.
+ * @property {string} logLevel.type - The type of the logLevel option (string).
+ * @property {string} logLevel.default - The default value for log level ("info").
+ * @property {Object} logStyle - Log styling option.
+ * @property {string} logStyle.type - The type of the logStyle option (boolean).
+ * @property {boolean} logStyle.default - The default value for log styling (true).
+ * @property {Object} timestamp - Timestamp display option.
+ * @property {string} timestamp.type - The type of the timestamp option (boolean).
+ * @property {boolean} timestamp.default - The default value for timestamp display (true).
+ * @property {Object} banner - Banner display option.
+ * @property {string} banner.type - The type of the banner option (boolean).
+ * @property {boolean} banner.default - The default value for banner display (false).
+ * @memberOf module:utils
+ */
+export declare const DefaultCommandOptions: {
+    verbose: {
+        type: string;
+        short: string;
+        default: undefined;
+    };
+    version: {
+        type: string;
+        short: string;
+        default: undefined;
+    };
+    help: {
+        type: string;
+        short: string;
+        default: boolean;
+    };
+    logLevel: {
+        type: string;
+        default: string;
+    };
+    logStyle: {
+        type: string;
+        default: boolean;
+    };
+    timestamp: {
+        type: string;
+        default: boolean;
+    };
+    banner: {
+        type: string;
+        default: boolean;
+    };
+};
+/**
+ * @description Default command values derived from DefaultCommandOptions.
+ * @summary Creates an object with the default values of all options defined in DefaultCommandOptions.
+ * @const DefaultCommandValues
+ * @typedef {Object} DefaultCommandValues
+ * @property {unknown} [key: string] - The default value for each option in DefaultCommandOptions.
+ * @memberOf module:utils
+ */
+export declare const DefaultCommandValues: {
+    [k in keyof typeof DefaultCommandOptions]: unknown;
+};

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

@@ -0,0 +1,75 @@
+/**
+ * @description Default command options for CLI commands.
+ * @summary Defines the structure and default values for common command-line options used across various CLI commands.
+ * @const DefaultCommandOptions
+ * @typedef {Object} DefaultCommandOptions
+ * @property {Object} verbose - Verbosity level option.
+ * @property {string} verbose.type - The type of the verbose option (number).
+ * @property {string} verbose.short - The short flag for the verbose option (V).
+ * @property {number} verbose.default - The default value for verbosity (0).
+ * @property {Object} version - Version display option.
+ * @property {string} version.type - The type of the version option (boolean).
+ * @property {string} version.short - The short flag for the version option (v).
+ * @property {undefined} version.default - The default value for version display (undefined).
+ * @property {Object} help - Help display option.
+ * @property {string} help.type - The type of the help option (boolean).
+ * @property {string} help.short - The short flag for the help option (h).
+ * @property {boolean} help.default - The default value for help display (false).
+ * @property {Object} logLevel - Log level option.
+ * @property {string} logLevel.type - The type of the logLevel option (string).
+ * @property {string} logLevel.default - The default value for log level ("info").
+ * @property {Object} logStyle - Log styling option.
+ * @property {string} logStyle.type - The type of the logStyle option (boolean).
+ * @property {boolean} logStyle.default - The default value for log styling (true).
+ * @property {Object} timestamp - Timestamp display option.
+ * @property {string} timestamp.type - The type of the timestamp option (boolean).
+ * @property {boolean} timestamp.default - The default value for timestamp display (true).
+ * @property {Object} banner - Banner display option.
+ * @property {string} banner.type - The type of the banner option (boolean).
+ * @property {boolean} banner.default - The default value for banner display (false).
+ * @memberOf module:utils
+ */
+export declare const DefaultCommandOptions: {
+    verbose: {
+        type: string;
+        short: string;
+        default: undefined;
+    };
+    version: {
+        type: string;
+        short: string;
+        default: undefined;
+    };
+    help: {
+        type: string;
+        short: string;
+        default: boolean;
+    };
+    logLevel: {
+        type: string;
+        default: string;
+    };
+    logStyle: {
+        type: string;
+        default: boolean;
+    };
+    timestamp: {
+        type: string;
+        default: boolean;
+    };
+    banner: {
+        type: string;
+        default: boolean;
+    };
+};
+/**
+ * @description Default command values derived from DefaultCommandOptions.
+ * @summary Creates an object with the default values of all options defined in DefaultCommandOptions.
+ * @const DefaultCommandValues
+ * @typedef {Object} DefaultCommandValues
+ * @property {unknown} [key: string] - The default value for each option in DefaultCommandOptions.
+ * @memberOf module:utils
+ */
+export declare const DefaultCommandValues: {
+    [k in keyof typeof DefaultCommandOptions]: unknown;
+};

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

@@ -0,0 +1,4 @@
+export * from "./command.cjs";
+export * from "./commands.cjs";
+export * from "./constants.cjs";
+export * from "./types.cjs";

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

@@ -0,0 +1,4 @@
+export * from "./command.js";
+export * from "./commands.js";
+export * from "./constants.js";
+export * from "./types.js";

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

@@ -0,0 +1,30 @@
+import { ParseArgsOptionConfig } from "../input/types.cjs";
+import { LoggingConfig } from "@decaf-ts/logging";
+/**
+ * @description Interface for input options.
+ * @summary Defines the structure of input options for CLI commands.
+ * @interface InputOptions
+ * @property {number} [verbose] - The verbosity level.
+ * @property {boolean} [version] - Flag to show version information.
+ * @property {boolean} [banner] - Flag to show banner.
+ * @property {boolean} [help] - Flag to show help information.
+ * @memberOf module:utils
+ */
+export type InputOptions = {
+    verbose?: number;
+    version?: boolean;
+    banner?: boolean;
+    help?: boolean;
+};
+/**
+ * @description Type definition for command options.
+ * @summary Combines input options, input option configurations, and logging configurations into a single type.
+ * @template I - The type of additional input options specific to the command.
+ * @typedef {Object} CommandOptions
+ * @memberOf module:utils
+ */
+export type CommandOptions<I> = I & Partial<{
+    [k in keyof InputOptions]: ParseArgsOptionConfig;
+}> & Partial<{
+    [k in keyof LoggingConfig]: ParseArgsOptionConfig;
+}>;

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

@@ -0,0 +1,30 @@
+import { ParseArgsOptionConfig } from "../input/types.js";
+import { LoggingConfig } from "@decaf-ts/logging";
+/**
+ * @description Interface for input options.
+ * @summary Defines the structure of input options for CLI commands.
+ * @interface InputOptions
+ * @property {number} [verbose] - The verbosity level.
+ * @property {boolean} [version] - Flag to show version information.
+ * @property {boolean} [banner] - Flag to show banner.
+ * @property {boolean} [help] - Flag to show help information.
+ * @memberOf module:utils
+ */
+export type InputOptions = {
+    verbose?: number;
+    version?: boolean;
+    banner?: boolean;
+    help?: boolean;
+};
+/**
+ * @description Type definition for command options.
+ * @summary Combines input options, input option configurations, and logging configurations into a single type.
+ * @template I - The type of additional input options specific to the command.
+ * @typedef {Object} CommandOptions
+ * @memberOf module:utils
+ */
+export type CommandOptions<I> = I & Partial<{
+    [k in keyof InputOptions]: ParseArgsOptionConfig;
+}> & Partial<{
+    [k in keyof LoggingConfig]: ParseArgsOptionConfig;
+}>;

package/lib/types/index.d.cts

@@ -0,0 +1,38 @@
+export * from "./cli.cjs";
+export * from "./input.cjs";
+export * from "./output.cjs";
+export * from "./utils.cjs";
+export * from "./writers.cjs";
+export * from "./release-chain.cjs";
+/**
+ * @module utils
+ * @description Utilities and building blocks for Decaf-TS CLI and scripting.
+ * @summary Aggregates CLI command infrastructure, input helpers, output writers, filesystem/network utilities,
+ * and shared types. Consumers typically use {@link Command}, {@link UserInput}, {@link StandardOutputWriter},
+ * {@link printBanner}, and utilities from {@link module:utils|utils}.
+ *
+ * This entrypoint re-exports subpackages:
+ * - CLI framework under `./cli` (command base, options, built-in commands)
+ * - Input helpers under `./input` (prompting and arg parsing)
+ * - Output helpers under `./output` (banner and styling)
+ * - General utilities under `./utils` (fs, http, exec, types)
+ * - Writers under `./writers` (stdout/stderr processors)
+ *
+ * Note: Individual exports are documented in their source files.
+ */
+/**
+ * @description Represents the current version of the module.
+ * @summary Stores the version for the @decaf-ts/utils package. The build replaces
+ * the placeholder with the actual version number at publish time.
+ * @const VERSION
+ * @memberOf module:utils
+ */
+export declare const VERSION = "1.1.0";
+/**
+ * @description Represents the current version of the module.
+ * @summary Stores the version for the @decaf-ts/utils package. The build replaces
+ * the placeholder with the actual version number at publish time.
+ * @const VERSION
+ * @memberOf module:utils
+ */
+export declare const PACKAGE_NAME = "@decaf-ts/utils";

package/lib/types/index.d.mts

@@ -0,0 +1,38 @@
+export * from "./cli.js";
+export * from "./input.js";
+export * from "./output.js";
+export * from "./utils.js";
+export * from "./writers.js";
+export * from "./release-chain.js";
+/**
+ * @module utils
+ * @description Utilities and building blocks for Decaf-TS CLI and scripting.
+ * @summary Aggregates CLI command infrastructure, input helpers, output writers, filesystem/network utilities,
+ * and shared types. Consumers typically use {@link Command}, {@link UserInput}, {@link StandardOutputWriter},
+ * {@link printBanner}, and utilities from {@link module:utils|utils}.
+ *
+ * This entrypoint re-exports subpackages:
+ * - CLI framework under `./cli` (command base, options, built-in commands)
+ * - Input helpers under `./input` (prompting and arg parsing)
+ * - Output helpers under `./output` (banner and styling)
+ * - General utilities under `./utils` (fs, http, exec, types)
+ * - Writers under `./writers` (stdout/stderr processors)
+ *
+ * Note: Individual exports are documented in their source files.
+ */
+/**
+ * @description Represents the current version of the module.
+ * @summary Stores the version for the @decaf-ts/utils package. The build replaces
+ * the placeholder with the actual version number at publish time.
+ * @const VERSION
+ * @memberOf module:utils
+ */
+export declare const VERSION = "1.1.0";
+/**
+ * @description Represents the current version of the module.
+ * @summary Stores the version for the @decaf-ts/utils package. The build replaces
+ * the placeholder with the actual version number at publish time.
+ * @const VERSION
+ * @memberOf module:utils
+ */
+export declare const PACKAGE_NAME = "@decaf-ts/utils";

package/lib/types/index.d.ts

@@ -27,7 +27,7 @@ export * from "./release-chain";
  * @const VERSION
  * @memberOf module:utils
  */
-export declare const VERSION = "1.0.10";
+export declare const VERSION = "1.1.0";
 /**
  * @description Represents the current version of the module.
  * @summary Stores the version for the @decaf-ts/utils package. The build replaces

package/lib/types/input/index.d.cts

@@ -0,0 +1,2 @@
+export * from './input.cjs';
+export * from './types.cjs';

package/lib/types/input/index.d.mts

@@ -0,0 +1,2 @@
+export * from './input.js';
+export * from './types.js';