feat(commands): implement typed arguments

It should make things eaiser without worrying about having wrong types,
also Standard Schema is compatible as well btw

bun.lock

···
       "name": "hydro",
       "dependencies": {
         "@fluxerjs/core": "^1.2.3",
+        "@standard-schema/spec": "^1.1.0",
         "@t3-oss/env-core": "^0.13.10",
         "reflect-metadata": "^0.2.2",
         "zod": "^4.3.6",
···
     "@fluxerjs/util": ["@fluxerjs/util@1.2.3", "", { "dependencies": { "@fluxerjs/types": "1.2.3" } }, "sha512-vxDlxnQV3sTAAdZGrRQrmEx+O8Uzydw+HMx6vF4l0nxeTRwAZgR19CApY6r0tZk2mnHwZO0pqfaXbB4dHL4bGw=="],
 
     "@fluxerjs/ws": ["@fluxerjs/ws@1.2.3", "", { "dependencies": { "@fluxerjs/types": "1.2.3", "ws": "^8.18.0" } }, "sha512-0aQn1myqChfO2pABYVdm1bSqWOQrDURt7Bzh42hNsiTUGiJIkyf78r24k6X1JDHXuhUEd9MTBkIDCqQ7LD1K6w=="],
+
+    "@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
 
     "@t3-oss/env-core": ["@t3-oss/env-core@0.13.10", "", { "peerDependencies": { "arktype": "^2.1.0", "typescript": ">=5.0.0", "valibot": "^1.0.0-beta.7 || ^1.0.0", "zod": "^3.24.0 || ^4.0.0" }, "optionalPeers": ["arktype", "typescript", "valibot", "zod"] }, "sha512-NNFfdlJ+HmPHkLi2HKy7nwuat9SIYOxei9K10lO2YlcSObDILY7mHZNSHsieIM3A0/5OOzw/P/b+yLvPdaG52g=="],
 

package.json

···
   },
   "dependencies": {
     "@fluxerjs/core": "^1.2.3",
+    "@standard-schema/spec": "^1.1.0",
     "@t3-oss/env-core": "^0.13.10",
     "reflect-metadata": "^0.2.2",
     "zod": "^4.3.6"

src/args.ts

···
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+
+// ---------------------------------------------------------------------------
+// Optional wrapper for external Standard Schema schemas
+//
+// External schemas (Zod, Valibot, etc.) are treated as required by default.
+// Wrap with arg.optional(schema) to make them optional.
+// ---------------------------------------------------------------------------
+
+export interface OptionalStandardSchema<S extends StandardSchemaV1> {
+  readonly _tag: "optional";
+  readonly schema: S;
+}
+
+// ---------------------------------------------------------------------------
+// Our native ArgDef — implements StandardSchemaV1 so it's interoperable
+// with any tooling that accepts Standard Schema.
+//
+// Input is always `string` (a raw positional arg from the message).
+// Output is whatever the parser produces.
+// ---------------------------------------------------------------------------
+
+export interface ArgDef<T> extends StandardSchemaV1<string, T> {
+  readonly required: true;
+  optional(): OptionalArgDef<T>;
+}
+
+export interface OptionalArgDef<T> extends StandardSchemaV1<string, T | undefined> {
+  readonly required: false;
+}
+
+// ---------------------------------------------------------------------------
+// What can appear as a value in an arg schema
+// ---------------------------------------------------------------------------
+
+export type ArgEntry =
+  | ArgDef<unknown>
+  | OptionalArgDef<unknown>
+  | StandardSchemaV1 // any external schema — required by default
+  | OptionalStandardSchema<StandardSchemaV1>; // external schema wrapped as optional
+
+export type ArgSchema = Record<string, ArgEntry>;
+
+// Infer the parsed output type for a single entry
+type InferEntry<E extends ArgEntry> =
+  E extends OptionalStandardSchema<infer S>
+    ? StandardSchemaV1.InferOutput<S> | undefined
+    : E extends StandardSchemaV1
+      ? StandardSchemaV1.InferOutput<E>
+      : never;
+
+// Infer the fully parsed object type from a schema
+export type ParsedArgs<S extends ArgSchema> = {
+  [K in keyof S]: InferEntry<S[K]>;
+};
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function makeStandardProps<T>(
+  required: boolean,
+  parser: (raw: string) => T,
+): StandardSchemaV1<string, T>["~standard"] {
+  return {
+    version: 1 as const,
+    vendor: "hydro-args",
+    validate(value: unknown) {
+      if (value === undefined || value === "") {
+        if (required) {
+          return { issues: [{ message: "Missing required argument" }] };
+        }
+        return { value: undefined as T };
+      }
+      try {
+        return { value: parser(value as string) };
+      } catch (e) {
+        return { issues: [{ message: e instanceof Error ? e.message : String(e) }] };
+      }
+    },
+    types: undefined,
+  };
+}
+
+function makeOptional<T>(parser: (raw: string) => T): OptionalArgDef<T> {
+  return {
+    required: false as const,
+    "~standard": makeStandardProps(false, parser) as StandardSchemaV1<
+      string,
+      T | undefined
+    >["~standard"],
+  };
+}
+
+function makeRequired<T>(parser: (raw: string) => T): ArgDef<T> {
+  return {
+    required: true as const,
+    "~standard": makeStandardProps(true, parser),
+    optional(): OptionalArgDef<T> {
+      return makeOptional(parser);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Arg factories — the public API
+// ---------------------------------------------------------------------------
+
+export const arg = {
+  /** Raw string — returned as-is */
+  string(): ArgDef<string> {
+    return makeRequired((raw) => raw);
+  },
+
+  /** Parsed as a float — throws if not a valid number */
+  number(): ArgDef<number> {
+    return makeRequired((raw) => {
+      const n = Number(raw);
+      if (Number.isNaN(n)) throw new Error(`Expected a number, got "${raw}"`);
+      return n;
+    });
+  },
+
+  /** Parses "true"/"yes"/"1" as true, "false"/"no"/"0" as false */
+  boolean(): ArgDef<boolean> {
+    return makeRequired((raw) => {
+      const lower = raw.toLowerCase();
+      if (lower === "true" || lower === "yes" || lower === "1") return true;
+      if (lower === "false" || lower === "no" || lower === "0") return false;
+      throw new Error(`Expected a boolean (true/false/yes/no/1/0), got "${raw}"`);
+    });
+  },
+
+  /**
+   * Greedily consumes all remaining positional args into a single string.
+   * Must be the last entry in the schema.
+   *   !ban @user being rude in chat  →  reason = "being rude in chat"
+   */
+  rest(): ArgDef<string> & { readonly _rest: true } {
+    return { ...makeRequired((raw) => raw), _rest: true as const };
+  },
+
+  /**
+   * Wraps any Standard Schema compatible schema (Zod, Valibot, ArkType, etc.)
+   * as an optional arg. Without this wrapper, external schemas are required.
+   *
+   * @example
+   * const schema = {
+   *   tag: z.string().regex(/^[a-z]+$/),       // required, validated by Zod
+   *   note: arg.optional(z.string().max(100)),  // optional, validated by Zod
+   * };
+   */
+  optional<S extends StandardSchemaV1>(schema: S): OptionalStandardSchema<S> {
+    return { _tag: "optional", schema };
+  },
+} as const;
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+function isOptionalWrapper(entry: ArgEntry): entry is OptionalStandardSchema<StandardSchemaV1> {
+  return "_tag" in entry && (entry as OptionalStandardSchema<StandardSchemaV1>)._tag === "optional";
+}
+
+function isNativeArgDef(entry: ArgEntry): entry is ArgDef<unknown> | OptionalArgDef<unknown> {
+  return "required" in entry;
+}
+
+function isRest(entry: ArgEntry): boolean {
+  return "_rest" in entry && (entry as { _rest?: boolean })._rest === true;
+}
+
+// ---------------------------------------------------------------------------
+// Parser — called by the registry before execute()
+// ---------------------------------------------------------------------------
+
+async function validateEntry(
+  key: string,
+  entry: ArgEntry,
+  rawValue: string | undefined,
+): Promise<unknown> {
+  // Optional wrapper around an external schema
+  if (isOptionalWrapper(entry)) {
+    if (rawValue === undefined || rawValue === "") return undefined;
+    return runValidate(key, entry.schema, rawValue);
+  }
+
+  // Our native ArgDef / OptionalArgDef (also StandardSchemaV1)
+  if (isNativeArgDef(entry)) {
+    // Delegate to the ~standard.validate() we set up — it handles required/optional internally
+    return runValidate(key, entry, rawValue ?? "");
+  }
+
+  // Plain external Standard Schema — treated as required
+  if (rawValue === undefined || rawValue === "") {
+    throw new Error(`Missing required argument: ${key}`);
+  }
+  return runValidate(key, entry, rawValue);
+}
+
+async function runValidate(
+  key: string,
+  schema: StandardSchemaV1,
+  value: unknown,
+): Promise<unknown> {
+  let result = schema["~standard"].validate(value);
+  if (result instanceof Promise) result = await result;
+  if (result.issues) {
+    const messages = result.issues.map((i) => i.message).join(", ");
+    throw new Error(`Argument "${key}": ${messages}`);
+  }
+  return result.value;
+}
+
+export async function parseArgs<S extends ArgSchema>(
+  schema: S,
+  raw: string[],
+): Promise<ParsedArgs<S>> {
+  const keys = Object.keys(schema);
+  const result: Record<string, unknown> = {};
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i]!;
+    const entry = schema[key]!;
+    const isLastEntry = i === keys.length - 1;
+
+    let rawValue: string | undefined;
+
+    if (isRest(entry) && isLastEntry) {
+      // Consume all remaining tokens as one string
+      rawValue = raw.slice(i).join(" ") || undefined;
+    } else {
+      rawValue = raw[i];
+    }
+
+    result[key] = await validateEntry(key, entry, rawValue);
+  }
+
+  return result as ParsedArgs<S>;
+}

src/bot.ts

···
 
   registerEvents() {
     this.client.on(Events.MessageCreate, async (msg: Message) => {
-      await this.registry.handle(env.PREFIX, msg);
-    })
+      await this.registry.handle({ client: this.client }, env.PREFIX, msg);
+    });
   }
 
   async start() {
···
     this.registerEvents();
 
     this.client.on(Events.Ready, () => {
-      console.log("The bot is now ready")
-    })
+      console.log("The bot is now ready");
+    });
 
     // After loading commands and registering events, we can now login our bot
     await this.client.login(env.FLUXER_BOT_TOKEN);

src/registry/commandRegistry.ts

···
 import type { Message } from "@fluxerjs/core";
 import { COMMAND_META_KEY, type CommandMeta } from "../decorators/command";
 import { GUARDS_KEY, type Guard } from "../decorators/guards";
-import type { ICommand } from "../types";
+import { parseArgs } from "../args";
+import type { BotContext, ICommand } from "../types";
 import type { CommandCtor } from "../types";
 
 interface FileRecord {
···
   triggers: string[];
 }
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyCommand = ICommand<any>;
+
 export class CommandRegistry {
-  private map = new Map<string, ICommand>();
+  private map = new Map<string, AnyCommand>();
   private guards = new Map<string, Guard[]>();
   private fileSources = new Map<string, FileRecord>();
 
···
       }
 
       if (filePath) {
-        this.fileSources.set(meta.name, { filePath, triggers })
+        this.fileSources.set(meta.name, { filePath, triggers });
       }
     }
   }
···
     }
   }
 
-  async handle(prefix: string, message: Message): Promise<void> {
+  async handle(ctx: BotContext, prefix: string, message: Message): Promise<void> {
     if (!message.content.startsWith(prefix)) return;
     const [rawCmd, ...args] = message.content.slice(prefix.length).trim().split(/\s+/);
     const key = `${prefix}${rawCmd?.toLowerCase()}`;
···
       if (!(await guard(message))) return;
     }
 
-    await command.execute(message, args);
+    // Parse raw string args through the command's schema if it has one,
+    // otherwise pass the raw array cast to the expected type.
+    const parsedArgs = command.args ? await parseArgs(command.args, args) : ({} as never);
+
+    await command.execute(ctx, message, parsedArgs);
   }
 }

src/registry/loadCommands.ts

···
 export async function loadCommands(
   registry: CommandRegistry,
   prefix: string,
-  pattern = "src/commands/**/*.ts"
+  pattern = "src/commands/**/*.ts",
 ): Promise<void> {
   const glob = new Bun.Glob(pattern);
 

src/registry/watchCommands.ts

···
 async function reloadFile(
   registry: CommandRegistry,
   prefix: string,
-  absPath: string
+  absPath: string,
 ): Promise<void> {
   try {
     delete _require.cache[absPath];
···
 export function watchCommands(
   registry: CommandRegistry,
   prefix: string,
-  dir = "src/commands"
+  dir = "src/commands",
 ): void {
   // We intentionally ignore the event type here.
   // On Linux, editors do atomic saves (write tmp → rename into place),
···
           registry.unregisterFile(absPath);
           console.log(`[hot-reload] Unloaded: ${absPath}`);
         }
-      }, 50)
+      }, 50),
     );
   });
 

src/types.ts

···
-import type { Message } from "@fluxerjs/core";
+import type { Client, Message } from "@fluxerjs/core";
+import type { ArgSchema, ParsedArgs } from "./args";
+
+export type { ParsedArgs };
+
+/** Injected into every command's execute() call by the registry. */
+export interface BotContext {
+  client: Client;
+}
+
+export interface ICommand<TArgs extends ArgSchema = Record<string, never>> {
+  /**
+   * Declare your arg schema here. The registry reads this to parse and
+   * validate raw string args before calling execute().
+   *
+   * Entries can be:
+   *   - Our built-in helpers: arg.string(), arg.number(), arg.boolean(), arg.rest()
+   *   - Any Standard Schema compatible schema (Zod, Valibot, ArkType, etc.) — required by default
+   *   - arg.optional(zodSchema) — to make an external schema optional
+   *
+   * Omit entirely for commands that take no args.
+   */
+  readonly args?: TArgs;
 
-export interface ICommand {
-  execute(message: Message, args: string[]): Promise<void>
+  execute(ctx: BotContext, message: Message, args: ParsedArgs<TArgs>): Promise<void>;
 }
 
-export type CommandCtor = new () => ICommand;
+export type CommandCtor = new () => ICommand<ArgSchema>;