hexbus 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,312 +1,1516 @@
-import color from "picocolors";
-
 //#region src/types.d.ts
-type LogLevel = 'error' | 'warn' | 'info' | 'debug';
-type FlagType = 'boolean' | 'string' | 'special';
+/**
+ * Supported logger verbosity levels.
+ *
+ * @remarks
+ * Levels are ordered from least verbose (`error`) to most verbose (`debug`).
+ * `createCliLogger` uses this ordering to decide whether a message should be
+ * emitted.
+ */
+type LogLevel = "error" | "warn" | "info" | "debug";
+/**
+ * Describes how a command-line flag should be parsed.
+ *
+ * @remarks
+ * `special` flags behave like booleans during parsing but usually trigger
+ * control flow outside command execution, such as showing help or version
+ * output.
+ */
+type FlagType = "boolean" | "string" | "special";
+/**
+ * Defines a global command-line flag accepted by a Hexbus CLI.
+ */
 interface CliFlag {
+  /**
+   * Flag aliases accepted on the command line.
+   *
+   * @example ['--help', '-h']
+   */
   names: string[];
+  /**
+   * Human-readable explanation shown in generated help output.
+   */
   description: string;
+  /**
+   * Parser behavior for this flag.
+   */
   type: FlagType;
+  /**
+   * Whether the flag consumes the following argument as its value.
+   */
   expectsValue: boolean;
+  /**
+   * Initial value assigned before raw arguments are parsed.
+   */
   defaultValue?: string | boolean;
 }
+/**
+ * Normalized representation of raw CLI arguments.
+ */
 interface ParsedArgs {
+  /**
+   * Name of the matched top-level command, if the first positional argument
+   * matched a registered command.
+   */
   commandName: string | undefined;
+  /**
+   * Positional arguments remaining after the top-level command name is
+   * removed.
+   */
   commandArgs: string[];
+  /**
+   * Parsed global flags keyed by their primary long name without leading
+   * dashes.
+   *
+   * @example
+   * The `--no-telemetry` flag is stored as `no-telemetry`.
+   */
   parsedFlags: Record<string, string | boolean | undefined>;
 }
+/**
+ * Defines a command that can be rendered in help output and executed with a
+ * fully resolved CLI context.
+ *
+ * @remarks
+ * Commands are intentionally data-first so product CLIs can build menus,
+ * telemetry labels, and nested command trees from the same object. The action
+ * receives the resolved context after flags, package manager detection,
+ * framework detection, logging, and telemetry have been initialized.
+ *
+ * @typeParam TContext - CLI context shape required by this command. Extend the
+ * base context when a product CLI injects additional services or configuration.
+ *
+ * @example
+ * ```ts
+ * const command: CliCommand = {
+ *   name: 'init',
+ *   label: 'Initialize project',
+ *   hint: 'Scaffold config files',
+ *   description: 'Creates project configuration files.',
+ *   async action(context) {
+ *     context.logger.info(`Running in ${context.projectRoot}`);
+ *   },
+ * };
+ * ```
+ */
 interface CliCommand<TContext extends CliContext = CliContext> {
+  /**
+   * Stable command name accepted on the command line.
+   */
   name: string;
+  /**
+   * Short display label for menus or selection prompts.
+   */
   label: string;
+  /**
+   * Compact hint for interactive command menus.
+   */
   hint: string;
+  /**
+   * Longer explanation used in help output.
+   */
   description: string;
+  /**
+   * Command implementation.
+   *
+   * @remarks
+   * Throw `CliError` when possible so shared error handling can render
+   * catalog hints and documentation links.
+   */
   action: (context: TContext) => Promise<void>;
+  /**
+   * Optional nested command list consumed by `parseSubcommand` and custom
+   * command routers.
+   */
   subcommands?: CliCommand<TContext>[];
+  /**
+   * Hides the command from generated help and menu UIs without preventing
+   * direct execution by a custom router.
+   */
   hidden?: boolean;
 }
+/**
+ * Minimal package metadata loaded from a project's `package.json`.
+ */
 interface PackageInfo {
+  /**
+   * Package name, or `unknown` when no readable package name exists.
+   */
   name: string;
+  /**
+   * Package version, or `unknown` when no readable package version exists.
+   */
   version: string;
+  /**
+   * Additional package.json fields preserved for callers that need them.
+   */
   [key: string]: unknown;
 }
+/**
+ * Result of inspecting project dependencies for a known frontend framework.
+ *
+ * @typeParam TPackage - Product-specific package identifier selected from a
+ * `FrameworkPackageMap`.
+ */
 interface FrameworkDetectionResult<TPackage extends string = string> {
+  /**
+   * Detected framework display name, or `null` when no supported framework was
+   * found.
+   */
   framework: string | null;
+  /**
+   * Version range read from `package.json` for the detected framework.
+   */
   frameworkVersion: string | null;
+  /**
+   * Product package identifier associated with the detected framework.
+   */
   pkg: TPackage | null;
+  /**
+   * Whether any React dependency was found.
+   */
   hasReact: boolean;
+  /**
+   * React version range read from `package.json`, if present.
+   */
   reactVersion: string | null;
+  /**
+   * Tailwind CSS version range read from `package.json`, if present.
+   */
   tailwindVersion: string | null;
 }
-type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun';
+/**
+ * Package managers Hexbus can detect and render commands for.
+ */
+type PackageManager = "npm" | "yarn" | "pnpm" | "bun";
+/**
+ * Package manager command templates resolved for the current project.
+ */
 interface PackageManagerResult {
+  /**
+   * Detected package manager name.
+   */
   name: PackageManager;
+  /**
+   * Command used to install existing dependencies.
+   */
   installCommand: string;
+  /**
+   * Command prefix used to add new dependencies.
+   */
   addCommand: string;
+  /**
+   * Command prefix used to run package scripts.
+   */
   runCommand: string;
+  /**
+   * Command prefix used to execute package binaries without installing them
+   * globally.
+   */
   execCommand: string;
+  /**
+   * Optional detected package manager version.
+   */
   version?: string | null;
 }
+/**
+ * User-facing logger abstraction used by Hexbus commands.
+ *
+ * @remarks
+ * The interface mirrors the small subset of logging and prompt output that
+ * command authors need. It keeps command code independent from the concrete
+ * prompt renderer used by `createCliLogger`.
+ */
 interface CliLogger {
+  /**
+   * Emits a debug message when the active log level allows debug output.
+   */
   debug(message: string, ...args: unknown[]): void;
+  /**
+   * Emits an informational message.
+   */
   info(message: string, ...args: unknown[]): void;
+  /**
+   * Emits a warning message.
+   */
   warn(message: string, ...args: unknown[]): void;
+  /**
+   * Emits an error message.
+   */
   error(message: string, ...args: unknown[]): void;
+  /**
+   * Emits an unadorned message without log-level filtering.
+   */
   message(message: string): void;
+  /**
+   * Renders a note block with optional title.
+   */
   note(content: string, title?: string): void;
+  /**
+   * Renders a closing message for a completed interaction.
+   */
   outro(message: string): void;
+  /**
+   * Renders a successful completion message.
+   */
   success(message: string): void;
+  /**
+   * Renders a failure message and terminates the process.
+   *
+   * @throws Never returns because it exits the current process.
+   */
   failed(message: string, exitCode?: number): never;
+  /**
+   * Renders a numbered progress step.
+   */
   step(current: number, total: number, label: string): void;
 }
+/**
+ * Shared process-ending error and cancellation handlers.
+ */
 interface ErrorHandlers {
+  /**
+   * Normalizes, displays, tracks, and exits for an unknown thrown value.
+   */
   handleError(error: unknown, command: string): never;
+  /**
+   * Displays a cancellation message and exits successfully.
+   */
   handleCancel(message?: string, context?: {
     command?: string;
     stage?: string;
   }): never;
 }
+/**
+ * Configuration loading helpers attached to a CLI context.
+ */
 interface ConfigManagement {
+  /**
+   * Loads optional configuration for the current project.
+   *
+   * @typeParam TConfig - Expected user configuration shape.
+   * @returns The parsed config object, or `null` when no config is found.
+   */
   loadConfig<TConfig = unknown>(): Promise<TConfig | null>;
+  /**
+   * Loads required configuration for the current project.
+   *
+   * @typeParam TConfig - Expected user configuration shape.
+   * @throws `CliError` with `CONFIG_NOT_FOUND` when no config is found.
+   */
   requireConfig<TConfig = unknown>(): Promise<TConfig>;
+  /**
+   * Reads TypeScript-style path aliases from configuration when supported.
+   *
+   * @remarks
+   * The default Hexbus context currently returns `null`; product CLIs can
+   * override this method when they provide config-aware file resolution.
+   */
   getPathAliases(configPath?: string): Record<string, string> | null;
 }
+/**
+ * File-system helpers rooted in the detected project.
+ */
 interface FileSystemUtils {
+  /**
+   * Reads project package metadata.
+   */
   getPackageInfo(): PackageInfo;
+  /**
+   * Tests whether a file-system path exists.
+   */
   exists(path: string): Promise<boolean>;
+  /**
+   * Reads a UTF-8 text file.
+   */
   read(path: string): Promise<string>;
+  /**
+   * Writes a UTF-8 text file.
+   */
   write(path: string, content: string): Promise<void>;
+  /**
+   * Creates a directory and any missing parents.
+   */
   mkdir(path: string): Promise<void>;
 }
+/**
+ * Telemetry client used by CLI lifecycle and command code.
+ *
+ * @remarks
+ * The built-in implementation queues events in memory and flushes them only
+ * when an endpoint is configured. Commands should treat telemetry as best
+ * effort and never depend on it for core behavior.
+ */
 interface Telemetry {
+  /**
+   * Queues a named telemetry event.
+   */
   trackEvent(eventName: string, properties?: Record<string, unknown>): void;
+  /**
+   * Queues a standardized command invocation event.
+   */
   trackCommand(command: string, args?: string[], flags?: Record<string, string | number | boolean | undefined>): void;
+  /**
+   * Queues a standardized error event.
+   */
   trackError(error: Error, command?: string): void;
+  /**
+   * Sends queued events when possible and clears the local queue.
+   */
   flush(): Promise<void>;
+  /**
+   * Starts an immediate best-effort flush without requiring callers to await it.
+   *
+   * @remarks
+   * Entrypoints can call this before short-lived process exits. Implementations
+   * should not throw from this method.
+   */
+  flushBackground(): void;
+  /**
+   * Performs final telemetry cleanup before process exit.
+   */
   shutdown(): Promise<void>;
+  /**
+   * Indicates whether this telemetry instance is disabled.
+   */
   isDisabled(): boolean;
 }
+/**
+ * Fully resolved execution context passed to command actions.
+ *
+ * @remarks
+ * `createCliContext` builds this object once per invocation after parsing raw
+ * arguments, detecting the project root, selecting framework/package-manager
+ * metadata, and initializing logger, config, file-system, and telemetry
+ * services.
+ *
+ * @typeParam TPackage - Product-specific package identifier selected during
+ * framework detection.
+ */
 interface CliContext<TPackage extends string = string> {
+  /**
+   * Logger for command output.
+   */
   logger: CliLogger;
-  flags: ParsedArgs['parsedFlags'];
+  /**
+   * Parsed global flags keyed by primary flag name.
+   */
+  flags: ParsedArgs["parsedFlags"];
+  /**
+   * Matched top-level command name, if one was provided.
+   */
   commandName: string | undefined;
+  /**
+   * Positional arguments remaining after command parsing.
+   */
   commandArgs: string[];
+  /**
+   * Original working directory where context creation began.
+   */
   cwd: string;
+  /**
+   * Shared process-ending error handlers.
+   */
   error: ErrorHandlers;
+  /**
+   * Configuration loading helpers.
+   */
   config: ConfigManagement;
+  /**
+   * File-system helpers rooted at `projectRoot`.
+   */
   fs: FileSystemUtils;
+  /**
+   * Telemetry client for lifecycle and command events.
+   */
   telemetry: Telemetry;
+  /**
+   * Prompts the user to confirm an action.
+   *
+   * @remarks
+   * Returns `true` without prompting when `-y` or `--yes` was provided.
+   */
   confirm(message: string, initialValue?: boolean): Promise<boolean>;
+  /**
+   * Nearest ancestor directory containing `package.json`, or `cwd` when none
+   * was found.
+   */
   projectRoot: string;
+  /**
+   * Framework and package selection metadata for the detected project.
+   */
   framework: FrameworkDetectionResult<TPackage>;
+  /**
+   * Package manager commands for the detected project.
+   */
   packageManager: PackageManagerResult;
 }
 //#endregion
 //#region src/context.d.ts
+/**
+ * Options used to build a complete CLI execution context.
+ *
+ * @typeParam TPackage - Product-specific package identifier selected by
+ * framework detection.
+ */
 interface CreateContextOptions<TPackage extends string = string> {
+  /**
+   * Raw process arguments after the executable and script path have been
+   * removed.
+   *
+   * @example process.argv.slice(2)
+   */
   rawArgs: string[];
+  /**
+   * Directory where invocation started.
+   *
+   * @default process.cwd()
+   */
   cwd?: string;
+  /**
+   * Top-level commands used to identify `commandName` during argument parsing.
+   */
   commands: CliCommand[];
+  /**
+   * Global flags parsed before command execution.
+   *
+   * @remarks
+   * Pass this when a product CLI needs extra global flags while keeping Hexbus'
+   * parser and context bootstrap.
+   */
+  globalFlags?: CliFlag[];
+  /**
+   * Application name used for config lookup, telemetry defaults, and logger
+   * metadata.
+   *
+   * @default "cli"
+   */
   appName?: string;
+  /**
+   * Config name passed to `c12` when loading project configuration.
+   *
+   * @default appName
+   */
   configName?: string;
+  /**
+   * Telemetry configuration for the context.
+   */
   telemetry?: {
+    /**
+     * Disables telemetry regardless of command-line flags or environment
+     * variables.
+     */
     disabled?: boolean;
+    /**
+     * Emits queued telemetry payloads through the logger debug channel.
+     */
     debug?: boolean;
+    /**
+     * HTTP endpoint that receives flushed telemetry batches.
+     */
     endpoint?: string;
+    /**
+     * Environment variable prefix used to read telemetry opt-out flags.
+     *
+     * @remarks
+     * A prefix of `MY_CLI` reads `MY_CLI_TELEMETRY_DISABLED`.
+     */
     envVarPrefix?: string;
+    /**
+     * Properties merged into every telemetry event created by this context.
+     */
     defaultProperties?: Record<string, unknown>;
   };
+  /**
+   * Product package identifiers selected for framework-specific installs.
+   */
   packageMap?: {
+    /**
+     * Package used when no React framework is detected.
+     */
     core?: TPackage;
+    /**
+     * Package used for generic React-compatible projects.
+     */
     react?: TPackage;
+    /**
+     * Package used for Next.js projects.
+     */
     next?: TPackage;
   };
+  /**
+   * Allows package-manager detection to prompt when lockfile and package.json
+   * detection fail.
+   *
+   * @default false
+   */
   interactivePackageManagerDetection?: boolean;
 }
+/**
+ * Creates the resolved context passed to command actions.
+ *
+ * @remarks
+ * Context creation performs the standard CLI bootstrap sequence: parse global
+ * flags, create the logger, detect the project root, detect framework and
+ * package manager metadata, set up telemetry, and attach helpers for config
+ * loading, file-system access, confirmation prompts, and process-ending error
+ * handling.
+ *
+ * @typeParam TPackage - Product-specific package identifier returned from
+ * framework detection.
+ * @param options - Context creation options for the current invocation.
+ * @returns A fully initialized `CliContext`.
+ *
+ * @example
+ * ```ts
+ * const context = await createCliContext({
+ *   rawArgs: process.argv.slice(2),
+ *   appName: 'acme',
+ *   commands,
+ * });
+ *
+ * await commands.find((command) => command.name === context.commandName)
+ *   ?.action(context);
+ * ```
+ */
 declare function createCliContext<TPackage extends string = string>(options: CreateContextOptions<TPackage>): Promise<CliContext<TPackage>>;
+/**
+ * Creates a deterministic context for unit tests.
+ *
+ * @remarks
+ * The test context disables telemetry, uses an error-only logger, avoids real
+ * framework or package-manager detection, and provides no-op file-system
+ * helpers. Pass overrides to replace only the services a test needs.
+ *
+ * @param overrides - Partial context fields to merge into the default test
+ * context.
+ * @returns A `CliContext` suitable for command and helper tests.
+ *
+ * @example
+ * ```ts
+ * const context = createTestContext({
+ *   flags: { force: true },
+ *   commandName: 'init',
+ * });
+ * ```
+ */
 declare function createTestContext(overrides?: Partial<CliContext>): CliContext;
 //#endregion
 //#region src/detection.d.ts
+/**
+ * Product package identifiers to select after framework detection.
+ *
+ * @remarks
+ * Use this map when a product CLI installs different packages for core,
+ * React, or Next.js projects.
+ *
+ * @typeParam TPackage - Product-specific package identifier.
+ */
 interface FrameworkPackageMap<TPackage extends string = string> {
+  /**
+   * Package identifier used when no React framework is detected.
+   */
   core?: TPackage;
+  /**
+   * Package identifier used for React-compatible projects.
+   */
   react?: TPackage;
+  /**
+   * Package identifier used specifically for Next.js projects.
+   */
   next?: TPackage;
 }
+/**
+ * Detects common frontend frameworks from project dependencies.
+ *
+ * @remarks
+ * Detection reads the nearest project's `package.json` and looks at
+ * dependencies and devDependencies. It recognizes Next.js, Remix, Vite React,
+ * Gatsby, generic React, Tailwind CSS, and a configured core fallback.
+ *
+ * @typeParam TPackage - Product-specific package identifier returned in
+ * `FrameworkDetectionResult.pkg`.
+ * @param projectRoot - Directory containing the package.json to inspect.
+ * @param logger - Optional logger for debug diagnostics.
+ * @param packageMap - Product packages to select for detected frameworks.
+ * @returns Framework metadata and the selected product package identifier.
+ */
 declare function detectFramework<TPackage extends string = string>(projectRoot: string, logger?: CliLogger, packageMap?: FrameworkPackageMap<TPackage>): Promise<FrameworkDetectionResult<TPackage>>;
+/**
+ * Finds the nearest project root by walking up to a package.json.
+ *
+ * @remarks
+ * The search is capped at ten directory levels to avoid surprising filesystem
+ * traversal. When no root is found, the original current working directory is
+ * returned and a warning is logged.
+ *
+ * @param cwd - Directory where invocation started.
+ * @param logger - Optional logger for warning output.
+ * @returns The detected project root or `cwd` as a fallback.
+ */
 declare function detectProjectRoot(cwd: string, logger?: CliLogger): Promise<string>;
+/**
+ * Detects the package manager used by a project.
+ *
+ * @remarks
+ * Detection prefers lockfiles, then the `packageManager` field in
+ * `package.json`, then an optional interactive prompt, and finally `npm`.
+ *
+ * @param projectRoot - Directory to inspect for lockfiles and package.json.
+ * @param logger - Optional logger for debug output.
+ * @param options - Detection options.
+ * @returns Command templates for the detected package manager.
+ *
+ * @throws When interactive prompting is enabled and the user cancels package
+ * manager selection.
+ */
 declare function detectPackageManager(projectRoot: string, logger?: CliLogger, options?: {
   interactive?: boolean;
 }): Promise<PackageManagerResult>;
+/**
+ * Builds a dependency installation command for the detected package manager.
+ *
+ * @param pm - Package manager command templates.
+ * @param packages - Package names to install.
+ * @param options - Install command options.
+ * @returns A shell command string suitable for display or execution.
+ *
+ * @example
+ * ```ts
+ * getInstallCommand(pm, ['typescript'], { dev: true });
+ * ```
+ */
 declare function getInstallCommand(pm: PackageManagerResult, packages: string[], options?: {
   dev?: boolean;
 }): string;
+/**
+ * Builds a package-script command for the detected package manager.
+ *
+ * @param pm - Package manager command templates.
+ * @param script - Package script name to run.
+ * @returns A shell command string.
+ */
 declare function getRunCommand(pm: PackageManagerResult, script: string): string;
+/**
+ * Builds a one-off binary execution command for the detected package manager.
+ *
+ * @param pm - Package manager command templates.
+ * @param binary - Binary name to execute.
+ * @param args - Optional arguments appended after the binary name.
+ * @returns A shell command string.
+ */
 declare function getExecCommand(pm: PackageManagerResult, binary: string, args?: string[]): string;
 //#endregion
 //#region src/errors.d.ts
+/**
+ * Metadata used to render a known CLI error.
+ */
 interface ErrorCatalogEntry {
+  /**
+   * Stable machine-readable error code.
+   */
   code: string;
+  /**
+   * User-facing error message.
+   */
   message: string;
+  /**
+   * Optional recovery guidance displayed after the message.
+   */
   hint?: string;
+  /**
+   * Optional documentation URL displayed after the hint.
+   */
   docs?: string;
 }
+/**
+ * Error catalog keyed by stable error code.
+ */
 type ErrorCatalog = Record<string, ErrorCatalogEntry>;
+/**
+ * Built-in errors used by the Hexbus runtime.
+ */
 declare const DEFAULT_ERROR_CATALOG: {
+  readonly CANCELLED: {
+    readonly code: "CANCELLED";
+    readonly message: "Operation cancelled";
+  };
+  readonly COMMAND_NOT_FOUND: {
+    readonly code: "COMMAND_NOT_FOUND";
+    readonly hint: "Run --help to see available commands";
+    readonly message: "Unknown command";
+  };
   readonly CONFIG_NOT_FOUND: {
     readonly code: "CONFIG_NOT_FOUND";
-    readonly message: "Configuration not found";
     readonly hint: "Run the setup command to create a configuration";
+    readonly message: "Configuration not found";
   };
   readonly FLAG_VALUE_REQUIRED: {
     readonly code: "FLAG_VALUE_REQUIRED";
     readonly message: "Flag requires a value";
   };
-  readonly COMMAND_NOT_FOUND: {
-    readonly code: "COMMAND_NOT_FOUND";
-    readonly message: "Unknown command";
-    readonly hint: "Run --help to see available commands";
-  };
-  readonly CANCELLED: {
-    readonly code: "CANCELLED";
-    readonly message: "Operation cancelled";
-  };
   readonly UNKNOWN_ERROR: {
     readonly code: "UNKNOWN_ERROR";
     readonly message: "An unexpected error occurred";
   };
 };
+/**
+ * Adds or replaces entries in the active error catalog.
+ *
+ * @remarks
+ * This mutates process-local catalog state. Product CLIs should call it once
+ * during startup before command actions create `CliError` instances.
+ *
+ * @param entries - Error entries keyed by their stable code.
+ *
+ * @example
+ * ```ts
+ * extendErrorCatalog({
+ *   PROJECT_NOT_READY: {
+ *     code: 'PROJECT_NOT_READY',
+ *     message: 'Project is not ready',
+ *     hint: 'Run init before running this command.',
+ *   },
+ * });
+ * ```
+ */
 declare function extendErrorCatalog(entries: ErrorCatalog): void;
+/**
+ * Built-in or product-defined CLI error code.
+ */
 type ErrorCode = keyof typeof DEFAULT_ERROR_CATALOG | string;
+/**
+ * Error type that carries a catalog entry and optional structured context.
+ *
+ * @remarks
+ * `CliError` keeps command code focused on stable error codes while shared
+ * handlers render the configured message, hint, and documentation link.
+ */
 declare class CliError extends Error {
+  /**
+   * Error code requested by the caller.
+   */
   readonly code: ErrorCode;
+  /**
+   * Structured diagnostic details attached by the caller.
+   */
   readonly context?: Record<string, unknown>;
+  /**
+   * Catalog entry used to render this error.
+   */
   readonly entry: ErrorCatalogEntry;
+  /**
+   * Creates a catalog-backed CLI error.
+   *
+   * @param code - Built-in or product-defined error code.
+   * @param context - Optional diagnostic details for rendering or telemetry.
+   */
   constructor(code: ErrorCode, context?: Record<string, unknown>);
+  /**
+   * Renders the error message, hint, and docs link through a logger.
+   *
+   * @param logger - Logger used for user-facing output.
+   */
   display(logger: CliLogger): void;
+  /**
+   * Normalizes an unknown thrown value into a `CliError`.
+   *
+   * @param error - Value caught from a `try`/`catch` block.
+   * @param fallbackCode - Catalog code to use when `error` is not already a
+   * `CliError`.
+   * @returns `error` unchanged when it is already a `CliError`, otherwise a
+   * wrapped `CliError`.
+   */
   static from(error: unknown, fallbackCode?: ErrorCode): CliError;
 }
+/**
+ * Narrows an unknown value to a `CliError`.
+ *
+ * @param error - Value to inspect.
+ * @param code - Optional code that must match the error.
+ * @returns `true` when the value is a `CliError` and, if provided, matches the
+ * requested code.
+ */
 declare function isCliError(error: unknown, code?: ErrorCode): error is CliError;
+/**
+ * Creates shared process-ending error and cancellation handlers.
+ *
+ * @param logger - Logger used to render messages.
+ * @param telemetry - Optional telemetry sink for failed command errors.
+ * @returns Error handlers suitable for `CliContext.error`.
+ */
 declare function createErrorHandlers(logger: CliLogger, telemetry?: {
   trackError(error: Error, command?: string): void;
 }): {
-  handleError(error: unknown, command: string): never;
   handleCancel(message?: string, context?: {
     command?: string;
     stage?: string;
   }): never;
+  handleError(error: unknown, command: string): never;
 };
+/**
+ * Wraps an async function with CLI-style error rendering and process exit.
+ *
+ * @remarks
+ * This helper is useful near process entrypoints. Library-style code should
+ * usually throw `CliError` and let the caller decide when to exit.
+ *
+ * @typeParam T - Async function type to preserve.
+ * @param fn - Async function to run.
+ * @param logger - Logger used to render caught errors.
+ * @param context - Optional command metadata shown after an error.
+ * @returns A function with the same call signature as `fn`.
+ */
 declare function withErrorHandling<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, logger: CliLogger, context?: {
   command?: string;
 }): T;
 //#endregion
 //#region src/help.d.ts
+/**
+ * Metadata shown in the generated CLI help menu.
+ */
 interface ShowHelpMenuOptions {
+  /**
+   * CLI application name shown in usage and title text.
+   */
   appName: string;
+  /**
+   * CLI version shown near the top of the help menu.
+   */
   version: string;
+  /**
+   * Optional documentation URL shown after commands and global flags.
+   */
   docsUrl?: string;
 }
-declare function showHelpMenu(context: Pick<CliContext, 'logger'>, options: ShowHelpMenuOptions, commands: CliCommand[], flags: CliFlag[]): void;
+/**
+ * Renders a help menu for commands and global flags.
+ *
+ * @param context - Context subset providing the logger used for output.
+ * @param options - Application metadata for the help menu.
+ * @param commands - Commands to list; commands with `hidden: true` are
+ * omitted.
+ * @param flags - Global flags to list.
+ */
+declare function showHelpMenu(context: Pick<CliContext, "logger">, options: ShowHelpMenuOptions, commands: CliCommand[], flags: CliFlag[]): void;
 //#endregion
 //#region src/intro.d.ts
+/**
+ * Options for rendering a CLI intro banner.
+ */
 interface DisplayIntroOptions {
+  /**
+   * Application name used as the note title and default banner text.
+   */
   appName: string;
+  /**
+   * Optional application version shown in the fallback tagline.
+   */
   version?: string;
+  /**
+   * Optional tagline shown below the banner.
+   */
   tagline?: string;
+  /**
+   * Optional text passed to figlet instead of `appName`.
+   */
   figletText?: string;
 }
-declare function displayIntro(context: Pick<CliContext, 'logger'>, options: DisplayIntroOptions): Promise<void>;
+/**
+ * Renders a figlet banner and short intro note.
+ *
+ * @remarks
+ * If figlet rendering fails, the plain banner text is displayed instead.
+ *
+ * @param context - Context subset providing the logger used for output.
+ * @param options - Intro banner metadata.
+ */
+declare function displayIntro(context: Pick<CliContext, "logger">, options: DisplayIntroOptions): Promise<void>;
+//#endregion
+//#region src/color.d.ts
+/**
+ * Formats an arbitrary value as a string, optionally wrapping it in ANSI
+ * escape codes.
+ */
+type ColorFormatter = (input: unknown) => string;
+/**
+ * Collection of ANSI style and color formatters.
+ *
+ * @remarks
+ * When color is disabled, every formatter returns the input converted with
+ * `String(input)` and does not add escape codes.
+ */
+interface Colors {
+  /**
+   * Whether this formatter set emits ANSI escape codes.
+   */
+  isColorSupported: boolean;
+  /** Resets all ANSI styles. */
+  reset: ColorFormatter;
+  /** Applies bold text styling. */
+  bold: ColorFormatter;
+  /** Applies dim text styling. */
+  dim: ColorFormatter;
+  /** Applies italic text styling. */
+  italic: ColorFormatter;
+  /** Applies underline text styling. */
+  underline: ColorFormatter;
+  /** Applies inverse foreground/background styling. */
+  inverse: ColorFormatter;
+  /** Applies hidden text styling. */
+  hidden: ColorFormatter;
+  /** Applies strikethrough text styling. */
+  strikethrough: ColorFormatter;
+  /** Applies black foreground color. */
+  black: ColorFormatter;
+  /** Applies red foreground color. */
+  red: ColorFormatter;
+  /** Applies green foreground color. */
+  green: ColorFormatter;
+  /** Applies yellow foreground color. */
+  yellow: ColorFormatter;
+  /** Applies blue foreground color. */
+  blue: ColorFormatter;
+  /** Applies magenta foreground color. */
+  magenta: ColorFormatter;
+  /** Applies cyan foreground color. */
+  cyan: ColorFormatter;
+  /** Applies white foreground color. */
+  white: ColorFormatter;
+  /** Applies gray foreground color. */
+  gray: ColorFormatter;
+  /** Applies black background color. */
+  bgBlack: ColorFormatter;
+  /** Applies red background color. */
+  bgRed: ColorFormatter;
+  /** Applies green background color. */
+  bgGreen: ColorFormatter;
+  /** Applies yellow background color. */
+  bgYellow: ColorFormatter;
+  /** Applies blue background color. */
+  bgBlue: ColorFormatter;
+  /** Applies magenta background color. */
+  bgMagenta: ColorFormatter;
+  /** Applies cyan background color. */
+  bgCyan: ColorFormatter;
+  /** Applies white background color. */
+  bgWhite: ColorFormatter;
+  /** Applies bright black foreground color. */
+  blackBright: ColorFormatter;
+  /** Applies bright red foreground color. */
+  redBright: ColorFormatter;
+  /** Applies bright green foreground color. */
+  greenBright: ColorFormatter;
+  /** Applies bright yellow foreground color. */
+  yellowBright: ColorFormatter;
+  /** Applies bright blue foreground color. */
+  blueBright: ColorFormatter;
+  /** Applies bright magenta foreground color. */
+  magentaBright: ColorFormatter;
+  /** Applies bright cyan foreground color. */
+  cyanBright: ColorFormatter;
+  /** Applies bright white foreground color. */
+  whiteBright: ColorFormatter;
+  /** Applies bright black background color. */
+  bgBlackBright: ColorFormatter;
+  /** Applies bright red background color. */
+  bgRedBright: ColorFormatter;
+  /** Applies bright green background color. */
+  bgGreenBright: ColorFormatter;
+  /** Applies bright yellow background color. */
+  bgYellowBright: ColorFormatter;
+  /** Applies bright blue background color. */
+  bgBlueBright: ColorFormatter;
+  /** Applies bright magenta background color. */
+  bgMagentaBright: ColorFormatter;
+  /** Applies bright cyan background color. */
+  bgCyanBright: ColorFormatter;
+  /** Applies bright white background color. */
+  bgWhiteBright: ColorFormatter;
+}
+/**
+ * Default color formatter object plus a factory for creating formatter sets
+ * with explicit color support.
+ */
+type Color = Colors & {
+  createColors: typeof createColors;
+};
+/**
+ * Creates a complete set of color and style formatters.
+ *
+ * @param enabled - Whether returned formatters should emit ANSI escape codes.
+ * @returns A `Colors` object with either active ANSI formatters or plain string
+ * pass-through formatters.
+ */
+declare function createColors(enabled?: boolean): Colors;
+/**
+ * Default color formatter set for the current process.
+ *
+ * @remarks
+ * Use `color.createColors(false)` when tests need deterministic plain-text
+ * output.
+ */
+declare const color: Color;
 //#endregion
 //#region src/logger.d.ts
+/**
+ * Supported log levels in ascending verbosity.
+ */
 declare const LOG_LEVELS: LogLevel[];
+/**
+ * Alias for `LOG_LEVELS` kept for callers that prefer validation-oriented
+ * naming.
+ */
 declare const validLogLevels: LogLevel[];
-declare function formatLogMessage(logLevel: LogLevel | 'success' | 'failed' | string, message: unknown, args?: unknown[]): string;
-declare function logMessage(logLevel: LogLevel | 'success' | 'failed' | string, message: unknown, ...args: unknown[]): void;
+/**
+ * Formats a log message with a level badge and optional structured arguments.
+ *
+ * @param logLevel - Log level or custom badge label.
+ * @param message - Primary message to render.
+ * @param args - Additional values rendered as indented JSON-like bullets.
+ * @returns A formatted message string.
+ */
+declare function formatLogMessage(logLevel: LogLevel | "success" | "failed" | string, message: unknown, args?: unknown[]): string;
+/**
+ * Emits a formatted message through the prompt logger.
+ *
+ * @param logLevel - Log level or custom badge label.
+ * @param message - Primary message to render.
+ * @param args - Additional values rendered below the message.
+ */
+declare function logMessage(logLevel: LogLevel | "success" | "failed" | string, message: unknown, ...args: unknown[]): void;
+/**
+ * Formats a bounded progress step indicator.
+ *
+ * @remarks
+ * `current` is clamped between `0` and `total`, and `total` is clamped to at
+ * least `0` so malformed progress values still render predictably.
+ *
+ * @param current - Current step number.
+ * @param total - Total number of steps.
+ * @param label - Step label shown after the progress bar.
+ * @returns A formatted progress row.
+ */
 declare function formatStep(current: number, total: number, label: string): string;
+/**
+ * Creates a `CliLogger` backed by Clack prompt output.
+ *
+ * @remarks
+ * Messages below the configured verbosity are ignored for `debug`, `info`,
+ * `warn`, and `error`. Other output helpers such as `message`, `note`,
+ * `success`, `failed`, and `outro` always render because they represent
+ * explicit user interaction states rather than diagnostic verbosity.
+ *
+ * @param level - Minimum log level to emit.
+ * @returns A logger suitable for `CliContext.logger`.
+ */
 declare function createCliLogger(level?: LogLevel): CliLogger;
 //#endregion
 //#region src/parser.d.ts
+/**
+ * Built-in flags parsed for every Hexbus CLI invocation.
+ *
+ * @remarks
+ * Primary flag names are derived from the first long flag in each entry. For
+ * example, `--no-telemetry` is exposed as `parsedFlags['no-telemetry']`.
+ */
 declare const globalFlags: CliFlag[];
-declare function parseCliArgs(rawArgs: string[], commands: CliCommand[]): ParsedArgs;
+/**
+ * Parses raw command-line arguments into command name, command args, and
+ * global and caller-provided flags.
+ *
+ * @remarks
+ * Flags declared in `globalFlags` and `flags` are parsed. Unknown flags and
+ * other positional arguments are preserved as command arguments. If the first
+ * positional argument matches a registered top-level command in `commands`, it
+ * is returned as `commandName` and removed from `commandArgs`.
+ *
+ * @param rawArgs - Arguments after the executable and script path.
+ * @param commands - Top-level commands used to identify the command name.
+ * @param flags - Additional global flag definitions to parse alongside
+ * `globalFlags`. Caller-provided flags override built-in definitions that use
+ * the same primary flag name.
+ * @returns Normalized parsed output containing the matched command name,
+ * remaining command arguments, and parsed flag values keyed by primary name.
+ *
+ * @example
+ * ```ts
+ * const parsed = parseCliArgs(['init', '--logger', 'debug'], commands);
+ * // parsed.commandName === 'init'
+ * // parsed.parsedFlags.logger === 'debug'
+ * ```
+ */
+declare function parseCliArgs(rawArgs: string[], commands: CliCommand[], flags?: CliFlag[]): ParsedArgs;
+/**
+ * Formats a single flag for display in help output.
+ *
+ * @param flag - Flag definition to render.
+ * @returns A help row containing names, value hint, and description.
+ */
 declare function formatFlagHelp(flag: CliFlag): string;
-declare function generateFlagsHelp(): string;
-declare function hasFlag(flags: ParsedArgs['parsedFlags'], name: string): boolean;
-declare function getFlagValue(flags: ParsedArgs['parsedFlags'], name: string): string | undefined;
+/**
+ * Formats a provided set of flags for help output.
+ *
+ * @param flags - Flag definitions to render with `formatFlagHelp`, defaulting
+ * to `globalFlags`.
+ *
+ * @returns Newline-delimited help rows for the provided flag definitions.
+ */
+declare function generateFlagsHelp(flags?: CliFlag[]): string;
+/**
+ * Checks whether a parsed boolean flag is enabled.
+ *
+ * @param flags - Parsed flag map from `parseCliArgs` or `CliContext`.
+ * @param name - Primary flag name without leading dashes.
+ * @returns `true` only when the flag value is exactly `true`.
+ *
+ * @example
+ * ```ts
+ * if (hasFlag(context.flags, 'force')) {
+ *   // overwrite existing files
+ * }
+ * ```
+ */
+declare function hasFlag(flags: ParsedArgs["parsedFlags"], name: string): boolean;
+/**
+ * Reads a string-valued flag from a parsed flag map.
+ *
+ * @param flags - Parsed flag map from `parseCliArgs` or `CliContext`.
+ * @param name - Primary flag name without leading dashes.
+ * @returns The flag value when it is a string, otherwise `undefined`.
+ */
+declare function getFlagValue(flags: ParsedArgs["parsedFlags"], name: string): string | undefined;
+/**
+ * Splits command arguments into an optional nested subcommand and remaining
+ * args.
+ *
+ * @param args - Positional command arguments to inspect.
+ * @param subcommands - Available subcommands for the current command.
+ * @returns The matched subcommand, if any, plus arguments after the subcommand
+ * name.
+ *
+ * @example
+ * ```ts
+ * const { subcommand, remainingArgs } = parseSubcommand(
+ *   context.commandArgs,
+ *   command.subcommands ?? []
+ * );
+ * ```
+ */
 declare function parseSubcommand(args: string[], subcommands: CliCommand[]): {
   subcommand: CliCommand | undefined;
   remainingArgs: string[];
 };
 //#endregion
 //#region src/spinner.d.ts
+/**
+ * Minimal spinner controller used for long-running CLI tasks.
+ */
 interface Spinner {
+  /**
+   * Starts the spinner with an optional message override.
+   */
   start(message?: string): void;
+  /**
+   * Stops the spinner with an optional completion message.
+   */
   stop(message?: string): void;
+  /**
+   * Updates the spinner message while it is running.
+   */
   message(message: string): void;
 }
+/**
+ * Creates a Clack-backed spinner.
+ *
+ * @param initialMessage - Message used when `start()` is called without an
+ * explicit message.
+ * @returns A spinner controller.
+ */
 declare function createSpinner(initialMessage?: string): Spinner;
+/**
+ * Runs an async task while displaying a spinner.
+ *
+ * @typeParam T - Value returned by the task.
+ * @param message - Message shown when the spinner starts.
+ * @param task - Async work to run.
+ * @param options - Optional success and error messages shown when the task
+ * settles.
+ * @returns The value returned by `task`.
+ *
+ * @throws Re-throws any error from `task` after stopping the spinner.
+ */
 declare function withSpinner<T>(message: string, task: () => Promise<T>, options?: {
   successMessage?: string;
   errorMessage?: string;
 }): Promise<T>;
 //#endregion
 //#region src/telemetry.d.ts
+/**
+ * Options for the built-in in-memory telemetry client.
+ */
 interface TelemetryOptions {
+  /**
+   * Disables telemetry completely.
+   */
   disabled?: boolean;
+  /**
+   * Logs queued telemetry payloads through the optional debug logger.
+   */
   debug?: boolean;
+  /**
+   * HTTP endpoint that receives telemetry batches on flush.
+   */
   endpoint?: string;
+  /**
+   * Application name included in every telemetry event.
+   *
+   * @default "cli"
+   */
   appName?: string;
+  /**
+   * Environment variable prefix used for opt-out detection.
+   *
+   * @remarks
+   * A prefix of `MY_CLI` reads `MY_CLI_TELEMETRY_DISABLED`.
+   *
+   * @default "APP"
+   */
   envVarPrefix?: string;
+  /**
+   * Properties merged into every telemetry event before event-specific
+   * properties.
+   */
   defaultProperties?: Record<string, unknown>;
-  logger?: Pick<CliLogger, 'debug' | 'warn'>;
+  /**
+   * Logger used for debug payload output and flush warnings.
+   */
+  logger?: Pick<CliLogger, "debug" | "warn">;
 }
+/**
+ * Standard telemetry event names emitted by Hexbus runtime helpers.
+ */
 declare const TelemetryEventName: {
-  readonly CLI_INVOKED: "cli_invoked";
-  readonly CLI_ENVIRONMENT_DETECTED: "cli_environment_detected";
   readonly CLI_COMPLETED: "cli_completed";
+  readonly CLI_ENVIRONMENT_DETECTED: "cli_environment_detected";
+  readonly CLI_INVOKED: "cli_invoked";
+  readonly COMMAND_FAILED: "command_failed";
   readonly COMMAND_INVOKED: "command_invoked";
   readonly COMMAND_SUCCEEDED: "command_succeeded";
-  readonly COMMAND_FAILED: "command_failed";
   readonly COMMAND_UNKNOWN: "command_unknown";
   readonly ERROR_OCCURRED: "error_occurred";
   readonly HELP_DISPLAYED: "help_displayed";
-  readonly VERSION_DISPLAYED: "version_displayed";
-  readonly INTERACTIVE_MENU_OPENED: "interactive_menu_opened";
   readonly INTERACTIVE_MENU_EXITED: "interactive_menu_exited";
+  readonly INTERACTIVE_MENU_OPENED: "interactive_menu_opened";
+  readonly VERSION_DISPLAYED: "version_displayed";
 };
+/**
+ * Union of standard telemetry event name string values.
+ */
 type TelemetryEventNameType = (typeof TelemetryEventName)[keyof typeof TelemetryEventName];
+/**
+ * Creates a no-op telemetry client.
+ *
+ * @returns A telemetry implementation whose methods do nothing and whose
+ * `isDisabled()` method returns `true`.
+ */
 declare function createDisabledTelemetry(): Telemetry;
+/**
+ * Creates the built-in telemetry client.
+ *
+ * @remarks
+ * Events are queued in memory. `flush()` posts the queue to `endpoint` when one
+ * is configured, then clears the queue. Failed flushes are reported through
+ * the optional logger and do not throw, keeping telemetry best effort.
+ *
+ * @param options - Telemetry behavior and event defaults.
+ * @returns An enabled or disabled telemetry client depending on options and
+ * environment opt-out variables.
+ */
 declare function createTelemetry(options?: TelemetryOptions): Telemetry;
 //#endregion
-//#region src/version-check.d.ts
-type InstallSource = 'npm-global' | 'brew' | 'npx' | 'bunx' | 'pnpm-dlx' | 'yarn-dlx' | 'local' | 'unknown';
+//#region src/version-check/types.d.ts
+/**
+ * Installation source inferred from the running binary path and package manager
+ * environment.
+ */
+type InstallSource = "npm-global" | "brew" | "npx" | "bunx" | "pnpm-dlx" | "yarn-dlx" | "local" | "unknown";
+/**
+ * Result returned by an update check.
+ */
 interface UpdateCheckResult {
+  /**
+   * Version currently running.
+   */
   currentVersion: string;
+  /**
+   * Latest version fetched from the registry or cache, or `null` when lookup
+   * failed.
+   */
   latestVersion: string | null;
+  /**
+   * Whether `latestVersion` is newer than `currentVersion`.
+   *
+   * @remarks
+   * This is `false` when `latestVersion` is `null` due to lookup failure.
+   * Callers can check `latestVersion === null` to distinguish lookup failure
+   * from an up-to-date package.
+   */
   isOutdated: boolean;
+  /**
+   * Detected installation source for the current binary.
+   */
   source: InstallSource;
+  /**
+   * Update command appropriate for the detected source, when Hexbus can infer
+   * one.
+   */
   updateCommand: string | null;
+  /**
+   * User-facing update hint, or `null` when no actionable update is available.
+   */
   hint: string | null;
 }
+/**
+ * Options for checking package registry state and update hints.
+ */
 interface UpdateCheckOptions {
+  /**
+   * Published package name to query.
+   */
   packageName: string;
+  /**
+   * Version currently running.
+   */
   currentVersion: string;
+  /**
+   * Homebrew formula name used for Homebrew update hints.
+   *
+   * @default packageName
+   */
   brewFormula?: string;
+  /**
+   * Registry base URL used to fetch latest package metadata.
+   *
+   * @default "https://registry.npmjs.org"
+   */
   registryUrl?: string;
+  /**
+   * Maximum registry request duration in milliseconds.
+   *
+   * @default 1500
+   */
   timeoutMs?: number;
+  /**
+   * Directory where latest-version cache files are stored.
+   *
+   * @default path.join(os.tmpdir(), "hexbus-version-cache")
+   */
   cacheDir?: string;
+  /**
+   * How long cached latest-version data stays fresh.
+   *
+   * @default 86400000
+   */
   cacheTtlMs?: number;
+  /**
+   * Binary path used for installation-source detection.
+   *
+   * @default process.argv[1]
+   */
   binPath?: string;
+  /**
+   * Optional logger used for debug output when update checks fail.
+   */
+  logger?: VersionInfoLogger;
+  /**
+   * Clock override used by tests and deterministic callers.
+   *
+   * @default Date.now
+   */
   now?: () => number;
 }
-type VersionInfoLogger = Pick<CliLogger, 'message' | 'note'> & Partial<Pick<CliLogger, 'debug'>>;
+type VersionInfoLogger = Pick<CliLogger, "message" | "note"> & Partial<Pick<CliLogger, "debug">>;
+/**
+ * Options for printing or background-checking CLI version information.
+ */
 interface VersionInfoOptions extends UpdateCheckOptions {
+  /**
+   * Application name shown in version output.
+   */
   appName: string;
-  logger?: VersionInfoLogger;
 }
+//#endregion
+//#region src/version-check/check.d.ts
+/**
+ * Checks whether raw arguments request version output.
+ *
+ * @param rawArgs - Arguments after executable and script path.
+ * @returns `true` when `-v` or `--version` is present.
+ */
 declare function isVersionRequest(rawArgs: string[]): boolean;
-declare function detectInstallSource(binPath?: string): InstallSource;
-declare function getUpdateCommand(source: InstallSource, packageName: string, brewFormula?: string): string | null;
-declare function checkForUpdate(options: UpdateCheckOptions): Promise<UpdateCheckResult>;
+/**
+ * Formats a user-facing update hint from an update-check result.
+ *
+ * @param result - Update-check result to render.
+ * @returns A formatted hint when the result is outdated and has an update
+ * command, otherwise `null`.
+ */
 declare function formatUpdateHint(result: UpdateCheckResult): string | null;
+/**
+ * Checks whether a newer package version is available.
+ *
+ * @remarks
+ * The function first reads the local cache. On a cache miss it refreshes the
+ * cache from the configured registry. Refresh failures produce a result with
+ * `latestVersion: null` rather than throwing.
+ *
+ * @param options - Update-check configuration.
+ * @returns Update metadata and a formatted hint when an update is available.
+ */
+declare function checkForUpdate(options: UpdateCheckOptions): Promise<UpdateCheckResult>;
+//#endregion
+//#region src/version-check/display.d.ts
+/**
+ * Prints CLI version information and any available update hint.
+ *
+ * @param options - Version display and update-check options.
+ */
 declare function printVersionInfo(options: VersionInfoOptions): Promise<void>;
+/**
+ * Starts a non-blocking update check.
+ *
+ * @remarks
+ * Cached hints are displayed synchronously when available. If the cache is
+ * stale or missing, a refresh is started in the background and failures are
+ * only logged at debug level.
+ *
+ * @param options - Version display and update-check options.
+ */
 declare function startBackgroundUpdateCheck(options: VersionInfoOptions): void;
 //#endregion
+//#region src/version-check/install-source.d.ts
+/**
+ * Infers how the current CLI binary was installed.
+ *
+ * @remarks
+ * Detection is heuristic and based on binary path, realpath, and package
+ * manager environment variables. Unknown or transient install modes return
+ * `unknown` instead of throwing.
+ *
+ * @param binPath - Binary path to inspect.
+ * @returns The inferred installation source.
+ */
+declare function detectInstallSource(binPath?: string): InstallSource;
+/**
+ * Builds an update command for an installation source.
+ *
+ * @param source - Installation source returned by `detectInstallSource`.
+ * @param packageName - Package name to update.
+ * @param brewFormula - Homebrew formula name when `source` is `brew`.
+ * @returns A command string when the source has an actionable update path,
+ * otherwise `null`.
+ */
+declare function getUpdateCommand(source: InstallSource, packageName: string, brewFormula?: string): string | null;
+//#endregion
 export { type CliCommand, type CliContext, CliError, type CliFlag, type CliLogger, type ConfigManagement, type CreateContextOptions, DEFAULT_ERROR_CATALOG, type DisplayIntroOptions, type ErrorCatalog, type ErrorCatalogEntry, type ErrorCode, type ErrorHandlers, type FileSystemUtils, type FlagType, type FrameworkDetectionResult, type FrameworkPackageMap, type InstallSource, LOG_LEVELS, type LogLevel, type PackageInfo, type PackageManager, type PackageManagerResult, type ParsedArgs, type ShowHelpMenuOptions, type Spinner, type Telemetry, TelemetryEventName, type TelemetryEventNameType, type TelemetryOptions, type UpdateCheckOptions, type UpdateCheckResult, type VersionInfoOptions, checkForUpdate, color, createCliContext, createCliLogger, createDisabledTelemetry, createErrorHandlers, createSpinner, createTelemetry, createTestContext, detectFramework, detectInstallSource, detectPackageManager, detectProjectRoot, displayIntro, extendErrorCatalog, formatFlagHelp, formatLogMessage, formatStep, formatUpdateHint, generateFlagsHelp, getExecCommand, getFlagValue, getInstallCommand, getRunCommand, getUpdateCommand, globalFlags, hasFlag, isCliError, isVersionRequest, logMessage, parseCliArgs, parseSubcommand, printVersionInfo, showHelpMenu, startBackgroundUpdateCheck, validLogLevels, withErrorHandling, withSpinner };