chore: improve command documentation

Author: mrepol742

src/commands/ai.ts

@@ -2,11 +2,11 @@ import { Message } from "../types/message";
 import log from "../components/utils/log";
 import agentHandler from "../components/ai/agentHandler";
 import { greetings } from "../components/utils/data";
-import { commands } from "../components/utils/cmd/loader";
+import { Command, commands } from "../components/utils/cmd/loader";
 
 const PROJECT_CANIS_ALIS: string = process.env.PROJECT_CANIS_ALIAS || "Canis";
 
-export const info = {
+export const info: Command = {
   command: "ai",
   description: "Interact with the AI agent.",
   usage: "ai <query>",
@@ -42,7 +42,11 @@ export default async function (msg: Message): Promise<void> {
 
   for (const key in commands) {
     const cmd = commands[key];
-    if (cmd.role === "user" && !excludeAiCommands.includes(cmd.command)) {
+    if (
+      cmd.role === "user" &&
+      !excludeAiCommands.includes(cmd.command) &&
+      !(cmd.optOutAI ?? false)
+    ) {
       prompt += `\n${cmd.command} - ${cmd.description}\n${cmd.usage}\n`;
     }
   }

src/components/utils/cmd/loader.ts

@@ -10,18 +10,34 @@ const basePath = path.join(__dirname, "..", "..", "..", "commands");
 import * as Sentry from "@sentry/node";
 
 export const commandDirs = [basePath, path.join(basePath, "private")];
-export const commands: Record<
-  string,
-  {
-    command: string;
-    description: string;
-    usage: string;
-    example: string;
-    role: string;
-    cooldown: number;
-    exec: (msg: Message) => Promise<void>;
-  }
-> = {};
+export interface Command {
+  /** The actual command keyword the bot will listen for */
+  command: string;
+
+  /** A brief description of what the command does */
+  description: string;
+
+  /** How to use the command (syntax) */
+  usage: string;
+
+  /** Example usage of the command */
+  example: string;
+
+  /** Required role to use the command (e.g., 'admin', 'moderator') */
+  role: string;
+
+  /** Cooldown in seconds before the command can be reused */
+  cooldown: number;
+
+  /** Optional: set to true if you don't want AI to process this command */
+  optOutAI?: boolean;
+}
+
+interface InternalCommands extends Command {
+  /** The function that will be executed when the command is called */
+  exec: (msg: Message) => Promise<void>;
+}
+export const commands: Record<string, InternalCommands> = {};
 
 async function ensureDependencies(
   dependencies: { name: string; version: string }[],