@runium/cli 0.0.1 → 0.0.3

package/src/services/plugin.ts

@@ -1,49 +1,100 @@
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { Service } from 'typedi';
+import { Inject, Service } from 'typedi';
 import {
   isRuniumError,
-  Macro,
+  MacrosCollection,
+  Project,
+  ProjectConfig,
   ProjectSchemaExtension,
   RuniumError,
   RuniumTaskConstructor,
   RuniumTriggerConstructor,
   RuniumTriggerOptions,
 } from '@runium/core';
+import { RuniumCommandConstructor } from '@commands/runium-command.js';
 import { ErrorCode } from '@constants';
-
-type PluginOptions = Record<string, unknown>;
+import { OutputService } from '@services';
+import {
+  createValidator,
+  getErrorMessages,
+  getPluginSchema,
+} from '@validation';
 
 type PluginModule = { default: (options?: PluginOptions) => Plugin };
 
+type PluginHookErrorHandler = (error: RuniumError) => void;
+
+type PluginHookName =
+  | `app.${keyof PluginAppHooksDefinition}`
+  | `project.${keyof PluginProjectHooksDefinition}`;
+
+interface PluginHookOptions<M extends boolean> {
+  mutable?: M;
+  onError?: PluginHookErrorHandler;
+}
+
 export interface PluginProjectDefinition {
-  macros?: Record<string, Macro>;
+  macros?: MacrosCollection;
   tasks?: Record<string, RuniumTaskConstructor>;
   actions?: Record<string, (payload: unknown) => void>;
   triggers?: Record<string, RuniumTriggerConstructor<RuniumTriggerOptions>>;
   validationSchema?: ProjectSchemaExtension;
 }
 
-export interface PluginOptionsDefinition {
-  value?: PluginOptions;
-  validate?(options: PluginOptions): boolean;
-}
+export type PluginOptions = Record<string, unknown>;
 
 export interface PluginAppDefinition {
-  commands?: Record<string, unknown>;
+  commands?: RuniumCommandConstructor[];
+}
+
+export interface PluginProjectHooksDefinition {
+  beforeConfigRead?(path: string): Promise<void>;
+  afterConfigRead?(content: string): Promise<string>;
+  afterConfigMacrosApply?(content: string): Promise<string>;
+  afterConfigParse?<T extends ProjectConfig>(config: T): Promise<T>;
+  beforeStart?(project: Project): Promise<void>;
+}
+
+export interface PluginAppHooksDefinition {
+  afterInit?(params: { profilePath: string }): Promise<void>;
+  beforeExit?(reason?: string): Promise<void>;
+  beforeCommandRun?(params: {
+    command: string;
+    args: unknown[];
+  }): Promise<void>;
+  afterCommandRun?(params: { command: string; args: unknown[] }): Promise<void>;
+}
+
+export interface PluginHooksDefinition {
+  app?: PluginAppHooksDefinition;
+  project?: PluginProjectHooksDefinition;
 }
 
 export interface Plugin {
   name: string;
   project?: PluginProjectDefinition;
-  options?: PluginOptionsDefinition;
+  options?: PluginOptions;
   app?: PluginAppDefinition;
+  hooks?: PluginHooksDefinition;
 }
 
 @Service()
 export class PluginService {
+  /**
+   * Loaded plugins
+   */
   private plugins: Map<string, Plugin> = new Map();
 
+  /**
+   * Validate plugin schema
+   * @private
+   */
+  private validator: ReturnType<typeof createValidator> =
+    createValidator(getPluginSchema());
+
+  constructor(@Inject() private outputService: OutputService) {}
+
   /**
    * Get all plugins
    */
@@ -62,8 +113,9 @@ export class PluginService {
   /**
    * Load plugin
    * @param path
+   * @param options
    */
-  async loadPlugin(path: string): Promise<string> {
+  async loadPlugin(path: string, options?: PluginOptions): Promise<string> {
     if (!path || !existsSync(path)) {
       throw new RuniumError(
         `Plugin file "${path}" does not exist`,
@@ -82,7 +134,7 @@ export class PluginService {
           { path }
         );
       }
-      const plugin = getPlugin();
+      const plugin = getPlugin(options);
 
       this.validate(plugin);
 
@@ -95,7 +147,7 @@ export class PluginService {
       }
       throw new RuniumError(
         `Failed to load plugin "${path}"`,
-        ErrorCode.PLUGIN_INCORRECT_PLUGIN,
+        ErrorCode.PLUGIN_LOAD_ERROR,
         { path, original: error }
       );
     }
@@ -127,17 +179,69 @@ export class PluginService {
     }
   }
 
+  /**
+   * Run plugin hook
+   * @param name
+   * @param params
+   * @param options
+   */
+  async runHook<T, M extends boolean>(
+    name: PluginHookName,
+    params: T,
+    { mutable, onError }: PluginHookOptions<M> = {}
+  ): Promise<M extends true ? T : void> {
+    const plugins = this.getAllPlugins();
+
+    const [group, hookName] = name.split('.') as [
+      keyof PluginHooksDefinition,
+      keyof PluginHooksDefinition[keyof PluginHooksDefinition],
+    ];
+
+    for (const plugin of plugins) {
+      const hook = plugin.hooks?.[group]?.[hookName] as
+        | ((params: T) => Promise<T>)
+        | undefined;
+      if (hook) {
+        try {
+          if (!mutable) {
+            await hook(params);
+          } else {
+            params = (await hook(params)) ?? params;
+          }
+        } catch (ex) {
+          const error = new RuniumError(
+            `Failed to run "${plugin.name}.${name}" hook`,
+            ErrorCode.PLUGIN_HOOK_ERROR,
+            { plugin: plugin.name, hook: name, original: ex }
+          );
+          if (onError) {
+            onError(error);
+          } else {
+            this.outputService.error('Error: %s', error.message);
+            this.outputService.debug('Error details:', {
+              code: error.code,
+              payload: error.payload,
+            });
+          }
+        }
+      }
+    }
+
+    return (mutable ? params : undefined) as M extends true ? T : void;
+  }
+
   /**
    * Validate plugin
    * @param plugin
    */
   private validate(plugin: Plugin): void {
-    // TODO add plugin validation
-    if (!plugin || !plugin?.name) {
+    const result = this.validator(plugin || {});
+    if (!result && this.validator.errors) {
+      const errorMessages = getErrorMessages(this.validator.errors);
       throw new RuniumError(
         'Incorrect plugin format',
-        ErrorCode.PLUGIN_INCORRECT_PLUGIN,
-        { name: plugin.name }
+        ErrorCode.PLUGIN_INVALID,
+        { errors: errorMessages }
       );
     }
   }

package/src/services/profile.ts

@@ -1,15 +1,8 @@
 import { existsSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { Inject, Service } from 'typedi';
-import {
-  JSONObject,
-  readJsonFile,
-  RuniumError,
-  writeJsonFile,
-} from '@runium/core';
-import { ConfigService } from '@services';
-import { ErrorCode } from '@constants';
+import { ConfigService, FileService } from '@services';
 
 export interface ProfilePlugin {
   name: string;
@@ -35,7 +28,10 @@ export class ProfileService {
 
   private projects: ProfileProject[] = [];
 
-  constructor(@Inject() private configService: ConfigService) {}
+  constructor(
+    @Inject() private configService: ConfigService,
+    @Inject() private fileService: FileService
+  ) {}
 
   /**
    * Initialize the profile service
@@ -47,6 +43,7 @@ export class ProfileService {
     }
 
     await this.readPlugins();
+    await this.patchPlugins();
     await this.readProjects();
   }
 
@@ -140,39 +137,10 @@ export class ProfileService {
   }
 
   /**
-   * Read JSON file
-   * @param pathParts
-   */
-  async readJsonFile(...pathParts: string[]): Promise<JSONObject> {
-    return readJsonFile(this.getPath(...pathParts));
-  }
-
-  /**
-   * Write JSON file
-   * @param data
-   * @param parts
-   */
-  async writeJsonFile(data: unknown, ...parts: string[]): Promise<void> {
-    const path = this.getPath(...parts);
-    try {
-      const dirName = dirname(path);
-      if (!existsSync(dirName)) {
-        await mkdir(dirName, { recursive: true });
-      }
-      await writeJsonFile(path, data);
-    } catch (error) {
-      throw new RuniumError(
-        `Failed to write JSON file`,
-        ErrorCode.PROFILE_JSON_WRITE_ERROR,
-        { path, data, original: error }
-      );
-    }
-  }
-  /**
-   * Read JSON file
+   * Get path for a file
    * @param parts
    */
-  private getPath(...parts: string[]): string {
+  getPath(...parts: string[]): string {
     return join(this.path, ...parts);
   }
 
@@ -181,31 +149,51 @@ export class ProfileService {
    */
   private async readPlugins(): Promise<void> {
     this.plugins =
-      ((await readJsonFile(this.getPath(PLUGINS_FILE_NAME)).catch(
-        () => []
-      )) as ProfilePlugin[]) || this.plugins;
+      ((await this.fileService
+        .readJson(this.getPath(PLUGINS_FILE_NAME))
+        .catch(() => [])) as ProfilePlugin[]) || this.plugins;
   }
 
   /**
    * Write plugins to file
    */
   private async writePlugins(): Promise<void> {
-    await writeJsonFile(this.getPath(PLUGINS_FILE_NAME), this.plugins);
+    await this.fileService.writeJson(
+      this.getPath(PLUGINS_FILE_NAME),
+      this.plugins
+    );
   }
+
+  /**
+   * Patch plugins
+   */
+  private async patchPlugins(): Promise<void> {
+    const pluginsConfig = this.configService.get('plugins');
+    for (const plugin of this.plugins) {
+      const config = pluginsConfig[plugin.name];
+      if (config) {
+        Object.assign(plugin, config);
+      }
+    }
+  }
+
   /**
    * Read projects from file
    */
   private async readProjects(): Promise<void> {
     this.projects =
-      ((await readJsonFile(this.getPath(PROJECTS_FILE_NAME)).catch(
-        () => []
-      )) as ProfileProject[]) || this.projects;
+      ((await this.fileService
+        .readJson(this.getPath(PROJECTS_FILE_NAME))
+        .catch(() => [])) as ProfileProject[]) || this.projects;
   }
 
   /**
    * Write projects to file
    */
   private async writeProjects(): Promise<void> {
-    await writeJsonFile(this.getPath(PROJECTS_FILE_NAME), this.projects);
+    await this.fileService.writeJson(
+      this.getPath(PROJECTS_FILE_NAME),
+      this.projects
+    );
   }
 }

package/src/services/project.ts

@@ -16,9 +16,27 @@ export class ProjectService {
    * @param path
    */
   async initProject(path: string): Promise<Project> {
-    const content = await this.readFile(path);
-    const projectContent = this.applyMacros(content);
-    const projectData = this.parseProjectContent(projectContent, path);
+    await this.pluginService.runHook('project.beforeConfigRead', path);
+
+    let content = await this.readFile(path);
+    content = await this.pluginService.runHook(
+      'project.afterConfigRead',
+      content,
+      { mutable: true }
+    );
+    content = this.applyMacros(content);
+    content = await this.pluginService.runHook(
+      'project.afterConfigMacrosApply',
+      content,
+      { mutable: true }
+    );
+
+    let projectData = this.parseProjectContent(content, path);
+    projectData = await this.pluginService.runHook(
+      'project.afterConfigParse',
+      projectData,
+      { mutable: true }
+    );
 
     const project = new Project(projectData);
     return this.extendProjectWithPlugins(project);
@@ -32,6 +50,16 @@ export class ProjectService {
     return resolve(path);
   }
 
+  /**
+   * Run hook
+   * @param args
+   */
+  runHook(
+    ...args: Parameters<PluginService['runHook']>
+  ): ReturnType<PluginService['runHook']> {
+    return this.pluginService.runHook(...args);
+  }
+
   /**
    * Read project file
    * @param path

package/src/services/shutdown.ts

@@ -1,7 +1,7 @@
 import { Inject, Service } from 'typedi';
-import { OutputService } from '@services';
+import { OutputService, PluginService } from '@services';
 
-type ShutdownBlocker = () => Promise<void> | void;
+type ShutdownBlocker = (reason?: string) => Promise<void> | void;
 
 const TIMEOUT = 30000;
 const EXIT_DELAY = 250;
@@ -12,7 +12,10 @@ export class ShutdownService {
   private blockers: Set<ShutdownBlocker> = new Set();
   private isShuttingDown = false;
 
-  constructor(@Inject() private outputService: OutputService) {}
+  constructor(
+    @Inject() private outputService: OutputService,
+    @Inject() private pluginService: PluginService
+  ) {}
   /**
    * Initialize shutdown handlers
    */
@@ -82,6 +85,15 @@ export class ShutdownService {
       return;
     }
 
+    // add plugin beforeExit hooks as shutdown blockers
+    const plugins = this.pluginService.getAllPlugins();
+    for (const plugin of plugins) {
+      const hook = plugin.hooks?.app?.beforeExit;
+      if (hook) {
+        this.addBlocker(hook.bind(plugin, reason));
+      }
+    }
+
     this.isShuttingDown = true;
 
     const exitProcess = (code: number): void => {
@@ -96,7 +108,7 @@ export class ShutdownService {
     }
 
     try {
-      await this.executeBlockersWithTimeout();
+      await this.executeBlockersWithTimeout(reason);
       exitProcess(0);
     } catch (error) {
       exitProcess(1);
@@ -105,10 +117,11 @@ export class ShutdownService {
 
   /**
    * Execute all blockers with timeout
+   * @param reason
    */
-  private async executeBlockersWithTimeout(): Promise<void> {
+  private async executeBlockersWithTimeout(reason: string): Promise<void> {
     const blockerPromises = Array.from(this.blockers).map(blocker =>
-      this.executeBlocker(blocker)
+      this.executeBlocker(blocker, reason)
     );
 
     const timeoutPromise = new Promise<never>((_, reject) => {
@@ -123,8 +136,12 @@ export class ShutdownService {
   /**
    * Execute a single blocker with error handling
    * @param blocker
+   * @param reason
    */
-  private async executeBlocker(blocker: ShutdownBlocker): Promise<void> {
-    await blocker();
+  private async executeBlocker(
+    blocker: ShutdownBlocker,
+    reason: string
+  ): Promise<void> {
+    await blocker(reason);
   }
 }

package/src/utils/get-version.ts

@@ -0,0 +1,13 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+let version: string | null = null;
+
+export function getVersion(): string {
+  if (!version) {
+    const packageJsonPath = resolve(import.meta.dirname, '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    version = packageJson.version;
+  }
+  return version as string;
+}

package/src/utils/index.ts

@@ -1,3 +1,4 @@
 export { convertPathToValidFileName } from './convert-path-to-valid-file-name.js';
 export { debounce } from './debounce.js';
 export { formatTimestamp } from './format-timestamp.js';
+export { getVersion } from './get-version.js';

package/src/validation/create-validator.ts

@@ -0,0 +1,27 @@
+import Ajv, { ValidateFunction } from 'ajv/dist/2020.js';
+
+const classes = { Function: Function };
+
+export type Validator<T = unknown> = ValidateFunction<T>;
+
+/**
+ * Create validator
+ * @param schema
+ */
+export function createValidator<T = unknown>(schema: object): Validator<T> {
+  const ajv = new Ajv({
+    allowUnionTypes: true,
+    allErrors: true,
+    verbose: true,
+  });
+
+  ajv.addKeyword({
+    keyword: 'instanceof',
+    schemaType: 'string',
+    validate: (schema: string, data: unknown) => {
+      return data instanceof classes[schema as keyof typeof classes];
+    },
+  });
+
+  return ajv.compile<T>(schema);
+}

package/src/validation/get-config-schema.ts

@@ -0,0 +1,59 @@
+/**
+ * Get config schema
+ */
+export function getConfigSchema(): object {
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: 'https://runium.dev/schemas/config.json',
+    title: 'Runium Config',
+    type: 'object',
+    properties: {
+      env: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'array',
+            items: {
+              type: 'string',
+            },
+          },
+        },
+        additionalProperties: false,
+      },
+      output: {
+        type: 'object',
+        properties: {
+          debug: {
+            type: 'boolean',
+          },
+        },
+        additionalProperties: false,
+      },
+      profile: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+          },
+        },
+        additionalProperties: false,
+      },
+      plugins: {
+        type: 'object',
+        additionalProperties: {
+          type: 'object',
+          properties: {
+            disabled: {
+              type: 'boolean',
+            },
+            options: {
+              type: 'object',
+            },
+          },
+          additionalProperties: false,
+        },
+      },
+    },
+    additionalProperties: false,
+  };
+}

package/src/validation/get-error-messages.ts

@@ -0,0 +1,35 @@
+import { ErrorObject } from 'ajv';
+import { AggregateAjvError, Options } from '@segment/ajv-human-errors';
+import { AjvError } from '@segment/ajv-human-errors/dist/cjs/aggregate-ajv-error';
+
+interface GetErrorMessagesOptions extends Options {
+  filter?: (error: AjvError) => boolean;
+}
+
+/**
+ * Get error messages
+ * @param errors
+ * @param options
+ */
+export function getErrorMessages(
+  errors: ErrorObject[],
+  options: GetErrorMessagesOptions = {
+    filter: () => true,
+  }
+): string[] {
+  const humanErrors = new AggregateAjvError(errors, {
+    fieldLabels: 'jsonPath',
+    includeData: true,
+    includeOriginalError: true,
+  });
+
+  const filter = options?.filter ?? (_ => true);
+  const messages = [];
+  for (const error of humanErrors) {
+    if (filter(error)) {
+      messages.push(error.message);
+    }
+  }
+
+  return messages;
+}