@reliverse/rempts-core 1.6.1 → 2.3.2

package/src/plugin/types.ts

@@ -0,0 +1,206 @@
+/**
+ * Core plugin types and interfaces for Rempts
+ */
+
+import type { Command, RemptsConfig, ResolvedConfig } from "../types";
+import type { Logger } from "../utils/logger";
+import type { PluginStore } from "./store";
+
+// Command definition type for plugins
+export type CommandDefinition = Command<any>;
+
+/**
+ * Functional plugin hooks with store type
+ */
+export interface PluginHooks<TStore = {}> {
+  /** Plugin store - Zustand store instance */
+  store?: PluginStore<TStore>;
+
+  /**
+   * Setup hook - Called during CLI initialization
+   * Can modify configuration and register commands
+   */
+  setup?: (context: PluginContext) => void | Promise<void>;
+
+  /**
+   * Config resolved hook - Called after all configuration is finalized
+   * Config is now immutable
+   */
+  configResolved?: (config: ResolvedConfig) => void | Promise<void>;
+
+  /**
+   * Before command hook - Called before command execution
+   * Can inject context and validate
+   * Uses generic constraints to preserve store type information
+   */
+  beforeCommand?: (context: CommandContext<any>) => void | Promise<void>;
+
+  /**
+   * After command hook - Called after command execution
+   * Receives result or error from command
+   * Uses generic constraints to preserve store type information
+   */
+  afterCommand?: (context: CommandContext<any> & CommandResult) => void | Promise<void>;
+}
+
+/**
+ * Core plugin function that returns hooks
+ */
+export type Plugin<TStore = {}> = () => PluginHooks<TStore>;
+
+/**
+ * Extract store type from plugin hooks
+ */
+export type StoreOf<P> = P extends PluginHooks<infer S> ? S : {};
+
+/**
+ * Merge multiple plugin stores into one type
+ */
+export type MergeStores<Plugins extends readonly PluginHooks[]> = Plugins extends readonly []
+  ? {}
+  : Plugins extends readonly [infer First, ...infer Rest]
+    ? First extends PluginHooks
+      ? Rest extends readonly PluginHooks[]
+        ? StoreOf<First> & MergeStores<Rest>
+        : StoreOf<First>
+      : {}
+    : {};
+
+/**
+ * Merge stores from plugin functions
+ */
+export type MergePluginStores<Plugins extends readonly Plugin[]> = Plugins extends readonly []
+  ? {}
+  : Plugins extends readonly [infer First, ...infer Rest]
+    ? First extends Plugin<infer S>
+      ? Rest extends readonly Plugin[]
+        ? S & MergePluginStores<Rest>
+        : S
+      : {}
+    : {};
+
+/**
+ * Plugin factory function type - returns a function that creates hooks
+ */
+export type PluginFactory<TOptions = any, TStore = {}> = (options?: TOptions) => Plugin<TStore>;
+
+/**
+ * Command execution result
+ */
+export interface CommandResult {
+  /** Command return value */
+  result?: any;
+
+  /** Error if command failed */
+  error?: Error;
+
+  /** Exit code */
+  exitCode?: number;
+}
+
+/**
+ * Plugin configuration types
+ */
+export type PluginConfig =
+  | string // Path to plugin
+  | Plugin // Plugin function
+  | PluginFactory // Plugin factory function
+  | [PluginFactory, any]; // Plugin with options
+
+/**
+ * Plugin context available during setup
+ */
+export interface PluginContext {
+  /** Current configuration (being built) */
+  readonly config: Partial<RemptsConfig>;
+
+  /** Update configuration */
+  updateConfig(partial: Partial<RemptsConfig>): void;
+
+  /** Register a new command */
+  registerCommand(command: CommandDefinition): void;
+
+  /** Add global middleware */
+  use(middleware: Middleware): void;
+
+  /** Shared storage between plugins */
+  readonly store: PluginStore<any>;
+
+  /** Plugin logger */
+  readonly logger: Logger;
+
+  /** System paths */
+  readonly paths: PathInfo;
+}
+
+/**
+ * Command execution context
+ */
+export interface CommandContext<TStore = {}> {
+  /** Command name being executed */
+  readonly command: string;
+
+  /** The Command object being executed */
+  readonly commandDef: Command<any, TStore>;
+
+  /** Positional arguments */
+  readonly args: string[];
+
+  /** Parsed flags/options */
+  readonly flags: Record<string, any>;
+
+  /** Environment information */
+  readonly env: EnvironmentInfo;
+
+  /** Type-safe context store */
+  readonly store?: PluginStore<TStore>;
+
+  /** Type-safe store value access */
+  getStoreValue<K extends keyof TStore>(key: K): TStore[K];
+  getStoreValue(key: string | number | symbol): any;
+
+  /** Type-safe store value update */
+  setStoreValue<K extends keyof TStore>(key: K, value: TStore[K]): void;
+  setStoreValue(key: string | number | symbol, value: any): void;
+
+  /** Check if a store property exists */
+  hasStoreValue<K extends keyof TStore>(key: K): boolean;
+  hasStoreValue(key: string | number | symbol): boolean;
+}
+
+/**
+ * System path information
+ */
+export interface PathInfo {
+  /** Current working directory */
+  cwd: string;
+
+  /** User home directory */
+  home: string;
+
+  /** Config directory path */
+  config: string;
+}
+
+/**
+ * Environment information
+ */
+export interface EnvironmentInfo {
+  /** Running in CI environment */
+  isCI: boolean;
+
+  /** Additional properties that plugins can add */
+  [key: string]: any;
+}
+
+/**
+ * Middleware function type
+ */
+export type Middleware = (context: CommandContext, next: () => Promise<any>) => Promise<any>;
+
+/**
+ * Plugin extension interfaces
+ *
+ * Note: Plugins should extend these interfaces directly in their own code
+ * rather than using module augmentation, as that creates circular dependencies.
+ */

package/src/tui/registry.ts

@@ -0,0 +1,22 @@
+/**
+ * TUI Registry - manages the global TUI renderer
+ * This module provides a simple registry for TUI renderers
+ */
+
+import type { RenderArgs } from "../types";
+
+let renderer: ((args: RenderArgs<any, any>) => Promise<unknown> | unknown) | null = null;
+
+export function registerTuiRenderer<TFlags = Record<string, unknown>, TStore = {}>(
+  fn: (args: RenderArgs<TFlags, TStore>) => Promise<unknown> | unknown
+) {
+  renderer = fn as (args: RenderArgs<any, any>) => Promise<unknown> | unknown;
+}
+
+export function getTuiRenderer<TFlags = Record<string, unknown>, TStore = {}>() {
+  return renderer as ((args: RenderArgs<TFlags, TStore>) => Promise<unknown> | unknown) | null;
+}
+
+export function clearTuiRenderer() {
+  renderer = null;
+}

package/src/tui/types.ts

@@ -0,0 +1,79 @@
+import type { RenderResult } from "../types";
+
+/**
+ * Options passed to the TUI renderer when rendering a component
+ */
+export interface TuiRendererOptions {
+  /**
+   * Exit on Ctrl+C (default: true)
+   */
+  exitOnCtrlC?: boolean;
+
+  /**
+   * Target frames per second (default: 30)
+   */
+  targetFps?: number;
+
+  /**
+   * Enable mouse movement events (default: true)
+   */
+  enableMouseMovement?: boolean;
+
+  /**
+   * Additional renderer-specific options
+   */
+  [key: string]: unknown;
+}
+
+/**
+ * Context passed when rendering TUI components
+ */
+export interface TuiRenderContext {
+  /**
+   * Renderer-specific options
+   */
+  rendererOptions?: TuiRendererOptions;
+}
+
+/**
+ * TUI Renderer interface
+ * Implementations should handle rendering React components to the terminal
+ */
+export interface TuiRenderer {
+  /**
+   * Render a component result to the terminal
+   * @param component The component or render result to render
+   * @param context Rendering context and options
+   * @returns Promise that resolves when rendering completes
+   */
+  render(component: RenderResult, context: TuiRenderContext): Promise<unknown>;
+}
+
+/**
+ * Global TUI renderer instance
+ * Set by calling registerTuiRenderer()
+ */
+let globalRenderer: TuiRenderer | null = null;
+
+/**
+ * Register a TUI renderer globally
+ * @param renderer The renderer implementation
+ */
+export function registerTuiRenderer(renderer: TuiRenderer): void {
+  globalRenderer = renderer;
+}
+
+/**
+ * Get the currently registered TUI renderer
+ * @returns The registered renderer, or null if none registered
+ */
+export function getTuiRenderer(): TuiRenderer | null {
+  return globalRenderer;
+}
+
+/**
+ * Clear the registered TUI renderer (mainly for testing)
+ */
+export function clearTuiRenderer(): void {
+  globalRenderer = null;
+}

package/src/types.ts

@@ -0,0 +1,285 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { GLOBAL_FLAGS } from "./global-flags";
+
+// Re-export StandardSchemaV1 for use in other modules
+export type { StandardSchemaV1 } from "@standard-schema/spec";
+
+export type RenderResult = unknown;
+
+export interface TuiRenderOptions {
+  exitOnCtrlC?: boolean;
+  targetFps?: number;
+  enableMouseMovement?: boolean;
+  [key: string]: unknown;
+}
+
+export interface RenderArgs<TFlags = Record<string, unknown>, TStore = {}>
+  extends HandlerArgs<TFlags, TStore> {
+  command: Command<any, TStore>;
+  rendererOptions?: TuiRenderOptions;
+}
+
+export type RenderFunction<TFlags = Record<string, unknown>, TStore = {}> = (
+  args: RenderArgs<TFlags, TStore>
+) => RenderResult;
+
+// Core Rempts types
+/**
+ * CLI instance with plugin type information
+ */
+export interface CLI<TStore = {}> {
+  /**
+   * Initialize the CLI (load config, etc)
+   */
+  init(): Promise<void>;
+
+  /**
+   * Run the CLI with given arguments
+   */
+  run(argv?: string[]): Promise<void>;
+
+  /**
+   * Execute a command programmatically
+   */
+  execute(commandName: string, args?: string[]): Promise<void>;
+  execute<T extends keyof RegisteredCommands>(
+    commandName: T,
+    options: CommandOptions<T>
+  ): Promise<void>;
+  execute<T extends keyof RegisteredCommands>(
+    commandName: T,
+    args: string[],
+    options: CommandOptions<T>
+  ): Promise<void>;
+
+  /**
+   * Add a global before hook that runs before command execution
+   * This provides a simple API for setup/initialization tasks
+   */
+  before(hook: BeforeHook<TStore>): void;
+
+  /**
+   * Add a global after hook that runs after command execution
+   */
+  after(hook: AfterHook<TStore>): void;
+}
+
+// generic Command type that carries options type information
+interface BaseCommand<
+  TOptions extends Options = Options,
+  TStore = {},
+  TName extends string = string,
+> {
+  description: string;
+  options?: TOptions;
+  alias?: string | string[];
+  handler?: Handler<InferOptions<TOptions>, TStore, TName>;
+  render?: RenderFunction<InferOptions<TOptions>, TStore>;
+}
+
+export type Command<
+  TOptions extends Options = Options,
+  TStore = {},
+  TName extends string = string,
+> =
+  | (BaseCommand<TOptions, TStore, TName> & {
+      handler: Handler<InferOptions<TOptions>, TStore, TName>;
+    })
+  | (BaseCommand<TOptions, TStore, TName> & {
+      render: RenderFunction<InferOptions<TOptions>, TStore>;
+    })
+  | (BaseCommand<TOptions, TStore, TName> & {
+      handler: Handler<InferOptions<TOptions>, TStore, TName>;
+      render: RenderFunction<InferOptions<TOptions>, TStore>;
+    })
+  | (BaseCommand<TOptions, TStore, TName> & {
+      // Synthetic parent command - no handler/render, subcommands discovered from file structure
+      handler?: never;
+      render?: never;
+    });
+
+// Type helper to extract output types from StandardSchemaV1
+type InferSchema<T> = T extends StandardSchemaV1<any, infer Out> ? Out : never;
+
+export type InferOptions<T extends Options> = {
+  [K in keyof T]: T[K] extends CLIOption<infer S> ? InferSchema<S> : never;
+};
+
+// Type helper to merge global flags with command options
+export type MergedOptions<TOptions extends Options> = typeof GLOBAL_FLAGS & TOptions;
+
+// Type helper to infer types from merged options (global flags + command options)
+export type InferMergedOptions<TOptions extends Options> = InferOptions<MergedOptions<TOptions>>;
+
+// generic Handler type that accepts inferred flags type
+export type Handler<
+  TFlags = Record<string, unknown>,
+  TStore = {},
+  TCommandName extends string = string,
+> = (args: HandlerArgs<TFlags, TStore, TCommandName>) => void | Promise<void>;
+
+// generic HandlerArgs that accepts flags type
+export interface HandlerArgs<
+  TFlags = Record<string, unknown>,
+  TStore = {},
+  TCommandName extends string = string,
+> {
+  // ✨ Automatic type inference from command options ✨
+  flags: TFlags;
+  positional: string[];
+  shell: typeof Bun.$;
+  env: typeof process.env;
+  cwd: string;
+  // Utilities
+  prompt: typeof import("@reliverse/rempts-utils").prompt;
+  spinner: typeof import("@reliverse/rempts-utils").spinner;
+  colors: typeof import("@reliverse/relico").relico;
+  // Plugin context (if plugins are loaded)
+  context?: import("./plugin/types.js").CommandContext<any>;
+  // Data set by global before hooks
+  hooks?: Record<string, any>;
+  // Terminal information
+  terminal: TerminalInfo;
+  // Runtime information
+  runtime: RuntimeInfo;
+}
+
+export interface TerminalInfo {
+  width: number;
+  height: number;
+  isInteractive: boolean;
+  isCI: boolean;
+  supportsColor: boolean;
+  supportsMouse: boolean;
+}
+
+export interface RuntimeInfo {
+  startTime: number;
+  args: string[];
+  command: string;
+}
+
+// CLI option with metadata - generic to preserve schema type
+export interface CLIOption<S extends StandardSchemaV1 = StandardSchemaV1> {
+  schema: S;
+  short?: string;
+  description?: string;
+  default?: unknown; // Default value when flag is not provided (will be validated against schema)
+}
+
+// Options must use the CLIOption wrapper
+export type Options = Record<string, CLIOption<any>>;
+
+// Define command helper with proper type inference
+// Note: 'name' is automatically inferred from file path: <cmds-dir>/<cmd-name>/cmd.{ts,js,mjs}
+export function defineCommand<TOptions extends Options = Options, TStore = {}>(
+  command: Command<TOptions, TStore>
+): Command<TOptions, TStore> {
+  return command;
+}
+
+// Import configuration types from schema
+import type { RemptsConfig } from "./config";
+
+export type { RemptsConfig } from "./config";
+export { remptsConfigSchema } from "./config";
+
+// Plugin configuration type (imported from plugin/types)
+export type PluginConfig = import("./plugin/types.js").PluginConfig;
+
+export type RegisteredCommands = Record<string, Command<any, any, any>>;
+
+/**
+ * Get command options type from registered commands
+ * Uses Standard Schema's InferOutput to extract types from schemas
+ */
+export type CommandOptions<T extends keyof RegisteredCommands> =
+  RegisteredCommands[T] extends Command<infer TOptions, any, any> ? InferOptions<TOptions> : never;
+
+export type CommandFlags<TCommand extends Command<any, any, any>> =
+  TCommand extends Command<infer TOptions, any, any> ? InferOptions<TOptions> : never;
+
+/**
+ * Get all registered command names
+ */
+export type RegisteredCommandNames = keyof RegisteredCommands;
+
+// Resolved config after all plugins have run
+// Codegen is handled internally and not part of the resolved config
+export type ResolvedConfig = Required<
+  Omit<RemptsConfig, "build" | "dev" | "test" | "workspace" | "release">
+> & {
+  build: NonNullable<RemptsConfig["build"]>;
+  dev: NonNullable<RemptsConfig["dev"]>;
+  test: NonNullable<RemptsConfig["test"]>;
+  workspace: NonNullable<RemptsConfig["workspace"]>;
+  release: NonNullable<RemptsConfig["release"]>;
+};
+
+/**
+ * Hook context passed to before/after hooks
+ */
+export interface HookContext<TStore = {}> {
+  /** Global flags parsed from command line */
+  flags: Record<string, unknown>;
+  /** Store from plugins (if any) */
+  store: TStore;
+  /** Environment variables */
+  env: typeof process.env;
+  /** Current working directory */
+  cwd: string;
+  /** Set data that will be available to command handlers */
+  set(key: string, value: any): void;
+  /** Get data that was set by hooks */
+  get(key: string): any;
+}
+
+/**
+ * Before hook function type
+ */
+export type BeforeHook<TStore = {}> = (context: HookContext<TStore>) => void | Promise<void>;
+
+/**
+ * After hook function type
+ */
+export type AfterHook<TStore = {}> = (
+  context: HookContext<TStore> & { exitCode: number; error?: Error }
+) => void | Promise<void>;
+
+/**
+ * Rich validation error with context information
+ */
+export class RemptsValidationError extends Error {
+  constructor(
+    message: string,
+    readonly context: {
+      option: string;
+      value: unknown;
+      command: string;
+      expectedType: string;
+      hint?: string;
+    }
+  ) {
+    super(message);
+    this.name = "RemptsValidationError";
+  }
+
+  override toString(): string {
+    return `${this.name}: Invalid option '${this.context.option}' for command '${this.context.command}'
+    
+Expected: ${this.context.expectedType}
+Received: ${typeof this.context.value} (${JSON.stringify(this.context.value)})
+${this.context.hint ? `\nHint: ${this.context.hint}` : ""}`;
+  }
+}
+
+// Helper to create a CLI option with metadata
+export function option<S extends StandardSchemaV1>(
+  schema: S,
+  metadata?: { short?: string; description?: string; default?: unknown }
+): CLIOption<S> {
+  return {
+    schema,
+    ...metadata,
+  };
+}

package/src/utils/logger.ts

@@ -0,0 +1,43 @@
+/**
+ * Simple logger implementation
+ */
+
+export interface Logger {
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+  debug(message: string, ...args: any[]): void;
+}
+
+export function createLogger(namespace: string): Logger {
+  const prefix = `[${namespace}]`;
+  const debugEnabled =
+    process.env.dler_DEBUG === "true" || process.env.dler_DEBUG?.includes(namespace);
+  const silent = process.env.dler_SILENT === "true" || process.env.NODE_ENV === "test";
+
+  return {
+    info(message: string, ...args: any[]) {
+      if (!silent) {
+        console.log(prefix, message, ...args);
+      }
+    },
+
+    warn(message: string, ...args: any[]) {
+      if (!silent) {
+        console.warn(prefix, message, ...args);
+      }
+    },
+
+    error(message: string, ...args: any[]) {
+      if (!silent) {
+        console.error(prefix, message, ...args);
+      }
+    },
+
+    debug(message: string, ...args: any[]) {
+      if (debugEnabled && !silent) {
+        console.log(`${prefix} [DEBUG]`, message, ...args);
+      }
+    },
+  };
+}

package/src/utils/merge.ts

@@ -0,0 +1,54 @@
+/**
+ * Deep merge utility for configuration objects
+ */
+
+/**
+ * Check if a value is a plain object
+ */
+function isPlainObject(value: any): value is Record<string, any> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    value.constructor === Object &&
+    Object.prototype.toString.call(value) === "[object Object]"
+  );
+}
+
+/**
+ * Deep merge multiple objects
+ * Arrays are concatenated, objects are recursively merged
+ */
+export function deepMerge<T = any>(...objects: Partial<T>[]): T {
+  const result: any = {};
+
+  for (const obj of objects) {
+    if (!obj) {
+      continue;
+    }
+
+    for (const [key, value] of Object.entries(obj)) {
+      const existing = result[key];
+
+      if (Array.isArray(value)) {
+        // Concatenate arrays
+        result[key] = Array.isArray(existing) ? [...existing, ...value] : [...value];
+      } else if (isPlainObject(value)) {
+        // Recursively merge objects
+        result[key] = isPlainObject(existing) ? deepMerge(existing, value) : { ...value };
+      } else {
+        // Primitive values - last one wins
+        result[key] = value;
+      }
+    }
+  }
+
+  return result as T;
+}
+
+/**
+ * Shallow merge multiple objects
+ * Last value wins for all properties
+ */
+export function shallowMerge<T = any>(...objects: Partial<T>[]): T {
+  return Object.assign({}, ...objects) as T;
+}

package/src/utils/mod.ts

@@ -0,0 +1,7 @@
+/**
+ * Utility exports
+ */
+
+export type { Logger } from "./logger";
+export { createLogger } from "./logger";
+export { deepMerge, shallowMerge } from "./merge";