@reliverse/rempts-core 1.6.1 → 2.3.2

package/dist/mod.js

@@ -0,0 +1,19 @@
+export { SchemaError } from "@standard-schema/utils";
+export { createApp, createCLI } from "./cli.js";
+export { defineConfig, remptsConfigSchema } from "./config.js";
+export { loadConfig } from "./config-loader.js";
+export { createFileCommandLoader, loadCommandsFromDirectory } from "./file-loader.js";
+export { GLOBAL_FLAGS } from "./global-flags.js";
+export {
+  clearTuiRenderer,
+  getTuiRenderer,
+  registerTuiRenderer
+} from "./tui/registry.js";
+export { defineCommand, option } from "./types.js";
+export {
+  createBatchValidator,
+  createValidator,
+  isValueOfType,
+  validateValue,
+  validateValues
+} from "./validation.js";

package/dist/parser.d.ts

@@ -0,0 +1,6 @@
+import type { InferOptions, Options } from "./types.js";
+export interface ParsedArgs<TOptions extends Options = Options> {
+    flags: InferOptions<TOptions>;
+    positional: string[];
+}
+export declare function parseArgs<TOptions extends Options = Options>(args: string[], options: TOptions, commandName?: string): Promise<ParsedArgs<TOptions>>;

package/dist/parser.js

@@ -0,0 +1,137 @@
+import { RemptsValidationError } from "./types.js";
+export async function parseArgs(args, options, commandName = "unknown") {
+  const flags = {};
+  const positional = [];
+  const shortToName = /* @__PURE__ */ new Map();
+  for (const [name, opt] of Object.entries(options)) {
+    if (opt.short) {
+      shortToName.set(opt.short, name);
+    }
+  }
+  let stopParsingFlags = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "--") {
+      stopParsingFlags = true;
+      continue;
+    }
+    if (stopParsingFlags) {
+      positional.push(arg);
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const eqIndex = arg.indexOf("=");
+      const name = eqIndex > 0 ? arg.slice(2, eqIndex) : arg.slice(2);
+      const inlineValue = eqIndex > 0 ? arg.slice(eqIndex + 1) : void 0;
+      if (!(name && options[name])) {
+        continue;
+      }
+      let value = inlineValue;
+      if (value === void 0 && i + 1 < args.length && !args[i + 1]?.startsWith("-")) {
+        value = args[++i];
+      }
+      flags[name] = await validateOption(name, value ?? "true", options[name]?.schema, commandName);
+    } else if (arg.startsWith("-") && arg.length > 1) {
+      const short = arg.slice(1);
+      const name = shortToName.get(short);
+      if (name && options[name]) {
+        let value;
+        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.push(arg);
+    }
+  }
+  for (const [name, opt] of Object.entries(options)) {
+    if (!(name in flags)) {
+      if (opt.default !== void 0) {
+        const defaultValidated = await validateOption(name, opt.default, opt.schema, commandName);
+        flags[name] = defaultValidated;
+      } else {
+        const validatedValue = await validateOption(name, void 0, opt.schema, commandName);
+        if (validatedValue === void 0) {
+          const booleanTest = await opt.schema["~standard"].validate(false);
+          if (booleanTest.issues) {
+            flags[name] = void 0;
+          } else {
+            flags[name] = false;
+          }
+        } else {
+          flags[name] = validatedValue;
+        }
+      }
+    }
+  }
+  return { flags, positional };
+}
+async function validateOption(name, value, schema, commandName = "unknown") {
+  let processedValue = value;
+  if (typeof value === "string" && (value === "true" || value === "false")) {
+    const testResult = await schema["~standard"].validate(true);
+    if (!testResult.issues) {
+      processedValue = value === "true";
+    }
+  }
+  const result = await schema["~standard"].validate(processedValue);
+  if (result.issues && result.issues.length > 0) {
+    const issue = result.issues[0];
+    if (!issue) {
+      return processedValue;
+    }
+    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;
+}
+function extractSchemaType(schema) {
+  if ("type" in schema && typeof schema.type === "string") {
+    return schema.type;
+  }
+  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";
+}
+function generateHint(schema, value) {
+  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/dist/plugin/context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Plugin context implementations - functional approach
+ */
+import type { PluginStore } from "./store.js.js";
+import type { EnvironmentInfo, CommandContext as ICommandContext } from "./types.js";
+/**
+ * Create environment info for contexts
+ */
+export declare function createEnvironmentInfo(): EnvironmentInfo;
+/**
+ * Create command context for command execution
+ */
+export declare function createCommandContext<TStore = {}>(command: string, commandDef: any, args: string[], flags: Record<string, any>, env: EnvironmentInfo, store?: PluginStore<TStore>): ICommandContext<TStore>;

package/dist/plugin/context.js

@@ -0,0 +1,53 @@
+export function createEnvironmentInfo() {
+  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: []
+  };
+}
+export function createCommandContext(command, commandDef, args, flags, env, store) {
+  return {
+    command,
+    commandDef,
+    args,
+    flags,
+    env,
+    store,
+    /**
+     * Type-safe store value access
+     * Provides compile-time type checking for store properties
+     */
+    getStoreValue(key) {
+      if (!store) return void 0;
+      const state = store.getState();
+      return state[key];
+    },
+    /**
+     * Type-safe store value update
+     * Provides compile-time type checking for store property updates
+     */
+    setStoreValue(key, value) {
+      if (!store) return;
+      store.setState((prevState) => ({
+        ...prevState,
+        [key]: value
+      }));
+    },
+    /**
+     * Check if a store property exists
+     */
+    hasStoreValue(key) {
+      if (!store) return false;
+      const state = store.getState();
+      return key in state;
+    }
+  };
+}

package/dist/plugin/create.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Plugin development utilities
+ */
+import type { Plugin, PluginFactory, PluginHooks } from "./types.js";
+/**
+ * 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' })
+ * ```
+ */
+export declare function createPlugin<TStore = {}>(plugin: Plugin<TStore>): Plugin<TStore>;
+export declare function createPlugin<TOptions, TStore = {}>(factory: (options: TOptions) => Plugin<TStore>): (options: TOptions) => Plugin<TStore>;
+/**
+ * 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 declare function createTestPlugin<TStore = {}>(initialState: TStore, hooks: Partial<PluginHooks<TStore>>): Plugin<TStore>;
+/**
+ * Compose multiple plugins into a single plugin
+ *
+ * @example
+ * ```typescript
+ * const composedPlugin = composePlugins(
+ *   authPlugin({ provider: 'github' }),
+ *   loggingPlugin({ level: 'debug' }),
+ *   metricsPlugin({ enabled: true })
+ * )
+ * ```
+ */
+export declare function composePlugins<T extends Plugin[]>(...plugins: T): Plugin;

package/dist/plugin/create.js

@@ -0,0 +1,61 @@
+import { createPluginStore } from "./store.js";
+export function createPlugin(input) {
+  return input;
+}
+export function createTestPlugin(initialState, hooks) {
+  return () => ({
+    store: createPluginStore(initialState),
+    ...hooks
+  });
+}
+export function composePlugins(...plugins) {
+  return () => {
+    const hooksArray = plugins.map((plugin) => plugin());
+    const stores = {};
+    hooksArray.forEach((hooks, index) => {
+      if (hooks.store) {
+        stores[`plugin_${index}`] = hooks.store;
+      }
+    });
+    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;
+      }, {})
+    ) : void 0;
+    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/dist/plugin/loader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Plugin loader implementation - functional approach
+ */
+import type { Plugin, PluginConfig } from "./types.js";
+export interface PluginLoader {
+    loadPlugin(config: PluginConfig): Promise<Plugin>;
+    validatePlugin(plugin: Plugin): void;
+}
+/**
+ * Create a plugin loader
+ */
+export declare function createPluginLoader(): PluginLoader;

package/dist/plugin/loader.js

@@ -0,0 +1,65 @@
+import { join } from "node:path";
+function isPluginFunction(obj) {
+  return obj && typeof obj === "function";
+}
+async function loadFromPath(path) {
+  try {
+    const resolvedPath = path.startsWith(".") ? join(process.cwd(), path) : path;
+    const module = await import(resolvedPath);
+    const plugin = module.default || module.plugin || module;
+    if (typeof plugin === "function" && !isPluginFunction(plugin)) {
+      return plugin();
+    }
+    if (!isPluginFunction(plugin)) {
+      throw new Error("Module does not export a valid plugin");
+    }
+    return plugin;
+  } catch (error) {
+    throw new Error(`Failed to load plugin from ${path}: ${error.message}`);
+  }
+}
+export function createPluginLoader() {
+  return {
+    /**
+     * Load a plugin from various configuration formats
+     */
+    async loadPlugin(config) {
+      if (typeof config === "string") {
+        return loadFromPath(config);
+      }
+      if (isPluginFunction(config)) {
+        return config;
+      }
+      if (typeof config === "function") {
+        return config();
+      }
+      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) {
+      if (typeof plugin !== "function") {
+        throw new Error("Plugin must be a function");
+      }
+      try {
+        const hooks = plugin();
+        const hookNames = ["setup", "configResolved", "beforeCommand", "afterCommand"];
+        for (const hook of hookNames) {
+          const value = hooks[hook];
+          if (value !== void 0 && typeof value !== "function") {
+            throw new Error(`Plugin hook ${hook} must be a function`);
+          }
+        }
+      } catch (error) {
+        throw new Error(`Plugin validation failed: ${error.message}`);
+      }
+    }
+  };
+}

package/dist/plugin/manager.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Plugin lifecycle manager - functional implementation
+ */
+import type { RemptsConfig, ResolvedConfig } from "../types.js";
+import { createLogger } from "../utils/logger.js";
+import { createCommandContext } from "./context.js";
+import { createPluginLoader } from "./loader.js";
+import { type PluginStore } from "./store.js.js";
+import type { CommandDefinition, CommandResult, Middleware, Plugin, PluginConfig, PluginHooks } from "./types.js";
+export interface PluginSetupResult {
+    config: Partial<RemptsConfig>;
+    commands: CommandDefinition[];
+    middlewares: Middleware[];
+}
+export interface PluginManagerState<TStore = {}> {
+    plugins: Plugin[];
+    pluginHooks: PluginHooks[];
+    combinedStore?: PluginStore<TStore>;
+    loader: ReturnType<typeof createPluginLoader>;
+    logger: ReturnType<typeof createLogger>;
+}
+/**
+ * Create a new plugin manager state
+ */
+export declare function createPluginManager<TStore = {}>(): PluginManagerState<TStore>;
+/**
+ * Load and validate plugins
+ */
+export declare function loadPlugins<TStore>(state: PluginManagerState<TStore>, configs: PluginConfig[]): Promise<void>;
+/**
+ * Run setup hooks for all plugins
+ */
+export declare function runSetup<TStore>(state: PluginManagerState<TStore>, config: Partial<RemptsConfig>): Promise<PluginSetupResult>;
+/**
+ * Run configResolved hooks
+ */
+export declare function runConfigResolved<TStore>(state: PluginManagerState<TStore>, config: ResolvedConfig): Promise<void>;
+/**
+ * Run beforeCommand hooks
+ */
+export declare function runBeforeCommand<TStore>(state: PluginManagerState<TStore>, command: string, commandDef: any, args: string[], flags: Record<string, any>): Promise<ReturnType<typeof createCommandContext<TStore>>>;
+/**
+ * Run afterCommand hooks
+ */
+export declare function runAfterCommand<TStore>(state: PluginManagerState<TStore>, context: ReturnType<typeof createCommandContext<TStore>>, result: CommandResult): Promise<void>;
+/**
+ * Get loaded plugins (for debugging/listing)
+ */
+export declare function getPlugins<TStore>(state: PluginManagerState<TStore>): readonly Plugin[];
+/**
+ * Get plugin hooks by index
+ */
+export declare function getPlugin<TStore>(state: PluginManagerState<TStore>, index: number): PluginHooks | undefined;

package/dist/plugin/manager.js

@@ -0,0 +1,135 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createLogger } from "../utils/logger.js";
+import { deepMerge } from "../utils/merge.js";
+import { createCommandContext, createEnvironmentInfo } from "./context.js";
+import { createPluginLoader } from "./loader.js";
+import { combinePluginStores } from "./store.js";
+export function createPluginManager() {
+  return {
+    plugins: [],
+    pluginHooks: [],
+    combinedStore: void 0,
+    loader: createPluginLoader(),
+    logger: createLogger("plugin-manager")
+  };
+}
+export async function loadPlugins(state, configs) {
+  const loadPromises = configs.map(async (config) => {
+    try {
+      const plugin = await state.loader.loadPlugin(config);
+      state.loader.validatePlugin(plugin);
+      return plugin;
+    } catch (error) {
+      state.logger.error(`Failed to load plugin: ${error.message}`);
+      throw error;
+    }
+  });
+  state.plugins = await Promise.all(loadPromises);
+  state.pluginHooks = state.plugins.map((plugin) => plugin());
+  const stores = {};
+  state.pluginHooks.forEach((hooks, index) => {
+    if (hooks.store) {
+      stores[`plugin_${index}`] = hooks.store;
+    }
+  });
+  if (Object.keys(stores).length > 0) {
+    state.combinedStore = combinePluginStores(stores);
+  }
+  state.logger.info(`Loaded ${state.plugins.length} plugins`);
+}
+export async function runSetup(state, config) {
+  const setupState = {
+    configUpdates: [],
+    commands: [],
+    middlewares: []
+  };
+  const context = {
+    config,
+    store: state.combinedStore,
+    logger: createLogger("plugins"),
+    paths: {
+      cwd: process.cwd(),
+      home: homedir(),
+      config: join(homedir(), ".config", config.name || "rempts")
+    },
+    updateConfig(partial) {
+      setupState.configUpdates.push(partial);
+    },
+    registerCommand(command) {
+      setupState.commands.push(command);
+    },
+    use(middleware) {
+      setupState.middlewares.push(middleware);
+    }
+  };
+  for (const hooks of state.pluginHooks) {
+    if (hooks.setup) {
+      state.logger.debug(`Running setup for plugin`);
+      try {
+        await hooks.setup(context);
+      } catch (error) {
+        throw new Error(`Plugin setup failed: ${error.message}`);
+      }
+    }
+  }
+  const mergedConfig = setupState.configUpdates.length > 0 ? deepMerge(config, ...setupState.configUpdates) : config;
+  return {
+    config: mergedConfig,
+    commands: setupState.commands,
+    middlewares: setupState.middlewares
+  };
+}
+export async function runConfigResolved(state, config) {
+  for (const hooks of state.pluginHooks) {
+    if (hooks.configResolved) {
+      state.logger.debug(`Running configResolved for plugin`);
+      try {
+        await hooks.configResolved(config);
+      } catch (error) {
+        state.logger.error(`Plugin configResolved error: ${error.message}`);
+      }
+    }
+  }
+}
+export async function runBeforeCommand(state, command, commandDef, args, flags) {
+  const commandStore = state.combinedStore;
+  const context = createCommandContext(
+    command,
+    commandDef,
+    args,
+    flags,
+    createEnvironmentInfo(),
+    commandStore
+  );
+  for (const hooks of state.pluginHooks) {
+    if (hooks.beforeCommand) {
+      state.logger.debug(`Running beforeCommand for plugin`);
+      try {
+        await hooks.beforeCommand(context);
+      } catch (error) {
+        throw new Error(`Plugin beforeCommand failed: ${error.message}`);
+      }
+    }
+  }
+  return context;
+}
+export async function runAfterCommand(state, context, result) {
+  const fullContext = Object.assign(context, result);
+  for (const hooks of state.pluginHooks) {
+    if (hooks.afterCommand) {
+      state.logger.debug(`Running afterCommand for plugin`);
+      try {
+        await hooks.afterCommand(fullContext);
+      } catch (error) {
+        state.logger.error(`Plugin afterCommand error: ${error.message}`);
+      }
+    }
+  }
+}
+export function getPlugins(state) {
+  return state.plugins;
+}
+export function getPlugin(state, index) {
+  return state.pluginHooks[index];
+}

package/dist/plugin/mod.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Plugin system public API
+ */
+export { createCommandContext, createEnvironmentInfo, } from "./context.js";
+export { composePlugins, createPlugin, createTestPlugin } from "./create.js";
+export { createPluginManager, getPlugin, getPlugins, loadPlugins, runAfterCommand, runBeforeCommand, runConfigResolved, runSetup, } from "./manager.js";
+export { combinePluginStores, createPluginStore, createPluginStoreWithLogging, type PluginStore, type PluginStoreState, } from "./store.js";
+export { assertPluginBehavior, createMockCommandContext, createMockPluginContext, testPluginHooks, } from "./testing.js";
+export type { CommandContext as ICommandContext, CommandResult, EnvironmentInfo, MergePluginStores, MergeStores, Middleware, PathInfo, Plugin, PluginConfig, PluginContext as IPluginContext, PluginFactory, PluginHooks, } from "./types.js";
+export * from "./types.js";

package/dist/plugin/mod.js

@@ -0,0 +1,27 @@
+export {
+  createCommandContext,
+  createEnvironmentInfo
+} from "./context.js";
+export { composePlugins, createPlugin, createTestPlugin } from "./create.js";
+export {
+  createPluginManager,
+  getPlugin,
+  getPlugins,
+  loadPlugins,
+  runAfterCommand,
+  runBeforeCommand,
+  runConfigResolved,
+  runSetup
+} from "./manager.js";
+export {
+  combinePluginStores,
+  createPluginStore,
+  createPluginStoreWithLogging
+} from "./store.js";
+export {
+  assertPluginBehavior,
+  createMockCommandContext,
+  createMockPluginContext,
+  testPluginHooks
+} from "./testing.js";
+export * from "./types.js";