hexbus 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# hexbus
+
+Reusable CLI chassis for Hexbus tools.
+
+Includes:
+
+- argument parsing and global flags
+- context creation
+- logger and spinner helpers
+- configurable telemetry
+- configurable error catalog
+- project root, framework, and package manager detection
+- intro and help rendering
+
+```ts
+import { createCliContext, displayIntro, showHelpMenu } from 'hexbus';
+```

package/dist/index.d.mts

@@ -0,0 +1,312 @@
+import color from "picocolors";
+
+//#region src/types.d.ts
+type LogLevel = 'error' | 'warn' | 'info' | 'debug';
+type FlagType = 'boolean' | 'string' | 'special';
+interface CliFlag {
+  names: string[];
+  description: string;
+  type: FlagType;
+  expectsValue: boolean;
+  defaultValue?: string | boolean;
+}
+interface ParsedArgs {
+  commandName: string | undefined;
+  commandArgs: string[];
+  parsedFlags: Record<string, string | boolean | undefined>;
+}
+interface CliCommand<TContext extends CliContext = CliContext> {
+  name: string;
+  label: string;
+  hint: string;
+  description: string;
+  action: (context: TContext) => Promise<void>;
+  subcommands?: CliCommand<TContext>[];
+  hidden?: boolean;
+}
+interface PackageInfo {
+  name: string;
+  version: string;
+  [key: string]: unknown;
+}
+interface FrameworkDetectionResult<TPackage extends string = string> {
+  framework: string | null;
+  frameworkVersion: string | null;
+  pkg: TPackage | null;
+  hasReact: boolean;
+  reactVersion: string | null;
+  tailwindVersion: string | null;
+}
+type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun';
+interface PackageManagerResult {
+  name: PackageManager;
+  installCommand: string;
+  addCommand: string;
+  runCommand: string;
+  execCommand: string;
+  version?: string | null;
+}
+interface CliLogger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+  message(message: string): void;
+  note(content: string, title?: string): void;
+  outro(message: string): void;
+  success(message: string): void;
+  failed(message: string, exitCode?: number): never;
+  step(current: number, total: number, label: string): void;
+}
+interface ErrorHandlers {
+  handleError(error: unknown, command: string): never;
+  handleCancel(message?: string, context?: {
+    command?: string;
+    stage?: string;
+  }): never;
+}
+interface ConfigManagement {
+  loadConfig<TConfig = unknown>(): Promise<TConfig | null>;
+  requireConfig<TConfig = unknown>(): Promise<TConfig>;
+  getPathAliases(configPath?: string): Record<string, string> | null;
+}
+interface FileSystemUtils {
+  getPackageInfo(): PackageInfo;
+  exists(path: string): Promise<boolean>;
+  read(path: string): Promise<string>;
+  write(path: string, content: string): Promise<void>;
+  mkdir(path: string): Promise<void>;
+}
+interface Telemetry {
+  trackEvent(eventName: string, properties?: Record<string, unknown>): void;
+  trackCommand(command: string, args?: string[], flags?: Record<string, string | number | boolean | undefined>): void;
+  trackError(error: Error, command?: string): void;
+  flush(): Promise<void>;
+  shutdown(): Promise<void>;
+  isDisabled(): boolean;
+}
+interface CliContext<TPackage extends string = string> {
+  logger: CliLogger;
+  flags: ParsedArgs['parsedFlags'];
+  commandName: string | undefined;
+  commandArgs: string[];
+  cwd: string;
+  error: ErrorHandlers;
+  config: ConfigManagement;
+  fs: FileSystemUtils;
+  telemetry: Telemetry;
+  confirm(message: string, initialValue?: boolean): Promise<boolean>;
+  projectRoot: string;
+  framework: FrameworkDetectionResult<TPackage>;
+  packageManager: PackageManagerResult;
+}
+//#endregion
+//#region src/context.d.ts
+interface CreateContextOptions<TPackage extends string = string> {
+  rawArgs: string[];
+  cwd?: string;
+  commands: CliCommand[];
+  appName?: string;
+  configName?: string;
+  telemetry?: {
+    disabled?: boolean;
+    debug?: boolean;
+    endpoint?: string;
+    envVarPrefix?: string;
+    defaultProperties?: Record<string, unknown>;
+  };
+  packageMap?: {
+    core?: TPackage;
+    react?: TPackage;
+    next?: TPackage;
+  };
+  interactivePackageManagerDetection?: boolean;
+}
+declare function createCliContext<TPackage extends string = string>(options: CreateContextOptions<TPackage>): Promise<CliContext<TPackage>>;
+declare function createTestContext(overrides?: Partial<CliContext>): CliContext;
+//#endregion
+//#region src/detection.d.ts
+interface FrameworkPackageMap<TPackage extends string = string> {
+  core?: TPackage;
+  react?: TPackage;
+  next?: TPackage;
+}
+declare function detectFramework<TPackage extends string = string>(projectRoot: string, logger?: CliLogger, packageMap?: FrameworkPackageMap<TPackage>): Promise<FrameworkDetectionResult<TPackage>>;
+declare function detectProjectRoot(cwd: string, logger?: CliLogger): Promise<string>;
+declare function detectPackageManager(projectRoot: string, logger?: CliLogger, options?: {
+  interactive?: boolean;
+}): Promise<PackageManagerResult>;
+declare function getInstallCommand(pm: PackageManagerResult, packages: string[], options?: {
+  dev?: boolean;
+}): string;
+declare function getRunCommand(pm: PackageManagerResult, script: string): string;
+declare function getExecCommand(pm: PackageManagerResult, binary: string, args?: string[]): string;
+//#endregion
+//#region src/errors.d.ts
+interface ErrorCatalogEntry {
+  code: string;
+  message: string;
+  hint?: string;
+  docs?: string;
+}
+type ErrorCatalog = Record<string, ErrorCatalogEntry>;
+declare const DEFAULT_ERROR_CATALOG: {
+  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 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";
+  };
+};
+declare function extendErrorCatalog(entries: ErrorCatalog): void;
+type ErrorCode = keyof typeof DEFAULT_ERROR_CATALOG | string;
+declare class CliError extends Error {
+  readonly code: ErrorCode;
+  readonly context?: Record<string, unknown>;
+  readonly entry: ErrorCatalogEntry;
+  constructor(code: ErrorCode, context?: Record<string, unknown>);
+  display(logger: CliLogger): void;
+  static from(error: unknown, fallbackCode?: ErrorCode): CliError;
+}
+declare function isCliError(error: unknown, code?: ErrorCode): error is CliError;
+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;
+};
+declare function withErrorHandling<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, logger: CliLogger, context?: {
+  command?: string;
+}): T;
+//#endregion
+//#region src/help.d.ts
+interface ShowHelpMenuOptions {
+  appName: string;
+  version: string;
+  docsUrl?: string;
+}
+declare function showHelpMenu(context: Pick<CliContext, 'logger'>, options: ShowHelpMenuOptions, commands: CliCommand[], flags: CliFlag[]): void;
+//#endregion
+//#region src/intro.d.ts
+interface DisplayIntroOptions {
+  appName: string;
+  version?: string;
+  tagline?: string;
+  figletText?: string;
+}
+declare function displayIntro(context: Pick<CliContext, 'logger'>, options: DisplayIntroOptions): Promise<void>;
+//#endregion
+//#region src/logger.d.ts
+declare const LOG_LEVELS: LogLevel[];
+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;
+declare function formatStep(current: number, total: number, label: string): string;
+declare function createCliLogger(level?: LogLevel): CliLogger;
+//#endregion
+//#region src/parser.d.ts
+declare const globalFlags: CliFlag[];
+declare function parseCliArgs(rawArgs: string[], commands: CliCommand[]): ParsedArgs;
+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;
+declare function parseSubcommand(args: string[], subcommands: CliCommand[]): {
+  subcommand: CliCommand | undefined;
+  remainingArgs: string[];
+};
+//#endregion
+//#region src/spinner.d.ts
+interface Spinner {
+  start(message?: string): void;
+  stop(message?: string): void;
+  message(message: string): void;
+}
+declare function createSpinner(initialMessage?: string): Spinner;
+declare function withSpinner<T>(message: string, task: () => Promise<T>, options?: {
+  successMessage?: string;
+  errorMessage?: string;
+}): Promise<T>;
+//#endregion
+//#region src/telemetry.d.ts
+interface TelemetryOptions {
+  disabled?: boolean;
+  debug?: boolean;
+  endpoint?: string;
+  appName?: string;
+  envVarPrefix?: string;
+  defaultProperties?: Record<string, unknown>;
+  logger?: Pick<CliLogger, 'debug' | 'warn'>;
+}
+declare const TelemetryEventName: {
+  readonly CLI_INVOKED: "cli_invoked";
+  readonly CLI_ENVIRONMENT_DETECTED: "cli_environment_detected";
+  readonly CLI_COMPLETED: "cli_completed";
+  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";
+};
+type TelemetryEventNameType = (typeof TelemetryEventName)[keyof typeof TelemetryEventName];
+declare function createDisabledTelemetry(): Telemetry;
+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';
+interface UpdateCheckResult {
+  currentVersion: string;
+  latestVersion: string | null;
+  isOutdated: boolean;
+  source: InstallSource;
+  updateCommand: string | null;
+  hint: string | null;
+}
+interface UpdateCheckOptions {
+  packageName: string;
+  currentVersion: string;
+  brewFormula?: string;
+  registryUrl?: string;
+  timeoutMs?: number;
+  cacheDir?: string;
+  cacheTtlMs?: number;
+  binPath?: string;
+  now?: () => number;
+}
+type VersionInfoLogger = Pick<CliLogger, 'message' | 'note'> & Partial<Pick<CliLogger, 'debug'>>;
+interface VersionInfoOptions extends UpdateCheckOptions {
+  appName: string;
+  logger?: VersionInfoLogger;
+}
+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>;
+declare function formatUpdateHint(result: UpdateCheckResult): string | null;
+declare function printVersionInfo(options: VersionInfoOptions): Promise<void>;
+declare function startBackgroundUpdateCheck(options: VersionInfoOptions): void;
+//#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 };