@reliverse/rempts-core 1.6.1 → 2.3.2

package/src/plugin/manager.ts

@@ -0,0 +1,244 @@
+/**
+ * Plugin lifecycle manager - functional implementation
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { RemptsConfig, ResolvedConfig } from "../types";
+import { createLogger } from "../utils/logger";
+import { deepMerge } from "../utils/merge";
+import { createCommandContext, createEnvironmentInfo } from "./context";
+import { createPluginLoader } from "./loader";
+import { combinePluginStores, type PluginStore } from "./store.js";
+import type {
+  CommandDefinition,
+  CommandResult,
+  Middleware,
+  Plugin,
+  PluginConfig,
+  PluginHooks,
+} from "./types";
+
+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 function createPluginManager<TStore = {}>(): PluginManagerState<TStore> {
+  return {
+    plugins: [],
+    pluginHooks: [],
+    combinedStore: undefined,
+    loader: createPluginLoader(),
+    logger: createLogger("plugin-manager"),
+  };
+}
+
+/**
+ * Load and validate plugins
+ */
+export async function loadPlugins<TStore>(
+  state: PluginManagerState<TStore>,
+  configs: PluginConfig[]
+): Promise<void> {
+  // Load all plugins
+  const loadPromises = configs.map(async (config) => {
+    try {
+      const plugin = await state.loader.loadPlugin(config);
+      state.loader.validatePlugin(plugin);
+      return plugin;
+    } catch (error: any) {
+      state.logger.error(`Failed to load plugin: ${error.message}`);
+      throw error;
+    }
+  });
+
+  state.plugins = await Promise.all(loadPromises);
+
+  // Instantiate hooks for all plugins
+  state.pluginHooks = state.plugins.map((plugin) => plugin());
+
+  // Combine all plugin stores using Zustand
+  const stores: Record<string, PluginStore<any>> = {};
+  state.pluginHooks.forEach((hooks, index) => {
+    if (hooks.store) {
+      stores[`plugin_${index}`] = hooks.store;
+    }
+  });
+
+  if (Object.keys(stores).length > 0) {
+    state.combinedStore = combinePluginStores(stores) as any;
+  }
+
+  state.logger.info(`Loaded ${state.plugins.length} plugins`);
+}
+
+/**
+ * Run setup hooks for all plugins
+ */
+export async function runSetup<TStore>(
+  state: PluginManagerState<TStore>,
+  config: Partial<RemptsConfig>
+): Promise<PluginSetupResult> {
+  // Create a stateful context that can collect results
+  const setupState = {
+    configUpdates: [] as Partial<RemptsConfig>[],
+    commands: [] as CommandDefinition[],
+    middlewares: [] as Middleware[],
+  };
+
+  const context = {
+    config,
+    store: state.combinedStore,
+    logger: createLogger("plugins"),
+    paths: {
+      cwd: process.cwd(),
+      home: homedir(),
+      config: join(homedir(), ".config", config.name || "rempts"),
+    },
+
+    updateConfig(partial: Partial<RemptsConfig>): void {
+      setupState.configUpdates.push(partial);
+    },
+
+    registerCommand(command: CommandDefinition): void {
+      setupState.commands.push(command);
+    },
+
+    use(middleware: Middleware): void {
+      setupState.middlewares.push(middleware);
+    },
+  };
+
+  // Run all setup hooks
+  for (const hooks of state.pluginHooks) {
+    if (hooks.setup) {
+      state.logger.debug(`Running setup for plugin`);
+      try {
+        await hooks.setup(context as any);
+      } catch (error: any) {
+        throw new Error(`Plugin setup failed: ${error.message}`);
+      }
+    }
+  }
+
+  // Merge all config updates
+  const mergedConfig =
+    setupState.configUpdates.length > 0 ? deepMerge(config, ...setupState.configUpdates) : config;
+
+  return {
+    config: mergedConfig,
+    commands: setupState.commands,
+    middlewares: setupState.middlewares,
+  };
+}
+
+/**
+ * Run configResolved hooks
+ */
+export async function runConfigResolved<TStore>(
+  state: PluginManagerState<TStore>,
+  config: ResolvedConfig
+): Promise<void> {
+  for (const hooks of state.pluginHooks) {
+    if (hooks.configResolved) {
+      state.logger.debug(`Running configResolved for plugin`);
+      try {
+        await hooks.configResolved(config);
+      } catch (error: any) {
+        // Log but don't fail - config is already resolved
+        state.logger.error(`Plugin configResolved error: ${error.message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Run beforeCommand hooks
+ */
+export async function runBeforeCommand<TStore>(
+  state: PluginManagerState<TStore>,
+  command: string,
+  commandDef: any,
+  args: string[],
+  flags: Record<string, any>
+): Promise<ReturnType<typeof createCommandContext<TStore>>> {
+  // Use the combined store directly (Zustand handles immutability)
+  const commandStore = state.combinedStore;
+
+  const context = createCommandContext<TStore>(
+    command,
+    commandDef,
+    args,
+    flags,
+    createEnvironmentInfo(),
+    commandStore as any
+  );
+
+  // Run all beforeCommand hooks
+  for (const hooks of state.pluginHooks) {
+    if (hooks.beforeCommand) {
+      state.logger.debug(`Running beforeCommand for plugin`);
+      try {
+        await hooks.beforeCommand(context as any);
+      } catch (error: any) {
+        throw new Error(`Plugin beforeCommand failed: ${error.message}`);
+      }
+    }
+  }
+
+  return context;
+}
+
+/**
+ * Run afterCommand hooks
+ */
+export async function runAfterCommand<TStore>(
+  state: PluginManagerState<TStore>,
+  context: ReturnType<typeof createCommandContext<TStore>>,
+  result: CommandResult
+): Promise<void> {
+  const fullContext = Object.assign(context, result);
+
+  // Run all afterCommand hooks
+  for (const hooks of state.pluginHooks) {
+    if (hooks.afterCommand) {
+      state.logger.debug(`Running afterCommand for plugin`);
+      try {
+        await hooks.afterCommand(fullContext as any);
+      } catch (error: any) {
+        // Log error but don't fail - command already executed
+        state.logger.error(`Plugin afterCommand error: ${error.message}`);
+      }
+    }
+  }
+}
+
+/**
+ * Get loaded plugins (for debugging/listing)
+ */
+export function getPlugins<TStore>(state: PluginManagerState<TStore>): readonly Plugin[] {
+  return state.plugins;
+}
+
+/**
+ * Get plugin hooks by index
+ */
+export function getPlugin<TStore>(
+  state: PluginManagerState<TStore>,
+  index: number
+): PluginHooks | undefined {
+  return state.pluginHooks[index];
+}

package/src/plugin/mod.ts

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

package/src/plugin/store.ts

@@ -0,0 +1,124 @@
+/**
+ * Zustand store utilities for Rempts plugin system
+ */
+
+import { createStore, type StoreApi } from "zustand";
+
+/**
+ * Generic Zustand store interface for plugins
+ */
+export interface PluginStore<TState = any> extends StoreApi<TState> {
+  /**
+   * Get the current state
+   */
+  getState(): TState;
+
+  /**
+   * Subscribe to state changes
+   */
+  subscribe(listener: (state: TState, prevState: TState) => void): () => void;
+
+  /**
+   * Set new state
+   */
+  setState(updater: TState | ((prevState: TState) => TState)): void;
+
+  /**
+   * Destroy the store
+   */
+  destroy(): void;
+}
+
+/**
+ * Create a Zustand store for a plugin
+ */
+export function createPluginStore<TState>(initialState: TState): PluginStore<TState> {
+  const store = createStore<TState>()(() => initialState);
+
+  return {
+    ...store,
+    destroy: () => {
+      // Zustand stores don't have a built-in destroy method
+      // but we provide this for consistency
+    },
+  };
+}
+
+/**
+ * Combine multiple plugin stores into a single store
+ */
+export function combinePluginStores<TCombined>(
+  stores: Record<string, PluginStore<any>>
+): PluginStore<TCombined> {
+  // Create initial combined state
+  const initialState = Object.keys(stores).reduce((acc, key) => {
+    const store = stores[key];
+    if (store) {
+      acc[key] = store.getState();
+    }
+    return acc;
+  }, {} as any);
+
+  const combinedStore = createStore<TCombined>()(() => initialState);
+
+  // Subscribe to all individual stores and update combined store
+  const unsubscribers = Object.keys(stores).map((key) => {
+    const store = stores[key];
+    if (store) {
+      return store.subscribe((state) => {
+        combinedStore.setState((prevState: TCombined) => ({
+          ...prevState,
+          [key]: state,
+        }));
+      });
+    }
+    return () => {}; // Return empty unsubscribe function if store is undefined
+  });
+
+  return {
+    ...combinedStore,
+    destroy: () => {
+      unsubscribers.forEach((unsubscribe) => unsubscribe());
+    },
+  };
+}
+
+/**
+ * Type helper for plugin store state
+ */
+export type PluginStoreState<TStore extends PluginStore<any>> = ReturnType<TStore["getState"]>;
+
+/**
+ * Middleware for logging store changes (useful for debugging)
+ */
+export function createLoggingMiddleware<TState>() {
+  return (config: any) => (set: any, get: any, api: any) =>
+    config(
+      (...args: any[]) => {
+        console.log("Store before:", get());
+        set(...args);
+        console.log("Store after:", get());
+      },
+      get,
+      api
+    );
+}
+
+/**
+ * Create a store with logging enabled
+ */
+export function createPluginStoreWithLogging<TState>(
+  initialState: TState,
+  enableLogging = false
+): PluginStore<TState> {
+  if (enableLogging) {
+    const store = createStore<TState>()(createLoggingMiddleware<TState>()(() => initialState));
+
+    return {
+      ...store,
+      destroy: () => {},
+    };
+  }
+
+  return createPluginStore(initialState);
+}

package/src/plugin/testing.ts

@@ -0,0 +1,236 @@
+/**
+ * Plugin testing utilities for Rempts
+ */
+
+import type { RemptsConfig, ResolvedConfig } from "../types";
+import { createLogger } from "../utils/logger";
+import { createPluginStore, type PluginStore } from "./store.js";
+import type { CommandContext, Plugin, PluginContext } from "./types";
+
+/**
+ * Mock plugin context for testing
+ */
+export function createMockPluginContext(
+  config: Partial<RemptsConfig> = {},
+  store: PluginStore<any> = createPluginStore({})
+): PluginContext {
+  return {
+    config,
+    updateConfig: () => {},
+    registerCommand: () => {},
+    use: () => {},
+    store,
+    logger: createLogger("test"),
+    paths: {
+      cwd: process.cwd(),
+      home: process.env.HOME || "/tmp",
+      config: "/tmp/.config/rempts",
+    },
+  };
+}
+
+/**
+ * Mock command context for testing
+ */
+export function createMockCommandContext<TStore = {}>(
+  command = "test",
+  args: string[] = [],
+  flags: Record<string, any> = {},
+  initialStore: TStore = {} as TStore
+): CommandContext<TStore> {
+  // Create a mock store that behaves like a Zustand store
+  let storeState = { ...initialStore };
+  const mockStore = {
+    getState: () => storeState,
+    setState: (updater: any) => {
+      if (typeof updater === "function") {
+        storeState = { ...storeState, ...updater(storeState) };
+      } else {
+        storeState = { ...storeState, ...updater };
+      }
+    },
+    subscribe: () => () => {}, // Mock subscription
+    destroy: () => {},
+  };
+
+  return {
+    command,
+    commandDef: {} as any,
+    args,
+    flags,
+    env: {
+      isCI: false,
+      isAIAgent: false,
+      aiAgents: [],
+    },
+    store: mockStore as any,
+    getStoreValue: (key: keyof TStore | string | number | symbol) => (storeState as any)[key],
+    setStoreValue: (key: keyof TStore | string | number | symbol, value: any) => {
+      mockStore.setState({ [key]: value });
+    },
+    hasStoreValue: (key: keyof TStore | string | number | symbol) => key in (storeState as object),
+  };
+}
+
+/**
+ * Test plugin lifecycle hooks
+ */
+export async function testPluginHooks<TStore = {}>(
+  plugin: Plugin<TStore>,
+  options: {
+    config?: Partial<RemptsConfig>;
+    store?: TStore;
+    command?: string;
+    args?: string[];
+    flags?: Record<string, any>;
+  } = {}
+) {
+  const hooks = plugin();
+  const results: {
+    setup?: any;
+    configResolved?: any;
+    beforeCommand?: any;
+    afterCommand?: any;
+  } = {};
+
+  // Test setup hook
+  if (hooks.setup) {
+    const context = createMockPluginContext(options.config);
+    try {
+      await hooks.setup(context);
+      results.setup = { success: true, context };
+    } catch (error) {
+      results.setup = { success: false, error };
+    }
+  }
+
+  // Test configResolved hook
+  if (hooks.configResolved) {
+    const config: ResolvedConfig = {
+      name: "test-cli",
+      version: "1.0.0",
+      description: "Test CLI",
+      commands: {},
+      build: {
+        targets: ["native"],
+        compress: false,
+        minify: false,
+        sourcemap: true,
+      },
+      dev: {
+        watch: true,
+        inspect: false,
+      },
+      test: {
+        pattern: ["**/*.test.ts", "**/*.spec.ts"],
+        coverage: false,
+        watch: false,
+      },
+      workspace: {
+        versionStrategy: "fixed",
+      },
+      release: {
+        npm: true,
+        github: false,
+        tagFormat: "v{{version}}",
+        conventionalCommits: true,
+      },
+      plugins: [],
+    };
+    try {
+      await hooks.configResolved(config);
+      results.configResolved = { success: true, config };
+    } catch (error) {
+      results.configResolved = { success: false, error };
+    }
+  }
+
+  // Test beforeCommand hook
+  if (hooks.beforeCommand) {
+    const context = createMockCommandContext(
+      options.command || "test",
+      options.args || [],
+      options.flags || {},
+      options.store || ({} as TStore)
+    );
+    try {
+      await hooks.beforeCommand(context);
+      results.beforeCommand = { success: true, context };
+    } catch (error) {
+      results.beforeCommand = { success: false, error };
+    }
+  }
+
+  // Test afterCommand hook
+  if (hooks.afterCommand) {
+    const context = createMockCommandContext(
+      options.command || "test",
+      options.args || [],
+      options.flags || {},
+      options.store || ({} as TStore)
+    );
+    try {
+      await hooks.afterCommand(context as any);
+      results.afterCommand = { success: true, context };
+    } catch (error) {
+      results.afterCommand = { success: false, error };
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Assert plugin behavior in tests
+ */
+export function assertPluginBehavior(
+  results: Awaited<ReturnType<typeof testPluginHooks>>,
+  expectations: {
+    setupShouldSucceed?: boolean;
+    configResolvedShouldSucceed?: boolean;
+    beforeCommandShouldSucceed?: boolean;
+    afterCommandShouldSucceed?: boolean;
+  }
+) {
+  const assertions: string[] = [];
+
+  if (expectations.setupShouldSucceed !== undefined) {
+    const actual = results.setup?.success ?? false;
+    if (actual !== expectations.setupShouldSucceed) {
+      assertions.push(
+        `Setup hook ${actual ? "succeeded" : "failed"} but expected ${expectations.setupShouldSucceed ? "success" : "failure"}`
+      );
+    }
+  }
+
+  if (expectations.configResolvedShouldSucceed !== undefined) {
+    const actual = results.configResolved?.success ?? false;
+    if (actual !== expectations.configResolvedShouldSucceed) {
+      assertions.push(
+        `ConfigResolved hook ${actual ? "succeeded" : "failed"} but expected ${expectations.configResolvedShouldSucceed ? "success" : "failure"}`
+      );
+    }
+  }
+
+  if (expectations.beforeCommandShouldSucceed !== undefined) {
+    const actual = results.beforeCommand?.success ?? false;
+    if (actual !== expectations.beforeCommandShouldSucceed) {
+      assertions.push(
+        `BeforeCommand hook ${actual ? "succeeded" : "failed"} but expected ${expectations.beforeCommandShouldSucceed ? "success" : "failure"}`
+      );
+    }
+  }
+
+  if (expectations.afterCommandShouldSucceed !== undefined) {
+    const actual = results.afterCommand?.success ?? false;
+    if (actual !== expectations.afterCommandShouldSucceed) {
+      assertions.push(
+        `AfterCommand hook ${actual ? "succeeded" : "failed"} but expected ${expectations.afterCommandShouldSucceed ? "success" : "failure"}`
+      );
+    }
+  }
+
+  if (assertions.length > 0) {
+    throw new Error(`Plugin behavior assertions failed:\n${assertions.join("\n")}`);
+  }
+}