ENHANCEMENTS:

- Commands: migrated to slash commands

BUGFIXES:
- Some former migrations did not re-read the configuration properly.

Author: karel26

core/plugin.py

@@ -22,7 +22,7 @@
 from discord.utils import MISSING, _shorten
 from packaging.version import parse
 from pathlib import Path
-from typing import Type, Optional, TYPE_CHECKING, Union, Any, Dict, Callable, List, Generic
+from typing import Type, Optional, TYPE_CHECKING, Union, Any, Callable, Generic
 
 from .const import DEFAULT_TAG
 from .listener import TEventListener
@@ -59,7 +59,7 @@ def command(
     description: Union[str, locale_str] = MISSING,
     nsfw: bool = False,
     auto_locale_strings: bool = True,
-    extras: Dict[Any, Any] = MISSING,
+    extras: dict[Any, Any] = MISSING,
 ) -> Callable[[CommandCallback[GroupT, P, T]], Command[GroupT, P, T]]:
     """Creates an application command from a regular function.
 
@@ -122,9 +122,9 @@ def __init__(
         callback: CommandCallback[GroupT, P, T],
         nsfw: bool = False,
         parent: Optional[Group] = None,
-        guild_ids: Optional[List[int]] = None,
+        guild_ids: Optional[list[int]] = None,
         auto_locale_strings: bool = True,
-        extras: Dict[Any, Any] = MISSING,
+        extras: dict[Any, Any] = MISSING,
     ):
         from services.bot import BotService
 
@@ -142,7 +142,7 @@ def __init__(
                 ((num_servers == 1 and nodes == 1) or not bot.locals.get('channels', {}).get('admin'))):
             del self._params['server']
 
-    async def _do_call(self, interaction: Interaction, params: Dict[str, Any]) -> T:
+    async def _do_call(self, interaction: Interaction, params: dict[str, Any]) -> T:
         if 'node' in inspect.signature(self._callback).parameters and 'node' not in params:
             params['node'] = interaction.client.node
         if 'server' in inspect.signature(self._callback).parameters and 'server' not in params:
@@ -175,7 +175,7 @@ def command(
         description: Union[str, locale_str] = MISSING,
         nsfw: bool = False,
         auto_locale_strings: bool = True,
-        extras: Dict[Any, Any] = MISSING,
+        extras: dict[Any, Any] = MISSING,
     ) -> Callable[[CommandCallback[GroupT, P, T]], Command[GroupT, P, T]]:
         """A decorator that creates an application command from a regular function under this group.
 

core/utils/validators.py

@@ -30,6 +30,7 @@
 
 __all__ = [
     "file_exists",
+    "dir_exists",
     "seq_or_map",
     "bool_or_map",
     "str_or_map",
@@ -115,15 +116,21 @@ def get_node_data() -> NodeData:
     return NodeData()
 
 def file_exists(value, _, path):
-    if path and path.split("/")[1] in [DEFAULT_TAG, COMMAND_LINE_ARGS.node]:
+    if path and path.split("/")[1] in [DEFAULT_TAG, COMMAND_LINE_ARGS.node, 'backups', 'commands']:
         filename = os.path.expandvars(value)
+        # do not check files with replacements
+        if '{' in filename:
+            return True
         if not os.path.exists(filename) or not os.path.isfile(filename):
             raise SchemaError(msg=f'File "{value}" does not exist or is no file', path=path)
     return True
 
 def dir_exists(value, _, path):
-    if path and path.split("/")[1] in [DEFAULT_TAG, COMMAND_LINE_ARGS.node]:
+    if path and path.split("/")[1] in [DEFAULT_TAG, COMMAND_LINE_ARGS.node, 'backups', 'commands']:
         filename = os.path.expandvars(value)
+        # do not check dirs with replacements
+        if '{' in filename:
+            return True
         if not os.path.exists(filename) or not os.path.isdir(filename):
             raise SchemaError(msg=f'Directory "{value}" does not exist or is no directory', path=path)
     return True

migrate.py

@@ -298,14 +298,6 @@ def migrate_3(node: str):
                 if plugin_name in ['backup', 'ovgme', 'music']:
                     shutil.move(f'config/plugins/{plugin_name}.yaml', f'config/services/{plugin_name}.yaml')
                     print(f"- Migrated config/{plugin_name}.json to config/services/{plugin_name}.yaml")
-                elif plugin_name == 'commands':
-                    data = yaml.load(Path('config/plugins/commands.yaml').read_text(encoding='utf-8'))
-                    data[DEFAULT_TAG] = {
-                        "command_prefix": cfg['BOT']['COMMAND_PREFIX']
-                    }
-                    with open('config/plugins/commands.yaml', mode='w', encoding='utf-8') as out:
-                        yaml.dump(data, out)
-                    print("- Migrated config/commands.json to config/plugins/commands.yaml")
                 else:
                     print(f"- Migrated config/{plugin_name}.json to config/plugins/{plugin_name}.yaml")
 

plugins/commands/README.md

@@ -11,31 +11,114 @@ opt_plugins:
 
 The plugin itself needs to be configured with a yaml file in config/plugins/commands.yaml. Each command has a name and 
 parameters. These parameters can be used in the arguments you use to call your external program. The sample shows how 
-to launch DCS from a specific command (not really useful as you have .startup, but you get the idea) and dir as a shell 
-command. 
+to launch DCS from a specific command (not really useful as you have `/server startup`, but you get the idea) and `dir` 
+as a shell command. 
 
 ```yaml
 commands:
-- name: dcs         # Create a command .dcs
-  roles:            # that can be run by the DCS Admin role
-  - DCS Admin
-  execute:          # and map it to a call of DCS_server.exe
-    cmd: DCS_server.exe
-    args: -w {instance}
-    cwd: C:\Program Files\Eagle Dynamics\DCS World Server\bin
-  params:           # which receives a parameter "instance" (will be auto replaced by the instance name)
-  - instance
-- name: dir         # Create a command .dir
-  roles:            # which can be run by Admin and DCS Admin
-  - Admin
-  - DCS Admin
-  execute:              # and that maps to a shell command "dir c:\"
-    cmd: dir
-    cwd: C:\
-    shell: true
-  hidden: true      # the .dir command will not apply in the help command
+  startup:              # Create a command /startup
+    roles:              # that can be run by the DCS Admin role
+    - DCS Admin
+    execute:            # and map it to a call of DCS_server.exe
+      cmd: DCS_server.exe
+      args: -w {instance.name}
+      cwd: C:\Program Files\Eagle Dynamics\DCS World Server\bin
+    params:             # parameter list
+      instance:         # instance parameters have auto completion
+        required: true  # mandatory parameter
+  dir:                  # Command /dir
+    description: shows a directory listing
+    roles:              # dir can be executed be Admin and DCS Admin
+    - Admin
+    - DCS Admin
+    execute:
+      shell: true       # Run dir as a shell command. You want to use this also for bat or cmd files.
+      cmd: dir
+      cwd: '{path}'
+      args: '{option}'
+    params:
+      option:
+        description: Options for the dir command
+        type: str
+        required: false
+      path:
+        description: Directory listing of this path
+        type: str
+        required: false
+        default: C:\Program Files\Eagle Dynamics\DCS World
+  setflag:
+    roles:
+    - DCS Admin
+    event:                  # Instead of running a command, send an event to DCS
+      command: setFlag      # setFlag takes 2 parameters
+      flag: '{flag}'
+      value: '{value}'
+    params:
+      server:               # we need to provide a server for events, otherwise they will be run on all servers
+        required: true
+      flag:
+        description: Flag to be set
+        required: true
+        type: int
+        choices:
+          - 100
+          - 110
+          - 120
+      value:
+        description: Value to set
+        type: int
+        required: true
+        choices:
+          - 1
+          - 2
+          - 3
 ```
-> [!NOTE]
-> * DCSServerBot needs to have the permissions to launch the respective executable!
-> * Do not run long-running shell scripts!
-> + These commands are NO slash commands, so they start with another prefix, set in the configuration!
+> [!IMPORTANT]
+> DCSServerBot needs to have the permission to launch the respective executables.
+
+> [!WARNING]
+> Do **not** run long-running shell scripts. 
+> Normal tasks can be long-running. You have commands to terminate them (see below).
+
+### Parameter Structure
+```yaml
+params:
+  name:                 # name of the parameter
+    type: str           # One of str, int, bool, member, channel, role, mentionable, number, attachment
+    description: xxx    # description of the parameter
+    required: true      # default: false
+    default: xxx        # A value to be set as default, if required = false. If not set, NONE will be applied.
+    nsfw: false         # Commands for NSFW-channels, default: false
+    min_value: 0        # Optional: min value for range
+    max_value: 10       # Optional: max value for range 
+    choices:            # Optional: choice of values (type must match the type above)
+      - A
+      - B
+      - C
+```
+
+### Special Parameters
+
+The following special parameters are supported and will be replaced by auto-completion if available:
+- node
+- instance
+- server
+- user
+- member
+- channel
+- role
+
+These parameters will be passed as objects.<br>
+You can keep it simple in the params section:
+```yaml
+params:
+  server:
+    required: true
+```
+
+## Discord Commands
+
+| Command             | Parameter | Channel | Role  | Description                                                  |
+|:--------------------|:----------|:--------|:------|:-------------------------------------------------------------|
+| /commands tasklist  |           | all     | Admin | Show all running processes that were started by this plugin. |
+| /commands terminate | process   | all     | Admin | Terminate a running process.                                 |