@reliverse/rempts 1.7.38 → 1.7.40

package/README.md

@@ -1,9 +1,9 @@
 # 📃 rempts • powerful js/ts cli builder
 
-> @reliverse/rempts is a modern, type-safe toolkit for building delightful cli experiences. it's fast, flexible, and made for developer happiness. file-based commands keep things simple—no clutter, just clean and easy workflows. this is how cli should feel.
-
 [sponsor](https://github.com/sponsors/blefnk) — [discord](https://discord.gg/Pb8uKbwpsJ) — [repo](https://github.com/reliverse/rempts) — [npm](https://npmjs.com/@reliverse/rempts)
 
+> @reliverse/rempts is a modern, type-safe toolkit for building delightful cli experiences. it's fast, flexible, and made for developer happiness. file-based commands keep things simple—no clutter, just clean and easy workflows. this is how cli should feel.
+
 ## Features
 
 - 😘 drop-in to libraries like `unjs/citty` and `@clack/prompts`
@@ -36,14 +36,6 @@
 bun add @reliverse/rempts
 ```
 
-**Coming soon**:
-
-```bash
-bun add -D @reliverse/dler
-bun dler rempts --init cmd1 cmd2 # creates `src/app/cmd1/cmd.ts` and `src/app/cmd2/cmd.ts` files
-bun dler rempts # creates `src/app/cmds.ts` file
-```
-
 ## Usage Examples
 
 - [Prompts](#prompts)
@@ -222,6 +214,14 @@ await main();
 
 > **Note**: `runMain` is now an alias for `createCli` and is still supported for backward compatibility. The new `createCli` API provides a more intuitive object-based configuration format.
 
+### Automatic command creation
+
+```bash
+bun add -D @reliverse/dler
+bun dler rempts --init cmd1 cmd2 # creates `src/app/cmd1/cmd.ts` and `src/app/cmd2/cmd.ts` files
+bun dler rempts # creates `src/app/cmds.ts` file
+```
+
 ### Terminology
 
 - **Launcher/Router**: The main entry point for your CLI. Visit [CLI Launcher (Router)](#cli-launcher-router) section to learn more.
@@ -837,6 +837,37 @@ export default defineCommand({
 });
 ```
 
+### Using `runCmd` with Flexible Argument Handling
+
+The `runCmd` function supports flexible argument passing, automatically normalizing template literals and space-separated strings:
+
+```ts
+import { runCmd } from "@reliverse/rempts";
+
+// Traditional way - each argument as separate array element
+await runCmd(cmd, ["--dev", "true", "--name", "John"]);
+
+// Template literals work automatically
+await runCmd(cmd, [`--dev ${isDev}`]); // Automatically converted to ["--dev", "true"]
+await runCmd(cmd, [`--dev ${isDev} --build mod.ts`]); // ["--dev", "true", "--build", "mod.ts"]
+
+// Mixed arrays with template literals and regular strings
+await runCmd(cmd, [
+  `--dev ${isDev} --build mod.ts`,
+  "--pub true",
+  "--someBoolean",
+]);
+
+// Multiple template literals
+await runCmd(cmd, [`--dev ${isDev}`, `--name ${userName}`, `--count ${count}`]);
+```
+
+**Remember**:
+
+- If you need to pass a value with spaces (e.g. a name like "John Doe"), you should quote it in your template literal: `await runCmd(cmd, ['--name "John Doe"']);`
+- Otherwise, it will be split into two arguments: `"John"` and `"Doe"`.
+- We do not handle this intentionally, because some library users might rely on this Node.js behavior and handle it themselves in their own way (e.g. space can serve as a separator for values).
+
 ### Loading Commands with `loadCommand`
 
 The `loadCommand` utility helps you load command files from your filesystem. It automatically handles:
@@ -926,6 +957,37 @@ export default defineCommand({
 });
 ```
 
+### Using `runCmdWithSubcommands` for Subcommands and Nested Subcommands
+
+If you need to programmatically run commands that support subcommands (including nested subcommands), use `runCmdWithSubcommands`:
+
+```ts
+import { runCmdWithSubcommands } from "@reliverse/rempts";
+
+// Single-level subcommand
+await runCmdWithSubcommands(mainCmd, [`build --input src/mod.ts --someBoolean`]);
+
+// Subcommand with positional arguments
+await runCmdWithSubcommands(mainCmd, [`build src/mod.ts --someBoolean`]);
+
+// Nested subcommands
+await runCmdWithSubcommands(mainCmd, [`build someSubCmd src/mod.ts --no-cjs`]);
+await runCmdWithSubcommands(mainCmd, [`build sub1 sub2 sub3 file.ts --flag`]);
+
+// Mixed array with subcommands
+await runCmdWithSubcommands(mainCmd, [
+  `build someSubCmd src/mod.ts`,
+  "--no-cjs",
+  "--verbose"
+]);
+```
+
+**Note:**
+
+- `runCmdWithSubcommands` automatically normalizes template literals and space-separated strings, just like `runCmd`.
+- If you need to pass a value with spaces (e.g. a name like "John Doe"), you should quote it in your template literal: `await runCmdWithSubcommands(cmd, ['--name "John Doe"']);`
+- For subcommands, always use `runCmdWithSubcommands` for the most robust behavior.
+
 ## 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.
@@ -1179,6 +1241,7 @@ All APIs are fully typed. See [`src/types.ts`](./src/types.ts) for advanced cust
 ## TODO
 
 - [ ] migrate to `dler libs` in the future (all main components will be published as separate packages; `@reliverse/rempts` will be a wrapper for all of them)
+- [ ] migrate all tests to `bun:test`
 
 ## Related
 

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

@@ -102,13 +102,61 @@ export declare function createCli<A extends ArgDefinitions = EmptyArgs>(options:
  * for IntelliSense and validation for array defaults against options.
  */
 export declare function defineArgs<A extends ArgDefinitions>(args: A): A;
+/**
+ * Programmatically run a command with subcommand support and flexible argument handling.
+ * This function can handle subcommands (including nested), positional arguments, and automatically normalizes
+ * template literals and space-separated strings.
+ *
+ * @param command The command definition (from defineCommand)
+ * @param argv The argv array to parse (default: []). Supports template literals and subcommands.
+ * @param parserOptions Optional reliArgParser options
+ *
+ * @example
+ * ```ts
+ * // ✅ Single command with template literals
+ * await runCmdWithSubcommands(cmd, [`--dev ${isDev}`]);
+ *
+ * // ✅ Subcommand with arguments
+ * await runCmdWithSubcommands(cmd, [`build --input src/mod.ts --someBoolean`]);
+ *
+ * // ✅ Subcommand with positional arguments
+ * await runCmdWithSubcommands(cmd, [`build src/mod.ts --someBoolean`]);
+ *
+ * // ✅ Nested subcommands
+ * await runCmdWithSubcommands(cmd, [`build someSubCmd src/mod.ts --no-cjs`]);
+ * await runCmdWithSubcommands(cmd, [`build sub1 sub2 sub3 file.ts --flag`]);
+ *
+ * // ✅ Mixed array with subcommands
+ * await runCmdWithSubcommands(cmd, [
+ *   `build someSubCmd src/mod.ts`,
+ *   "--no-cjs",
+ *   "--verbose"
+ * ]);
+ * ```
+ */
+export declare function runCmdWithSubcommands<A extends ArgDefinitions = EmptyArgs>(command: Command<A>, argv?: string[], parserOptions?: ReliArgParserOptions & {
+    fileBased?: FileBasedOptions;
+    autoExit?: boolean;
+}): Promise<any>;
 /**
  * Programmatically run a command's run() handler with parsed arguments.
  * Does not handle subcommands, file-based commands, or global hooks.
  * Suitable for use in demos, tests, or programmatic invocation.
  *
  * @param command The command definition (from defineCommand)
- * @param argv The argv array to parse (default: [])
+ * @param argv The argv array to parse (default: []). Each argument should be a separate array element.
  * @param parserOptions Optional reliArgParser options
+ *
+ * @example
+ * **each argument as separate array element**:
+ * ```ts
+ * await runCmd(cmd, ["--dev", "true"]);
+ * await runCmd(cmd, ["--name", "John", "--verbose"]);
+ * ```
+ * **automatic normalization of template literals**:
+ * ```ts
+ * await runCmd(cmd, [`--dev ${isDev}`]); // Automatically converted to ["--dev", "true"]
+ * await runCmd(cmd, [`--dev ${isDev} --build mod.ts`]); // ["--dev", "true", "--build", "mod.ts"]
+ * ```
  */
 export declare function runCmd<A extends ArgDefinitions = EmptyArgs>(command: Command<A>, argv?: string[], parserOptions?: ReliArgParserOptions): Promise<void>;

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

@@ -1002,7 +1002,49 @@ function renderPositional(args) {
 export function defineArgs(args) {
   return args;
 }
+function normalizeArgv(argv) {
+  const normalized = [];
+  for (const arg of argv) {
+    const parts = arg.split(/\s+/).filter((part) => part.length > 0);
+    normalized.push(...parts);
+  }
+  return normalized;
+}
+export async function runCmdWithSubcommands(command, argv = [], parserOptions = {}) {
+  const normalizedArgv = normalizeArgv(argv);
+  let currentCommand = command;
+  let currentArgv = normalizedArgv;
+  while (currentCommand.commands && currentArgv.length > 0 && currentArgv[0] && !isFlag(currentArgv[0])) {
+    const [maybeSub, ...restArgv] = currentArgv;
+    let subSpec;
+    for (const [key, spec] of Object.entries(currentCommand.commands)) {
+      if (key === maybeSub) {
+        subSpec = spec;
+        break;
+      }
+      try {
+        const cmd = await loadSubCommand(spec);
+        if (cmd.meta?.aliases?.includes(maybeSub)) {
+          subSpec = spec;
+          break;
+        }
+      } catch (err) {
+        debugLog(`Error checking alias for command ${key}:`, err);
+      }
+    }
+    if (!subSpec) break;
+    const loaded = await loadSubCommand(subSpec);
+    currentCommand = loaded;
+    currentArgv = restArgv;
+  }
+  return await runCommandWithArgs(currentCommand, currentArgv, {
+    ...parserOptions,
+    autoExit: false
+    // Don't exit process in programmatic usage
+  });
+}
 export async function runCmd(command, argv = [], parserOptions = {}) {
+  const normalizedArgv = normalizeArgv(argv);
   const booleanKeys = Object.keys(command.args || {}).filter(
     (k) => command.args?.[k]?.type === "boolean"
   );
@@ -1019,7 +1061,7 @@ export async function runCmd(command, argv = [], parserOptions = {}) {
     boolean: [...parserOptions.boolean || [], ...booleanKeys],
     defaults: { ...defaultMap, ...parserOptions.defaults || {} }
   };
-  const parsed = reliArgParser(argv, mergedParserOptions);
+  const parsed = reliArgParser(normalizedArgv, mergedParserOptions);
   debugLog("Parsed arguments (runCmd):", parsed);
   const finalArgs = {};
   const positionalKeys = Object.keys(command.args || {}).filter(
@@ -1073,6 +1115,7 @@ export async function runCmd(command, argv = [], parserOptions = {}) {
   }
 }
 function getParsedContext(command, argv, parserOptions) {
+  const normalizedArgv = normalizeArgv(argv);
   const booleanKeys = Object.keys(command.args || {}).filter(
     (k) => command.args?.[k]?.type === "boolean"
   );
@@ -1089,7 +1132,7 @@ function getParsedContext(command, argv, parserOptions) {
     boolean: [...parserOptions.boolean || [], ...booleanKeys],
     defaults: { ...defaultMap, ...parserOptions.defaults || {} }
   };
-  const parsed = reliArgParser(argv, mergedParserOptions);
+  const parsed = reliArgParser(normalizedArgv, mergedParserOptions);
   const finalArgs = {};
   const positionalKeys = Object.keys(command.args || {}).filter(
     (k) => command.args?.[k]?.type === "positional"

package/bin/libs/launcher/run-command.d.ts

@@ -1,2 +1,18 @@
 import type { Command } from "./launcher-types.js";
+/**
+ * Load a command from the filesystem.
+ *
+ * @param cmdPath - Path to the command file or directory containing cmd.ts/cmd.js
+ * @returns Promise<Command> - The loaded command
+ *
+ * @example
+ * ```ts
+ * // Load a command
+ * const cmd = await loadCommand("./web/cmd");
+ *
+ * // Use with runCmd - pass args as separate array elements
+ * await runCmd(cmd, ["--dev", "true"]); // ✅ Correct
+ * await runCmd(cmd, [`--dev ${isDev}`]); // ❌ Wrong - creates single string
+ * ```
+ */
 export declare function loadCommand(cmdPath: string): Promise<Command>;

package/bin/libs/launcher/run-command.js

@@ -23,9 +23,7 @@ const getCallerDirectory = () => {
 const tryLoadCommand = async (path) => {
   if (!await fs.pathExists(path)) return null;
   try {
-    relinka("verbose", `Attempting to load command from: ${path}`);
     const cmd = await jiti.import(path, { default: true });
-    relinka("verbose", `Successfully loaded command from: ${path}`);
     return cmd;
   } catch {
     relinka("verbose", `Failed to load ${path} as a command file`);

package/bin/mod.d.ts

@@ -14,7 +14,7 @@ export { inputPrompt } from "./libs/input/input-mod.js";
 export { startPrompt, intro } from "./libs/intro/intro-alias.js";
 export { introPrompt } from "./libs/intro/intro-mod.js";
 export { runMain } from "./libs/launcher/launcher-alias.js";
-export { defineCommand, showUsage, createCli, defineArgs, runCmd, } from "./libs/launcher/launcher-mod.js";
+export { defineCommand, showUsage, createCli, defineArgs, runCmd, runCmdWithSubcommands, } from "./libs/launcher/launcher-mod.js";
 export type { EmptyArgs, BaseArgProps, BaseArgDefinition, PositionalArgDefinition, BooleanArgDefinition, StringArgDefinition, NumberArgDefinition, ArrayArgDefinition, ArgDefinition, ArgDefinitions, CommandMeta, CommandSpec, CommandsMap, CommandContext, CommandRun, CommandHook, DefineCommandOptions, Command, InferArgTypes, FileBasedOptions, } from "./libs/launcher/launcher-types.js";
 export { loadCommand } from "./libs/launcher/run-command.js";
 export { addCompletions } from "./libs/launcher/trpc-orpc-support/completions.js";

package/bin/mod.js

@@ -30,7 +30,8 @@ export {
   showUsage,
   createCli,
   defineArgs,
-  runCmd
+  runCmd,
+  runCmdWithSubcommands
 } from "./libs/launcher/launcher-mod.js";
 export { loadCommand } from "./libs/launcher/run-command.js";
 export { addCompletions } from "./libs/launcher/trpc-orpc-support/completions.js";

package/package.json

@@ -8,7 +8,7 @@
     "@reliverse/reliarg": "^1.0.3",
     "@reliverse/relico": "^1.1.2",
     "@reliverse/relifso": "^1.4.5",
-    "@reliverse/relinka": "^1.5.2",
+    "@reliverse/relinka": "^1.5.3",
     "@reliverse/runtime": "^1.0.3",
     "@trpc/server": "^11.4.2",
     "ansi-escapes": "^7.0.0",
@@ -44,7 +44,7 @@
   "license": "MIT",
   "name": "@reliverse/rempts",
   "type": "module",
-  "version": "1.7.38",
+  "version": "1.7.40",
   "author": "reliverse",
   "bugs": {
     "email": "blefnk@gmail.com",