Update docs

Author: sontx

docs/plugin/module-location-resolver.md

@@ -85,4 +85,4 @@ Here are supported plugin types:
 10. [Workflow Runner](workflow-runner.md)
 11. [Pre/Post Run Workflow Plugin](pre-post-run-workflow-plugin.md)
 12. [Pre/Post Run Task Plugin](pre-post-run-task-plugin.md)
-13. [Module Location Resolver](module-location-resolver.md)
+13. [Task Handler Location Resolver](task-handler-location-resolver)

docs/plugin/plugin.md

@@ -0,0 +1,58 @@
+# TaskHandlerLocationResolver Plugin
+
+The `TaskHandlerLocationResolver` plugin is designed to resolve the location of task handlers within the system.
+It provides a consistent way to locate task handlers, whether they are specified by absolute paths, relative paths, or module names.
+
+The default implementation will look up in this order:
+
+1. If this type is `package`, we looked up in the node_modules directory, otherwise we stop immediately.
+2. Resolve it directly if it's an absolute path.
+3. Resolve it from the current directory.
+4. Resolve it from the runner directory.
+5. Lookup in the custom tasks directory (default is tasks directory).
+
+## Usage
+
+To create a `TaskHandlerLocationResolver` plugin, you need to implement the `TaskHandlerLocationResolver` interface and register your resolver plugin.
+
+### Example
+
+Here is an example of a `TaskHandlerLocationResolver` plugin:
+
+```typescript
+import { AbstractPlugin, TASK_HANDLER_LOCATION_RESOLVER_PLUGIN } from '@letrun/core';
+import { ParsedHandler } from '@letrun/common';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export default class ExampleTaskHandlerLocationResolver extends AbstractPlugin {
+  readonly name = 'example';
+  readonly type = TASK_HANDLER_LOCATION_RESOLVER_PLUGIN;
+
+  async resolveLocation(handler: ParsedHandler, throwsIfNotFound?: boolean) {
+    if (fs.existsSync(handler.name)) {
+      return handler.name;
+    }
+
+    if (throwsIfNotFound) {
+      throw new Error(`Module not found: ${handler.name}`);
+    }
+
+    return null;
+  }
+}
+```
+
+### Registering the Plugin
+
+To register the `TaskHandlerLocationResolver` plugin, place it in the `plugins` directory (or the directory specified in your configuration) and ensure it is loaded by the CLI tool.
+
+### Output
+
+For the example above, the resolver checks if the task handler exists at the specified location or within the tasks directory.
+If the handler is not found and `throwsIfNotFound` is set to `true`, an error is thrown.
+
+## Summary
+
+The `TaskHandlerLocationResolver` plugin provides a standardized way to resolve task handler locations within the system.
+By implementing this interface, you can customize the module resolution logic to fit your specific needs.

docs/plugin/task-handler-location-resolver.md

@@ -45,7 +45,7 @@ You can write custom tasks either in a simple JS file or a node package:
    - A node package that exports a default class that implements the `TaskHandler` interface.
    - The entry point should be defined in the `main` field in `package.json`.
    - The package should be published to npm or a private registry.
-   - We recommend you name the package with `letrun-task-` prefix.
+   - We recommend you use scoped package and name the package with `@letrun-task-` prefix.
    - You can install the package using `letrun task install <package-name>` command.
    - We also support you place the package in the `tasks` directory manually.
 
@@ -57,8 +57,6 @@ A task handler should have the following structure:
 - `parameters`: An object that describes the input parameters of the task for showing help.
 - `handle`: The function that executes the task.
 
-We support grouping tasks by placing them in subdirectories, the group name will be the directory name.
-
 This is an example of a custom task:
 
 ```ts
@@ -142,3 +140,77 @@ The output of the workflow will be: `HELLO, WORLD!`.
 > If you write custom task in TypeScript, you need to compile and bundle it to JavaScript before using.
 
 To show all available custom tasks, you can use the `letrun task list -c` command.
+
+## Task Group
+
+A task group is a collection of tasks that are grouped together.
+It is useful when you have a set of tasks that are related to each other.
+
+Currently, we support grouping tasks by placing them in subdirectories or multiple exported classes in a node package.
+
+### Subdirectory
+
+You can group tasks by placing them in subdirectories. The group name will be the directory name.
+The only one level of nesting is supported, so you can't nest a group inside another group.
+
+Here is an example of a task group:
+
+```
+tasks/
+└── my-group
+    ├── task1.js
+    └── task2.js
+```
+
+The task's handler will follow this format `script:group-name/script-file`.
+For example, the handler for `task1.js` will be `script:my-group/task1.js`.
+
+> This approach is limited to simple tasks.
+> If you need to use external libraries, we recommend you create a node package.
+
+### Node Package
+
+You can group tasks by exporting multiple classes in a node package.
+The group name will be the package name.
+
+Here is an example of a task group:
+
+**package.json**
+
+```json
+{
+  "name": "my-group",
+  "version": "1.0.0",
+  "main": "index.js"
+}
+```
+
+**index.js**
+
+```js
+export class Task1Handler {
+  name = 'task1';
+  handle() {
+    console.log('Task 1');
+  }
+}
+
+export class Task2Handler {
+  name = 'task2';
+  handle() {
+    console.log('Task 2');
+  }
+}
+```
+
+The task's handler will follow this format `package:package-name:task-name`.
+For example, the handler for `Task1Handler` will be `package:my-group:task1`.
+
+The group information will be obtained from the package.json:
+
+- `name`: The name of the task group.
+- `description`: A brief description of the task group.
+- `version`: The version of the task group.
+- `author`: The author of the task group.
+
+> We recommend you use scoped package and name the package with `@letrun-task-` prefix.

docs/task/task-handler.md

@@ -35,6 +35,36 @@ This is an example of a task definition:
 }
 ```
 
+## Task Handler Format
+
+A task handler is a string that represents the task type.
+It can be a built-in task or a custom task.
+The task handler should be defined in the `handler` field.
+
+The handler should follow the format: `type:identify[:task-name]`.
+
+- `type`: The type of the task, it can be:
+  - `package`: A task handler from a node package which is published to npm.
+  - `external`: A task handler from an external node package which is not published.
+  - `script`: A task handler from a standalone script file.
+- `identify`: The identifier of the task handler, it can be:
+  - The package name if the type is `package`. The version can be specified by using the `@` symbol, e.g. `@my-scope/[email protected]`.
+  - The path to the node module if the type is `external`.
+  - The path to the script file if the type is `script`.
+- `task-name`: The name of the task handler, this is optional if the identify isn't a group task package.
+
+> If the handler is a path, it will treat as a script task handler.
+
+This is some valid task handler examples:
+
+```text
+package:@letrun-task/[email protected]:read
+package:example-task
+
+external:./tasks/example-task
+script:./tasks/example-task.js
+```
+
 ## Nested Tasks
 
 You can nest tasks inside other tasks by defining the nested tasks in the `tasks` field. This is useful when you want to group tasks together.