@reliverse/rempts 1.7.7 → 1.7.8

package/README.md

@@ -155,7 +155,7 @@ await main();
 ```ts
 import { relinka } from "@reliverse/relinka";
 
-import { defineCommand, runMain } from "~/mod.js";
+import { defineCommand, runMain } from "@reliverse/rempts";
 
 const main = defineCommand({
   meta: {
@@ -238,7 +238,7 @@ defineCommand({
   args: {
     name: { type: "string", required: true },
     verbose: { type: "boolean", default: false },
-    animals: { type: "array", options: ["cat","dog"] },
+    animals: { type: "array", default: ["cat","dog"] },
   },
   async run({ args, raw }) { // or `async run(ctx)`
     relinka("log", args.name, args.verbose, args.animals); // or `relinka("log", ctx.args.name, ...);`
@@ -283,7 +283,7 @@ When playing with the example, you can run e.g. `bun dev:modern nested foo bar b
 git clone https://github.com/reliverse/rempts
 cd rempts
 bun i
-bun dev # supported options: name
+bun dev
 ```
 
 - `bun dev:prompts`: This example will show you a `multiselectPrompt()` where you can choose which CLI prompts you want to play with.
@@ -563,12 +563,12 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
 
 - **Lifecycle Hooks:**
   You can define optional lifecycle hooks in your main command:
-  - `onLauncherStart` and `onLauncherEnd` (global, called once per CLI process)
+  - `onLauncherInit` and `onLauncherExit` (global, called once per CLI process)
   - `onCmdInit` and `onCmdExit` (per-command, called before/after each command, but NOT for the main `run()` handler)
 
   **Global Hooks:**
-  - `onLauncherStart`: Called once, before any command/run() is executed.
-  - `onLauncherEnd`: Called once, after all command/run() logic is finished (even if an error occurs).
+  - `onLauncherInit`: Called once, before any command/run() is executed.
+  - `onLauncherExit`: Called once, after all command/run() logic is finished (even if an error occurs).
 
   **Per-Command Hooks:**
   - `onCmdInit`: Called before each command (not for main `run()`).
@@ -578,20 +578,20 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
   - If your CLI has multiple commands, `onCmdInit` and `onCmdExit` will be called for each command invocation, not just once for the whole CLI process.
   - If your main command has a `run()` handler (and no command is invoked), these hooks are **not** called; use the `run()` handler itself or the global hooks for such logic.
   - This allows you to perform setup/teardown logic specific to each command execution.
-  - If you want logic to run only once for the entire CLI process, use `onLauncherStart` and `onLauncherEnd`.
+  - If you want logic to run only once for the entire CLI process, use `onLauncherInit` and `onLauncherExit`.
 
   **Example:**
 
   ```ts
   const main = defineCommand({
-    onLauncherStart() { relinka('info', 'Global setup (once per process)'); },
-    onLauncherEnd() { relinka('info', 'Global cleanup (once per process)'); },
+    onLauncherInit() { relinka('info', 'Global setup (once per process)'); },
+    onLauncherExit() { relinka('info', 'Global cleanup (once per process)'); },
     onCmdInit() { relinka('info', 'Setup for each command'); },
     onCmdExit() { relinka('info', 'Cleanup for each command'); },
     commands: { ... },
     run() { relinka('info', 'Main run handler (no command)'); },
   });
-  // onLauncherStart/onLauncherEnd are called once per process
+  // onLauncherInit/onLauncherExit are called once per process
   // onCmdInit/onCmdExit are called for every command (not for main run())
   // If you want per-run() logic, use the run() handler or global hooks
   ```
@@ -627,7 +627,63 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
 
 ### Launcher Programmatic Execution
 
-For larger CLIs or when you want to programmatically run commands (e.g.: [prompt demo](./example/prompts/mod.ts), tests, etc), you can organize your commands in a `cmds.ts` file and use the `runCmd` utility.
+For larger CLIs or when you want to programmatically run commands (e.g.: [prompt demo](./example/prompts/mod.ts), tests, etc), you can organize your commands in a `cmds.ts` file and use the `runCmd` utility. Example:
+
+```ts
+// example/launcher/app/runcmd/cmd.ts
+
+import { relinka } from "@reliverse/relinka";
+import { defineArgs, defineCommand, runCmd } from "@reliverse/rempts";
+import { cmdMinimal } from "../cmds.js";
+
+export default defineCommand({
+  meta: {
+    name: "runcmd",
+    description:
+      "Demonstrate how to use runCmd() to invoke another command programmatically.",
+  },
+  args: defineArgs({
+    name: {
+      type: "string",
+      description: "your name",
+    },
+  }),
+  async run({ args }) {
+    // const username = args.name ?? "Alice";
+    const username = args.name; // intentionally missing fallback
+    relinka(
+      "info",
+      `Running the 'minimal' command using runCmd() with name='${username}'`,
+    );
+    await runCmd(await cmdMinimal(), ["--name", username]);
+    relinka("log", "Done running 'minimal' via runCmd().");
+  },
+});
+```
+
+```ts
+// example/launcher/app/minimal/cmd.ts
+
+import { relinka } from "@reliverse/relinka";
+import { defineArgs, defineCommand } from "@reliverse/rempts";
+
+export default defineCommand({
+  meta: {
+    name: "minimal",
+    description: "hello world",
+  },
+  args: defineArgs({
+    name: {
+      type: "string",
+      description: "your name",
+      required: true,
+    },
+  }),
+  run({ args }) {
+    relinka("success", `👋 Hello, ${args.name}!`);
+  },
+});
+```
 
 **Pro Tips & Best Practices**:
 
@@ -641,7 +697,7 @@ For larger CLIs or when you want to programmatically run commands (e.g.: [prompt
 ```ts
 // example/launcher/app/cmds.ts
 
-export async function getCmdHooks() {
+export async function cmdHooks() {
   return (await import("./hooks/cmd.js")).default;
 }
 
@@ -657,12 +713,12 @@ Usage:
 ```ts
 // example/prompts/mod.ts
 
-import { getCmdHooks } from "@/launcher/app/cmds.js";
+import { cmdHooks } from "@/launcher/app/cmds.js";
 import { runCmd } from "@reliverse/rempts";
 
-await runCmd(await getCmdHooks(), ["--flag"]);
+await runCmd(await cmdHooks(), ["--flag"]);
 // OR:
-// const hooksCmd = await getCmdHooks();
+// const hooksCmd = await cmdHooks();
 // await runCmd(hooksCmd, ["--flag"]);
 ```
 
@@ -698,7 +754,7 @@ await runCmd(hooksCmd, ["--flag"]); // argv as array of strings
 Or with lazy loading:
 
 ```ts
-const hooksCmd = await getCmdHooks();
+const hooksCmd = await cmdHooks();
 await runCmd(hooksCmd, ["--flag"]);
 ```
 
@@ -711,6 +767,162 @@ await runCmd(hooksCmd, ["--flag"]);
 
 Choose the pattern that best fits your CLI's size and usage!
 
+## Argument Types: Usage Comparison
+
+Below is a demonstration of how to define and use all supported argument types in rempts: positional, boolean, string, number, and array. This includes example CLI invocations and the resulting parsed output.
+
+```ts
+import { defineCommand, runMain } from "@reliverse/rempts";
+
+const main = defineCommand({
+  meta: {
+    name: "mycli",
+    version: "1.0.0",
+    description: "Demo of all argument types",
+  },
+  args: {
+    // Positional argument (required)
+    input: {
+      type: "positional",
+      required: true,
+      description: "Input file path",
+    },
+    // Boolean flag (default: false)
+    verbose: {
+      type: "boolean",
+      default: false,
+      description: "Enable verbose output",
+    },
+    // String option (optional)
+    name: {
+      type: "string",
+      description: "Your name",
+    },
+    // Number option (optional, with default)
+    count: {
+      type: "number",
+      default: 1,
+      description: "How many times to run",
+    },
+    // Array option (can be repeated, accepts any value)
+    tags: {
+      type: "array",
+      default: ["demo"],
+      description: "Tags for this run (repeatable)",
+    },
+  },
+  run({ args }) {
+    console.log("Parsed args:", args);
+  },
+});
+
+await runMain(main);
+```
+
+### Example CLI Invocations
+
+#### 1. Positional argument
+
+```bash
+mycli input.txt
+# → args.input = "input.txt"
+```
+
+#### 2. Boolean flag
+
+```bash
+mycli input.txt --verbose
+# → args.verbose = true
+mycli input.txt --no-verbose
+# → args.verbose = false
+```
+
+#### 3. String option
+
+```bash
+mycli input.txt --name Alice
+# → args.name = "Alice"
+mycli input.txt
+# → args.name = undefined
+```
+
+#### 4. Number option
+
+```bash
+mycli input.txt --count 5
+# → args.count = 5
+mycli input.txt
+# → args.count = 1 (default)
+```
+
+#### 5. Array option (repeatable, accepts any value)
+
+You can provide array values using any of the following syntaxes (mix and match as needed):
+
+- Repeated flags:
+
+  ```bash
+  mycli input.txt --tags foo --tags bar --tags baz
+  # → args.tags = ["foo", "bar", "baz"]
+  ```
+
+- Comma-separated values (with or without spaces):
+
+  ```bash
+  mycli input.txt --tags foo,bar,baz
+  mycli input.txt --tags foo, bar, baz
+  # → args.tags = ["foo", "bar", "baz"]
+  ```
+
+- Bracketed values (must be passed as a single argument!):
+
+  ```bash
+  mycli input.txt --tags "[foo,bar,baz]"
+  # → args.tags = ["foo", "bar", "baz"]
+  ```
+
+- Mix and match:
+
+  ```bash
+  mycli input.txt --tags foo --tags "[bar,bar2,bar3]" --tags baz
+  # → args.tags = ["foo", "bar", "bar2", "bar3", "baz"]
+  ```
+
+> **Important:**
+>
+> - **Quoted values (single or double quotes around elements) are NOT supported and will throw an error.**
+>   - Example: `--tags 'foo'` or `--tags "[\"bar\",'baz']"` will throw an error.
+> - **Bracketed or comma-separated lists must be passed as a single argument.**
+>   - Example: `--tags "[foo,bar]"` (quotes around the whole value, not around elements)
+>   - If you split a bracketed value across arguments, you will get a warning or incorrect parsing.
+> - **Shells remove quotes before passing arguments to the CLI.** If you want to pass a value with commas or brackets, always quote the whole value.
+> - **Troubleshooting:**
+>   - If you see a warning about possible shell splitting, try quoting the whole value: `--tags "[a,b,c]"`
+>   - If you see an error about quoted values, remove quotes around individual elements.
+
+**Example error:**
+
+```bash
+$ bun example/launcher/modern.ts build --entry "[foo.ts," "bar.ts]"
+✖   Don't use quotes around array elements.
+✖   Also — don't use spaces — unless you wrap the whole array in quotes.
+⚠   Array argument --entry: Detected possible shell splitting of bracketed value ('[foo.ts,').
+⚠   If you intended to pass a bracketed list, quote the whole value like: --entry "[a, b, c]"
+```
+
+#### 6. All together
+
+```bash
+mycli input.txt --verbose --name Alice --count 3 --tags foo --tags bar
+# → args = {
+#     input: "input.txt",
+#     verbose: true,
+#     name: "Alice",
+#     count: 3,
+#     tags: ["foo", "bar"]
+#   }
+```
+
 ## Contributing
 
 Bug report? Prompt idea? Want to build the best DX possible?

package/bin/components/launcher/launcher-mod.d.ts

@@ -1,8 +1,4 @@
 import type { ReliArgParserOptions } from "@reliverse/reliarg";
-type InvalidDefaultError<O extends readonly string[]> = {
-    __error__: "Default value(s) must be a subset of options";
-    options: O;
-};
 type EmptyArgs = Record<string, never>;
 type BaseArgProps = {
     description?: string;
@@ -27,7 +23,6 @@ type NumberArgDefinition = {
 type ArrayArgDefinition = {
     type: "array";
     default?: string | readonly string[];
-    options: readonly string[];
 } & BaseArgProps;
 export type ArgDefinition = PositionalArgDefinition | BooleanArgDefinition | StringArgDefinition | NumberArgDefinition | ArrayArgDefinition;
 export type ArgDefinitions = Record<string, ArgDefinition>;
@@ -85,11 +80,11 @@ type DefineCommandOptions<A extends ArgDefinitions = EmptyArgs> = {
     /**
      * Called once per CLI process, before any command/run() is executed
      */
-    onLauncherStart?: () => void | Promise<void>;
+    onLauncherInit?: () => void | Promise<void>;
     /**
      * Called once per CLI process, after all command/run() logic is finished
      */
-    onLauncherEnd?: () => void | Promise<void>;
+    onLauncherExit?: () => void | Promise<void>;
 };
 export type Command<A extends ArgDefinitions = EmptyArgs> = {
     meta?: CommandMeta;
@@ -122,28 +117,16 @@ export type Command<A extends ArgDefinitions = EmptyArgs> = {
     /**
      * Called once per CLI process, before any command/run() is executed
      */
-    onLauncherStart?: () => void | Promise<void>;
+    onLauncherInit?: () => void | Promise<void>;
     /**
      * Called once per CLI process, after all command/run() logic is finished
      */
-    onLauncherEnd?: () => void | Promise<void>;
+    onLauncherExit?: () => void | Promise<void>;
 };
 export type InferArgTypes<A extends ArgDefinitions> = {
     [K in keyof A]: A[K] extends PositionalArgDefinition ? string : A[K] extends BooleanArgDefinition ? boolean : A[K] extends StringArgDefinition ? string : A[K] extends NumberArgDefinition ? number : A[K] extends {
         type: "array";
-        options: infer O extends readonly string[];
-    } ? O[number][] : never;
-};
-type ValidateArrayDefaults<A extends ArgDefinitions> = {
-    [K in keyof A]: A[K] extends {
-        type: "array";
-        options: infer O extends readonly string[];
-        default?: infer D;
-    } ? D extends undefined ? A[K] : D extends O[number] ? A[K] : D extends readonly (infer E)[] ? E extends O[number] ? A[K] : Omit<A[K], "default"> & {
-        default: InvalidDefaultError<O>;
-    } : Omit<A[K], "default"> & {
-        default: InvalidDefaultError<O>;
-    } : A[K];
+    } ? string[] : never;
 };
 export type FileBasedCmdsOptions = {
     enable: boolean;
@@ -187,11 +170,8 @@ export declare function runMain<A extends ArgDefinitions = EmptyArgs>(command: C
 /**
  * Helper to define argument definitions with improved type inference
  * for IntelliSense and validation for array defaults against options.
- *
- * **Note:** For array types, use `as const` on the `options` array to enable
- * precise default value validation (e.g., `options: ["a", "b"] as const`).
  */
-export declare function defineArgs<A extends ArgDefinitions>(args: A & ValidateArrayDefaults<A>): A;
+export declare function defineArgs<A extends ArgDefinitions>(args: A): A;
 /**
  * Programmatically run a command's run() handler with parsed arguments.
  * Does not handle subcommands, file-based commands, or global hooks.

package/bin/components/launcher/launcher-mod.js

@@ -36,11 +36,7 @@ function buildExampleArgs(args) {
           parts.push(`--${key}=${String(def.default ?? 42)}`);
           break;
         case "array":
-          if (def.options && def.options.length > 0) {
-            parts.push(`--${key}=${String(def.options[0])}`);
-          } else {
-            parts.push(`--${key}=${String(key)}`);
-          }
+          parts.push(`--${key}=${String(def.default ?? key)}`);
           break;
       }
     }
@@ -59,8 +55,8 @@ function isFlag(str) {
 export function defineCommand(options) {
   const onCmdInit = options.onCmdInit || options.setup;
   const onCmdExit = options.onCmdExit || options.cleanup;
-  const onLauncherStart = options.onLauncherStart;
-  const onLauncherEnd = options.onLauncherEnd;
+  const onLauncherInit = options.onLauncherInit;
+  const onLauncherExit = options.onLauncherExit;
   let commands = options.commands;
   if (!commands) {
     commands = options.subCommands;
@@ -72,8 +68,8 @@ export function defineCommand(options) {
     commands,
     onCmdInit,
     onCmdExit,
-    onLauncherStart,
-    onLauncherEnd,
+    onLauncherInit,
+    onLauncherExit,
     // Backward-compatible aliases
     setup: onCmdInit,
     cleanup: onCmdExit
@@ -245,15 +241,13 @@ export async function showUsage(command, parserOptions = {}) {
       if (def.default !== void 0)
         parts.push(`default=${JSON.stringify(def.default)}`);
       if (def.required) parts.push("required");
-      if (def.type === "array" && def.options)
-        parts.push(`options: ${def.options.join(", ")}`);
       relinka("log", parts.filter(Boolean).join(" | "));
     }
   }
 }
 export async function runMain(command, parserOptions = {}) {
-  if (typeof command.onLauncherStart === "function")
-    await command.onLauncherStart();
+  if (typeof command.onLauncherInit === "function")
+    await command.onLauncherInit();
   try {
     if (!parserOptions.fileBasedCmds && !command.commands) {
       let callerDir = process.cwd();
@@ -430,8 +424,8 @@ This can cause recursion or unexpected behavior.`
     }
     await relinkaShutdown();
   } finally {
-    if (typeof command.onLauncherEnd === "function")
-      await command.onLauncherEnd();
+    if (typeof command.onLauncherExit === "function")
+      await command.onLauncherExit();
   }
 }
 function checkHelp(argv) {
@@ -583,8 +577,8 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
     const def = command.args?.[key];
     const val = leftoverPositionals[i];
     if (val == null && def.required) {
-      relinka("error", `Missing required positional argument: <${key}>`);
       await showUsage(command, parserOptions);
+      relinka("error", `Missing required positional argument: <${key}>`);
       if (autoExit) process.exit(1);
       else throw new Error(`Missing required positional argument: <${key}>`);
     }
@@ -601,8 +595,8 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
     }
     const valueOrDefault = rawVal ?? defaultMap[key];
     if (valueOrDefault == null && def.required) {
-      relinka("error", `Missing required argument: --${key}`);
       await showUsage(command, parserOptions);
+      relinka("error", `Missing required argument: --${key}`);
       if (autoExit) process.exit(1);
       else throw new Error(`Missing required argument: --${key}`);
     }
@@ -612,17 +606,6 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
       } else {
         finalArgs[key] = castArgValue(def, rawVal, key);
       }
-      if (def.type === "array" && def.options && finalArgs[key]) {
-        const values = finalArgs[key];
-        const invalidOptions = values.filter(
-          (v) => def.options && !def.options.includes(v)
-        );
-        if (invalidOptions.length > 0) {
-          throw new Error(
-            `Invalid choice(s) for --${key}: ${invalidOptions.join(", ")}. Allowed options: ${def.options.join(", ")}`
-          );
-        }
-      }
     } catch (err) {
       relinka("error", String(err));
       if (autoExit) process.exit(1);
@@ -647,8 +630,8 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
       }
       const cmdName = command.meta?.name || "unknown";
       const attempted = argv.length > 0 ? argv.join(" ") : "(no arguments)";
-      relinka("error", `Unknown command or arguments: ${attempted}`);
       await showUsage(command, parserOptions);
+      relinka("error", `Unknown command or arguments: ${attempted}`);
       if (autoExit) {
         process.exit(1);
       } else {
@@ -692,7 +675,40 @@ function castArgValue(def, rawVal, argName) {
       return String(rawVal);
     case "array": {
       const arrVal = Array.isArray(rawVal) ? rawVal : [String(rawVal)];
-      return arrVal.map(String);
+      const result = [];
+      const arrValStr = arrVal.map(String);
+      let warned = false;
+      for (let v of arrValStr) {
+        if (!warned && (v.startsWith("[") && !v.endsWith("]") || !v.startsWith("[") && v.endsWith("]"))) {
+          relinka("error", `Don't use quotes around array elements.`);
+          relinka(
+            "error",
+            `Also \u2014 don't use spaces \u2014 unless you wrap the whole array in quotes.`
+          );
+          relinka(
+            "warn",
+            `Array argument --${argName}: Detected possible shell splitting of bracketed value ('${v}').`
+          );
+          relinka(
+            "warn",
+            `If you intended to pass a bracketed list, quote the whole value like: --${argName} "[a, b, c]"`
+          );
+        }
+        warned = true;
+        if (v.startsWith("[") && v.endsWith("]")) {
+          v = v.slice(1, -1);
+        }
+        const parts = v.split(/\s*,\s*/).filter(Boolean);
+        parts.forEach((p) => {
+          if (p.startsWith('"') && p.endsWith('"') || p.startsWith("'") && p.endsWith("'")) {
+            throw new Error(
+              `Array argument --${argName}: Quoted values are not supported due to shell parsing limitations. Please avoid using single or double quotes around array elements.`
+            );
+          }
+        });
+        result.push(...parts);
+      }
+      return result;
     }
     default:
       return rawVal;
@@ -757,17 +773,15 @@ export async function runCmd(command, argv = [], parserOptions = {}) {
     if (valueOrDefault == null && def.required) {
       throw new Error(`Missing required argument: --${key}`);
     }
-    finalArgs[key] = castArgValue(def, rawVal, key);
-    if (def.type === "array" && def.options && finalArgs[key]) {
-      const values = finalArgs[key];
-      const invalidOptions = values.filter(
-        (v) => def.options && !def.options.includes(v)
-      );
-      if (invalidOptions.length > 0) {
-        throw new Error(
-          `Invalid choice(s) for --${key}: ${invalidOptions.join(", ")}. Allowed options: ${def.options.join(", ")}`
-        );
+    try {
+      if (def.type === "boolean") {
+        finalArgs[key] = rawVal !== void 0 ? castArgValue(def, rawVal, key) : false;
+      } else {
+        finalArgs[key] = castArgValue(def, rawVal, key);
       }
+    } catch (err) {
+      relinka("error", String(err));
+      throw err;
     }
   }
   const ctx = {

package/package.json

@@ -28,7 +28,7 @@
   "license": "MIT",
   "name": "@reliverse/rempts",
   "type": "module",
-  "version": "1.7.7",
+  "version": "1.7.8",
   "author": "reliverse",
   "bugs": {
     "email": "blefnk@gmail.com",