@reliverse/rempts-core 1.6.1 → 2.3.2

package/src/global-flags.ts

@@ -0,0 +1,50 @@
+import { type } from "arktype";
+import type { CLIOption } from "./types";
+
+/**
+ * Built-in global flags available to all commands
+ * Enhanced with better descriptions and validation
+ */
+export const GLOBAL_FLAGS = {
+  interactive: {
+    schema: type("boolean | undefined").configure({
+      description: "enable interactive terminal user interface mode",
+    }),
+    short: "i",
+    description: "Run in interactive TUI mode",
+  },
+  tui: {
+    schema: type("boolean | undefined").configure({
+      description: "force terminal user interface mode",
+    }),
+    description: "Force TUI mode (same as --interactive)",
+  },
+  "no-tui": {
+    schema: type("boolean | undefined").configure({
+      description: "disable terminal user interface mode",
+    }),
+    description: "Disable TUI mode, use CLI handler instead",
+  },
+  help: {
+    schema: type("boolean | undefined").configure({
+      description: "display help information",
+    }),
+    short: "h",
+    description: "Show help",
+  },
+  version: {
+    schema: type("boolean | undefined").configure({
+      description: "display version information",
+    }),
+    short: "v",
+    description: "Show version",
+  },
+} satisfies Record<string, CLIOption>;
+
+export interface GlobalFlags {
+  interactive?: boolean;
+  tui?: boolean;
+  "no-tui"?: boolean;
+  help?: boolean;
+  version?: boolean;
+}

package/src/mod.ts

@@ -0,0 +1,74 @@
+// Note: createCLI is now async and returns Promise<CLI>
+
+export { SchemaError } from "@standard-schema/utils";
+export { createApp, createCLI } from "./cli";
+export { defineConfig, type RemptsConfig, remptsConfigSchema } from "./config";
+export { type LoadedConfig, loadConfig } from "./config-loader";
+export type {
+  CommandConflict,
+  CommandFileInfo,
+  CommandFileTree,
+} from "./file-loader";
+export { createFileCommandLoader, loadCommandsFromDirectory } from "./file-loader";
+export type { GlobalFlags } from "./global-flags";
+// Export global flags
+export { GLOBAL_FLAGS } from "./global-flags";
+// Export TUI registry
+export {
+  clearTuiRenderer,
+  getTuiRenderer,
+  registerTuiRenderer,
+} from "./tui/registry";
+export type {
+  CLI,
+  CLIOption,
+  Command,
+  CommandOptions,
+  Handler,
+  HandlerArgs,
+  Options,
+  PluginConfig,
+  RegisteredCommands,
+  RenderArgs,
+  RenderFunction,
+  RenderResult,
+  ResolvedConfig,
+  RuntimeInfo,
+  TerminalInfo,
+} from "./types";
+export { defineCommand, option } from "./types";
+
+// Note: Plugin system is exported via subpath export
+// Usage: import { PluginManager, createPlugin } from '@reliverse/rempts-core/plugin'
+
+// Export type utilities
+export type {
+  Assign,
+  Constrain,
+  DeepPartial,
+  Expand,
+  ExtractObjects,
+  ExtractPrimitives,
+  IntersectAssign,
+  IsAny,
+  IsNonEmptyObject,
+  IsUnion,
+  MakeDifferenceOptional,
+  MergeAll,
+  MergeAllObjects,
+  NoInfer,
+  PartialMergeAll,
+  PickAsRequired,
+  PickOptional,
+  PickRequired,
+  UnionToIntersection,
+  WithoutEmpty,
+} from "./utils/type-helpers";
+// Export validation utilities
+export {
+  createBatchValidator,
+  createValidator,
+  isValueOfType,
+  validateValue,
+  validateValues,
+} from "./validation";

package/src/parser.ts

@@ -0,0 +1,212 @@
+import type { InferOptions, Options, StandardSchemaV1 } from "./types";
+import { RemptsValidationError } from "./types";
+
+export interface ParsedArgs<TOptions extends Options = Options> {
+  flags: InferOptions<TOptions>;
+  positional: string[];
+}
+
+export async function parseArgs<TOptions extends Options = Options>(
+  args: string[],
+  options: TOptions,
+  commandName = "unknown"
+): Promise<ParsedArgs<TOptions>> {
+  const flags: Record<string, unknown> = {};
+  const positional: string[] = [];
+
+  // Build lookup maps for short aliases
+  const shortToName = new Map<string, string>();
+  for (const [name, opt] of Object.entries(options)) {
+    if (opt.short) {
+      shortToName.set(opt.short, name);
+    }
+  }
+
+  // Parse arguments
+  let stopParsingFlags = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) {
+      continue;
+    }
+
+    // Handle -- separator: everything after is positional
+    if (arg === "--") {
+      stopParsingFlags = true;
+      continue;
+    }
+
+    // After -- separator, treat everything as positional
+    if (stopParsingFlags) {
+      positional.push(arg);
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      // Long flag: --name or --name=value
+      const eqIndex = arg.indexOf("=");
+      const name = eqIndex > 0 ? arg.slice(2, eqIndex) : arg.slice(2);
+      const inlineValue = eqIndex > 0 ? arg.slice(eqIndex + 1) : undefined;
+
+      if (!(name && options[name])) {
+        continue;
+      }
+
+      // Get the value (inline, next arg, or 'true' for boolean-like flags)
+      let value: string | undefined = inlineValue;
+      if (value === undefined && i + 1 < args.length && !args[i + 1]?.startsWith("-")) {
+        value = args[++i];
+      }
+
+      // Pass the value to the schema for validation
+      flags[name] = await validateOption(name, value ?? "true", options[name]?.schema, commandName);
+    } else if (arg.startsWith("-") && arg.length > 1) {
+      // Short flag: -n or -n value
+      const short = arg.slice(1);
+      const name = shortToName.get(short);
+
+      if (name && options[name]) {
+        // Get the next argument as value if available
+        let value: string | undefined;
+        if (i + 1 < args.length && !args[i + 1]?.startsWith("-")) {
+          value = args[++i];
+        }
+
+        flags[name] = await validateOption(
+          name,
+          value ?? "true",
+          options[name]?.schema,
+          commandName
+        );
+      }
+    } else {
+      // Positional argument
+      positional.push(arg);
+    }
+  }
+
+  // Validate all options were provided (schemas handle their own defaults/required logic)
+  // We run validation with undefined for options not provided on command line
+  // If a schema has a default value, it will be used during validation
+  for (const [name, opt] of Object.entries(options)) {
+    if (!(name in flags)) {
+      // Check if the option has an explicit default value
+      if (opt.default !== undefined) {
+        // Validate the default value against the schema
+        const defaultValidated = await validateOption(name, opt.default, opt.schema, commandName);
+        flags[name] = defaultValidated;
+      } else {
+        // No explicit default, validate undefined
+        const validatedValue = await validateOption(name, undefined, opt.schema, commandName);
+
+        // For boolean flags that weren't provided, default to false instead of undefined
+        // This is a common CLI pattern and makes boolean flags more intuitive to use
+        if (validatedValue === undefined) {
+          // Check if the schema accepts boolean values
+          const booleanTest = await opt.schema["~standard"].validate(false);
+          if (booleanTest.issues) {
+            // Schema doesn't accept boolean, keep undefined
+            flags[name] = undefined;
+          } else {
+            // Schema accepts boolean, so default to false
+            flags[name] = false;
+          }
+        } else {
+          // Validation returned a value (could be a default from the schema)
+          flags[name] = validatedValue;
+        }
+      }
+    }
+  }
+
+  // Type assertion: flags are validated at runtime, so we can safely assert the type
+  return { flags: flags as InferOptions<TOptions>, positional };
+}
+
+async function validateOption(
+  name: string,
+  value: unknown,
+  schema: StandardSchemaV1,
+  commandName = "unknown"
+): Promise<unknown> {
+  // Convert string 'true'/'false' to boolean for boolean schemas
+  let processedValue = value;
+  if (typeof value === "string" && (value === "true" || value === "false")) {
+    // Check if the schema expects a boolean by trying to validate true
+    const testResult = await schema["~standard"].validate(true);
+    if (!testResult.issues) {
+      // Schema accepts boolean, convert the string
+      processedValue = value === "true";
+    }
+  }
+
+  // Use Standard Schema validation
+  const result = await schema["~standard"].validate(processedValue);
+
+  if (result.issues && result.issues.length > 0) {
+    const issue = result.issues[0];
+    if (!issue) {
+      return processedValue; // Fallback if no issues
+    }
+
+    const expectedType = extractSchemaType(schema);
+    const hint = generateHint(schema, value);
+
+    throw new RemptsValidationError(`Invalid option '${name}': ${issue.message}`, {
+      option: name,
+      value,
+      command: commandName,
+      expectedType,
+      hint,
+    });
+  }
+
+  return "value" in result ? result.value : processedValue;
+}
+
+/**
+ * Extract a human-readable type description from a schema
+ */
+function extractSchemaType(schema: StandardSchemaV1): string {
+  // Try to infer type from the schema structure
+  if ("type" in schema && typeof schema.type === "string") {
+    return schema.type;
+  }
+
+  // Fallback to checking common patterns
+  if ("enum" in schema) {
+    return "enum";
+  }
+  if ("items" in schema) {
+    return "array";
+  }
+  if ("properties" in schema) {
+    return "object";
+  }
+  if ("format" in schema) {
+    return "string";
+  }
+
+  return "unknown";
+}
+
+/**
+ * Generate a helpful hint based on the schema and value
+ */
+function generateHint(schema: StandardSchemaV1, value: unknown): string {
+  const type = extractSchemaType(schema);
+
+  if (type === "boolean" && typeof value === "string") {
+    return "Use --flag or --no-flag for boolean options";
+  }
+  if (type === "number" && typeof value === "string") {
+    return "Provide a numeric value";
+  }
+  if (type === "array" && !Array.isArray(value)) {
+    return "Provide a comma-separated list of values";
+  }
+  if (type === "enum" && typeof value === "string") {
+    return "Choose from the available options";
+  }
+  return "";
+}

package/src/plugin/context.ts

@@ -0,0 +1,88 @@
+/**
+ * Plugin context implementations - functional approach
+ */
+
+import type { PluginStore } from "./store.js";
+import type { EnvironmentInfo, CommandContext as ICommandContext } from "./types";
+
+/**
+ * Create environment info for contexts
+ */
+export function createEnvironmentInfo(): EnvironmentInfo {
+  const isCI = !!(
+    process.env.CI ||
+    process.env.CONTINUOUS_INTEGRATION ||
+    process.env.GITHUB_ACTIONS ||
+    process.env.GITLAB_CI ||
+    process.env.CIRCLECI ||
+    process.env.TRAVIS
+  );
+
+  return {
+    cwd: process.cwd(),
+    home: require("node:os").homedir(),
+    temp: require("node:os").tmpdir(),
+    platform: process.platform,
+    arch: process.arch,
+    nodeVersion: process.version,
+    isCI,
+    // Initialize plugin-extended properties with defaults
+    isAIAgent: false,
+    aiAgents: [],
+  };
+}
+
+// Plugin context is now created internally in the plugin manager
+// to avoid interface mismatches
+
+/**
+ * Create command context for command execution
+ */
+export function createCommandContext<TStore = {}>(
+  command: string,
+  commandDef: any,
+  args: string[],
+  flags: Record<string, any>,
+  env: EnvironmentInfo,
+  store?: PluginStore<TStore>
+): ICommandContext<TStore> {
+  return {
+    command,
+    commandDef,
+    args,
+    flags,
+    env,
+    store,
+
+    /**
+     * Type-safe store value access
+     * Provides compile-time type checking for store properties
+     */
+    getStoreValue(key: keyof TStore | string | number | symbol): any {
+      if (!store) return undefined;
+      const state = store.getState();
+      return (state as any)[key];
+    },
+
+    /**
+     * Type-safe store value update
+     * Provides compile-time type checking for store property updates
+     */
+    setStoreValue(key: keyof TStore | string | number | symbol, value: any): void {
+      if (!store) return;
+      store.setState((prevState: TStore) => ({
+        ...prevState,
+        [key]: value,
+      }));
+    },
+
+    /**
+     * Check if a store property exists
+     */
+    hasStoreValue(key: keyof TStore | string | number | symbol): boolean {
+      if (!store) return false;
+      const state = store.getState();
+      return key in (state as object);
+    },
+  };
+}

package/src/plugin/create.ts

@@ -0,0 +1,174 @@
+/**
+ * Plugin development utilities
+ */
+
+import { createPluginStore, type PluginStore } from "./store.js";
+import type { Plugin, PluginFactory, PluginHooks } from "./types";
+
+/**
+ * Create a plugin - supports both direct plugins and plugin factories
+ *
+ * @example Direct plugin with explicit store type:
+ * ```typescript
+ * interface MyStore {
+ *   count: number
+ *   message: string
+ * }
+ *
+ * const myPlugin = createPlugin<MyStore>({
+ *   name: 'my-plugin',
+ *   store: {
+ *     count: 0,
+ *     message: ''
+ *   },
+ *   beforeCommand(context) {
+ *     context.store.count++ // TypeScript knows the type!
+ *   }
+ * })
+ * ```
+ *
+ * @example Plugin factory with options:
+ * ```typescript
+ * const myPlugin = createPlugin((options: { prefix: string }) => ({
+ *   name: 'my-plugin',
+ *   store: {
+ *     count: 0
+ *   },
+ *   beforeCommand(context) {
+ *     console.log(`${options.prefix}: ${context.store.count}`)
+ *   }
+ * } satisfies PluginHooks<{ count: number }>))
+ *
+ * // Use it:
+ * myPlugin({ prefix: 'Hello' })
+ * ```
+ */
+// Overload for direct plugin
+export function createPlugin<TStore = {}>(plugin: Plugin<TStore>): Plugin<TStore>;
+
+export function createPlugin<TOptions, TStore = {}>(
+  factory: (options: TOptions) => Plugin<TStore>
+): (options: TOptions) => Plugin<TStore>;
+
+export function createPlugin<T>(input: T): T {
+  return input;
+}
+
+/**
+ * Infer plugin options type from a plugin factory
+ *
+ * @example
+ * ```typescript
+ * type Options = InferPluginOptions<typeof myPlugin>
+ * ```
+ */
+export type InferPluginOptions<T> = T extends PluginFactory<infer O, any> ? O : never;
+
+/**
+ * Infer plugin store type
+ *
+ * @example
+ * ```typescript
+ * type Store = InferPluginStore<typeof myPlugin>
+ * ```
+ */
+export type InferPluginStore<T> =
+  T extends Plugin<infer S> ? S : T extends PluginFactory<any, infer S> ? S : {};
+
+/**
+ * Create a test plugin for development and testing
+ *
+ * @example
+ * ```typescript
+ * const testPlugin = createTestPlugin(
+ *   { count: 0, message: '' },
+ *   {
+ *     beforeCommand(context) {
+ *       context.store.count++
+ *       console.log(`Count: ${context.store.count}`)
+ *     }
+ *   }
+ * )
+ * ```
+ */
+export function createTestPlugin<TStore = {}>(
+  initialState: TStore,
+  hooks: Partial<PluginHooks<TStore>>
+): Plugin<TStore> {
+  return () => ({
+    store: createPluginStore(initialState),
+    ...hooks,
+  });
+}
+
+/**
+ * Compose multiple plugins into a single plugin
+ *
+ * @example
+ * ```typescript
+ * const composedPlugin = composePlugins(
+ *   authPlugin({ provider: 'github' }),
+ *   loggingPlugin({ level: 'debug' }),
+ *   metricsPlugin({ enabled: true })
+ * )
+ * ```
+ */
+export function composePlugins<T extends Plugin[]>(...plugins: T): Plugin {
+  return () => {
+    const hooksArray = plugins.map((plugin) => plugin());
+
+    // Collect all stores from plugins
+    const stores: Record<string, PluginStore<any>> = {};
+    hooksArray.forEach((hooks, index) => {
+      if (hooks.store) {
+        stores[`plugin_${index}`] = hooks.store;
+      }
+    });
+
+    // Create combined store if there are any stores
+    const composedStore =
+      Object.keys(stores).length > 0
+        ? createPluginStore(
+            Object.keys(stores).reduce((acc, key) => {
+              const store = stores[key];
+              if (store) {
+                acc[key] = store.getState();
+              }
+              return acc;
+            }, {} as any)
+          )
+        : undefined;
+
+    return {
+      store: composedStore,
+      async setup(context) {
+        for (const hooks of hooksArray) {
+          if (hooks.setup) {
+            await hooks.setup(context);
+          }
+        }
+      },
+      async configResolved(config) {
+        for (const hooks of hooksArray) {
+          if (hooks.configResolved) {
+            await hooks.configResolved(config);
+          }
+        }
+      },
+      async beforeCommand(context) {
+        for (const hooks of hooksArray) {
+          if (hooks.beforeCommand) {
+            await hooks.beforeCommand(context);
+          }
+        }
+      },
+      async afterCommand(context) {
+        for (const hooks of hooksArray) {
+          if (hooks.afterCommand) {
+            await hooks.afterCommand(context);
+          }
+        }
+      },
+    };
+  };
+}

package/src/plugin/loader.ts

@@ -0,0 +1,111 @@
+/**
+ * Plugin loader implementation - functional approach
+ */
+
+import { join } from "node:path";
+import type { Plugin, PluginConfig } from "./types";
+
+export interface PluginLoader {
+  loadPlugin(config: PluginConfig): Promise<Plugin>;
+  validatePlugin(plugin: Plugin): void;
+}
+
+/**
+ * Check if a value is a valid plugin function
+ */
+function isPluginFunction(obj: any): obj is Plugin {
+  return obj && typeof obj === "function";
+}
+
+/**
+ * Load plugin from file path
+ */
+async function loadFromPath(path: string): Promise<Plugin> {
+  try {
+    // Handle both absolute and relative paths
+    const resolvedPath = path.startsWith(".") ? join(process.cwd(), path) : path;
+
+    // Dynamic import
+    const module = await import(resolvedPath);
+
+    // Handle various export styles
+    const plugin = module.default || module.plugin || module;
+
+    // If it's a factory function, call it without options
+    if (typeof plugin === "function" && !isPluginFunction(plugin)) {
+      return plugin();
+    }
+
+    // Validate it's a plugin function
+    if (!isPluginFunction(plugin)) {
+      throw new Error("Module does not export a valid plugin");
+    }
+
+    return plugin;
+  } catch (error: any) {
+    throw new Error(`Failed to load plugin from ${path}: ${error.message}`);
+  }
+}
+
+/**
+ * Create a plugin loader
+ */
+export function createPluginLoader(): PluginLoader {
+  return {
+    /**
+     * Load a plugin from various configuration formats
+     */
+    async loadPlugin(config: PluginConfig): Promise<Plugin> {
+      // String path - dynamic import
+      if (typeof config === "string") {
+        return loadFromPath(config);
+      }
+
+      // Plugin function - use directly
+      if (isPluginFunction(config)) {
+        return config;
+      }
+
+      // Function - call it (legacy factory support)
+      if (typeof config === "function") {
+        return config();
+      }
+
+      // Array - function with options
+      if (Array.isArray(config) && config.length === 2) {
+        const [factory, options] = config;
+        if (typeof factory === "function") {
+          return factory(options);
+        }
+      }
+
+      throw new Error(`Invalid plugin configuration: ${JSON.stringify(config)}`);
+    },
+
+    /**
+     * Validate loaded plugin
+     */
+    validatePlugin(plugin: Plugin): void {
+      // Validate that it's a function
+      if (typeof plugin !== "function") {
+        throw new Error("Plugin must be a function");
+      }
+
+      // Call the plugin to get hooks and validate them
+      try {
+        const hooks = plugin();
+
+        // Check hook types
+        const hookNames = ["setup", "configResolved", "beforeCommand", "afterCommand"];
+        for (const hook of hookNames) {
+          const value = hooks[hook as keyof typeof hooks];
+          if (value !== undefined && typeof value !== "function") {
+            throw new Error(`Plugin hook ${hook} must be a function`);
+          }
+        }
+      } catch (error: any) {
+        throw new Error(`Plugin validation failed: ${error.message}`);
+      }
+    },
+  };
+}