@reliverse/rempts 1.7.4 → 1.7.6

package/README.md

@@ -1,4 +1,4 @@
-# rempts • powerful js/ts cli builder
+# 📃 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.
 
@@ -6,20 +6,25 @@
 
 ## Features
 
-- 🫂 Rempts prevents you from fighting with your CLI tool
-- ✨ Rempts is your end-to-end CLI UI + command framework
-- 💪 Made for DX precision and high-context terminal UX
-- 📂 File-based commands (app router style by default)
-- 🏎️ Prompt engine that *feels* modern, actually is
-- 🧠 Type-safe from args to prompts
-- ⚡ Blazing-fast, no runtime baggage
-- 🧩 Router + argument parser built-in
-- 🎨 Customizable themes, styled output
-- 🚨 Crash-safe (Ctrl+C, SIGINT, errors)
-- 🪄 Minimal API surface, max expressiveness
-- 🧪 Scriptable for testing, stable for production
-- 🆕 Automatic commands creation (via `dler rempts init --cmd my-cool-cmd`)
-- 🏞️ No more hacking together `inquirer`, `citty`, `commander`, `chalk`
+- 🫂 rempts keeps you from fighting with your CLI tool
+- ✨ rempts is your end-to-end CLI UI + command framework
+- 🌿 multi-level file-based subcommands (sibling + nested)
+- 💪 built for DX precision and high-context terminal UX
+- 🏎️ prompt engine that *feels* modern — and actually is
+- 📂 file-based commands (app-router style by default)
+- 🎭 looks great in plain scripts or full CLI apps
+- 🧠 type-safe from args to prompts
+- ⚡ blazing-fast, zero runtime baggage
+- 🧩 router + argument parser built-in
+- 🎨 customizable themes and styled output
+- 📦 built-in output formatter and logger
+- 🚨 crash-safe (Ctrl+C, SIGINT, errors)
+- 📐 smart layout for small terminals
+- 🎛️ override styles via prompt options
+- 🪄 minimal API surface, maximum expressiveness
+- 🧪 scriptable for testing, stable for production
+- 🏞️ no more hacking together `inquirer`/`citty`/`commander`/`chalk`
+- 🆕 automatic command creation (`bun dler rempts init --cmd my-cmd`)
 
 ## Installation
 
@@ -30,9 +35,9 @@ bun add @reliverse/rempts
 **Coming soon**:
 
 ```bash
-bun i -g @reliverse/dler
-dler rempts init --cmd my-cmd-1
-dler rempts init --cmds
+bun add -D @reliverse/dler
+bun dler rempts init --cmd my-cmd-1
+bun dler rempts init --cmds
 ```
 
 ## Usage Examples
@@ -217,14 +222,15 @@ export default defineCommand({
 - `arg-cmdName.{ts,js}`,
 - `cmdName/index.{ts,js}`,
 - `cmdName/cmdName-mod.{ts,js}`,
+- **Multi-level subcommands:** `foo/bar/baz/cmd.ts` → `my-cli foo bar baz`
 - And more — with automatic usage output.
 
 **Hint**:
 
 - Install `bun add -D @reliverse/dler`
-- Use `dler rempts init --cmd cmd1 cmd2` to init commands for rempts launcher's automatically
+- Use `bun dler rempts init --cmd cmd1 cmd2` to init commands for rempts launcher's automatically
 
-### Advanced Minimal API
+### Advanced Launcher Usage
 
 ```ts
 defineCommand({
@@ -247,21 +253,31 @@ defineCommand({
 - Default values, validations, descriptions
 - Full help rendering from metadata
 
-### Theming + Customization
+**By the way! Multi-level subcommands!**
 
-- Built-in output formatter and logger
-- Override styles via prompt options
-- Smart layout for small terminals
-- Looks great in plain scripts or full CLI apps
+You can also nest subcommands arbitrarily deep:
 
-### Playground
+```bash
+app/
+  foo/
+    bar/
+      baz/
+        cmd.ts
+```
+
+Invoke with:
 
 ```bash
-bun i -g @reliverse/rempts-cli
-rempts examples # supported options: name
+my-cli foo bar baz --some-flag
 ```
 
-OR:
+The launcher will recursively traverse subfolders for each non-flag argument, loading the deepest `cmd.ts`/`cmd.js` it finds, and passing the remaining arguments to it.
+
+See [example/launcher/app/nested](./example/launcher/app/nested/) and [example/launcher/app/sibling](./example/launcher/app/sibling/) folders to learn more.
+
+When playing with the example, you can run e.g. `bun dev:modern nested foo bar baz` to see the result in action.
+
+### Playground
 
 ```bash
 git clone https://github.com/reliverse/rempts
@@ -270,8 +286,9 @@ bun i
 bun dev # supported options: name
 ```
 
-- Both `rempts examples` from @reliverse/rempts and `bun dev` (which is the same thing) are themselves examples of `launcher` functionality.
-- This launcher will show you a `multiselectPrompt()` where you can choose which CLI prompts you want to play with.
+- `bun dev:prompts`: This example will show you a `multiselectPrompt()` where you can choose which CLI prompts you want to play with.
+- `bun dev:modern`: This example will show you a modern CLI launcher usage with file-based commands.
+- `bun dev:classic`: This example will show you a classic CLI launcher usage with programmatic commands.
 
 ### Launcher Usage Examples
 
@@ -288,7 +305,7 @@ await runMain(defineCommand({}));
 **2 Run the following:**
 
 ```bash
-bun add -D @reliverse/dler # or: bun i -g @reliverse/dler
+bun add -D @reliverse/dler
 bun dler rempts init --cmd my-cmd-1 # or: dler rempts init my-cmd-1 my-cmd-2 --main src/mod.ts
 # * `--main` is optional, default is `./src/mod.ts`
 # * you can specify multiple commands at once

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

@@ -163,7 +163,10 @@ export declare function showUsage<A extends ArgDefinitions>(command: Command<A>,
     metaSettings?: {
         showDescriptionOnMain?: boolean;
     };
-}, displayNotFoundMessage?: boolean): Promise<void>;
+    _fileBasedCurrentDir?: string;
+    _fileBasedPathSegments?: string[];
+    _isSubcommand?: boolean;
+}): Promise<void>;
 /**
  * Primary entry point to run a command. This function supports:
  *

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

@@ -105,11 +105,34 @@ async function getDefaultCliNameAndVersion() {
     return { name: "cli", version: void 0 };
   }
 }
-export async function showUsage(command, parserOptions = {}, displayNotFoundMessage) {
+async function findDirectFileBasedSubcommands(currentDir) {
+  const results = [];
+  const items = await fs.readdir(currentDir, { withFileTypes: true });
+  for (const dirent of items) {
+    if (dirent.isDirectory()) {
+      for (const fname of ["cmd.ts", "cmd.js"]) {
+        const fpath = path.join(currentDir, dirent.name, fname);
+        if (await fs.pathExists(fpath)) {
+          try {
+            const imported = await import(path.resolve(fpath));
+            if (imported.default && !imported.default.meta?.hidden) {
+              results.push({ name: dirent.name, def: imported.default });
+            }
+          } catch (err) {
+            debugLog(`Skipping file-based subcommand in ${fpath}:`, err);
+          }
+          break;
+        }
+      }
+    }
+  }
+  return results;
+}
+export async function showUsage(command, parserOptions = {}) {
   const { name: fallbackName, version: fallbackVersion } = await getDefaultCliNameAndVersion();
   const cliName = command.meta?.name || fallbackName;
   const cliVersion = command.meta?.version || fallbackVersion;
-  relinka("log", `${cliName}${cliVersion ? ` v${cliVersion}` : ""}`);
+  relinka("info", `${cliName}${cliVersion ? ` v${cliVersion}` : ""}`);
   if (parserOptions.metaSettings?.showDescriptionOnMain) {
     let description = command.meta?.description;
     if (!description) {
@@ -123,64 +146,40 @@ export async function showUsage(command, parserOptions = {}, displayNotFoundMess
       relinka("log", description);
     }
   }
+  const { name: pkgName } = await getDefaultCliNameAndVersion();
   const fileCmds = parserOptions.fileBasedCmds;
   if (fileCmds?.enable) {
-    const usageLine = `Usage: ${cliName} <command> [command's options]`;
-    relinka("log", usageLine);
-    try {
-      const commandsDir = path.resolve(fileCmds.cmdsRootPath);
-      const items = await fs.readdir(commandsDir, {
-        withFileTypes: true
-      });
-      const subCommandNames = [];
-      const subCommandDefs = [];
-      for (const dirent of items) {
-        if (dirent.isDirectory()) {
-          const name = dirent.name;
-          const cmdTs = path.join(commandsDir, name, "cmd.ts");
-          const cmdJs = path.join(commandsDir, name, "cmd.js");
-          let imported;
-          try {
-            if (await fs.pathExists(cmdTs)) {
-              imported = await import(path.resolve(cmdTs));
-            } else if (await fs.pathExists(cmdJs)) {
-              imported = await import(path.resolve(cmdJs));
-            } else {
-              continue;
-            }
-            if (imported.default && !imported.default.meta?.hidden) {
-              subCommandNames.push(name);
-              subCommandDefs.push({ name, def: imported.default });
-            }
-          } catch (err) {
-            debugLog(`Skipping file-based subcommand in ${name}:`, err);
-          }
-        }
-      }
-      if (subCommandDefs.length > 0) {
-        const randomIdx = Math.floor(Math.random() * subCommandDefs.length);
-        const { name: exampleCmd, def: exampleDef } = subCommandDefs[randomIdx];
-        const exampleArgs = buildExampleArgs(exampleDef.args || {});
+    const commandsDir = path.resolve(fileCmds.cmdsRootPath);
+    const currentDir = parserOptions._fileBasedCurrentDir || commandsDir;
+    const pathSegments = parserOptions._fileBasedPathSegments || [];
+    let usageLine = [pkgName, ...pathSegments].join(" ");
+    const directSubs = await findDirectFileBasedSubcommands(currentDir);
+    if (directSubs.length > 0) {
+      usageLine += " <command> [command's options]";
+    } else {
+      usageLine += " [command's options]";
+      const pos = renderPositional(command.args);
+      if (pos) usageLine += ` ${pos}`;
+    }
+    relinka("log", `Usage: ${usageLine}`);
+    if (directSubs.length > 0) {
+      const randomIdx = Math.floor(Math.random() * directSubs.length);
+      const { name: exampleCmd, def: exampleDef } = directSubs[randomIdx];
+      const exampleArgs = buildExampleArgs(exampleDef.args || {});
+      relinka(
+        "log",
+        `Example: ${pkgName} ${[...pathSegments, exampleCmd].join(" ")}${exampleArgs ? ` ${exampleArgs}` : ""}`
+      );
+    }
+    if (directSubs.length > 0) {
+      relinka("info", "Available commands (run with `help` to see more):");
+      directSubs.forEach(({ name, def }) => {
+        const desc = def?.meta?.description ?? "";
         relinka(
           "log",
-          `Example: ${cliName} ${exampleCmd}${exampleArgs ? ` ${exampleArgs}` : ""}`
+          `\u2022 ${[...pathSegments, name].join(" ")}${desc ? ` | ${desc}` : ""}`
         );
-      }
-      if (subCommandNames.length > 0) {
-        relinka("info", "Available commands (run with `help` to see more):");
-        subCommandDefs.forEach(({ name, def }) => {
-          const desc = def?.meta?.description ?? "";
-          relinka("log", `\u2022 ${name}${desc ? ` | ${desc}` : ""}`);
-        });
-      }
-    } catch (err) {
-      if (displayNotFoundMessage) {
-        relinka(
-          "warn",
-          `No file-based subcommands found in ${fileCmds.cmdsRootPath}`
-        );
-      }
-      debugLog("Error reading file-based commands:", err);
+      });
     }
   } else {
     const subCommandNames = [];
@@ -200,7 +199,10 @@ export async function showUsage(command, parserOptions = {}, displayNotFoundMess
         }
       }
     }
-    let usageLine = cliName;
+    let usageLine = pkgName;
+    if (parserOptions._isSubcommand) {
+      usageLine += ` ${cliName}`;
+    }
     if (subCommandNames.length > 0) {
       usageLine += " <command> [command's options]";
     } else {
@@ -213,7 +215,7 @@ export async function showUsage(command, parserOptions = {}, displayNotFoundMess
       const exampleArgs = buildExampleArgs(exampleDef.args || {});
       relinka(
         "log",
-        `Example: ${cliName} ${exampleCmd}${exampleArgs ? ` ${exampleArgs}` : ""}`
+        `Example: ${pkgName}${parserOptions._isSubcommand ? ` ${cliName}` : ""} ${exampleCmd}${exampleArgs ? ` ${exampleArgs}` : ""}`
       );
     }
     if (subCommandNames.length > 0) {
@@ -309,26 +311,26 @@ This can cause recursion or unexpected behavior.`
       );
       process.exit(1);
     }
-    if (rawArgv[0] === "help") {
-      await showUsage(command, parserOptions);
-      if (autoExit) process.exit(0);
-      return;
-    }
-    await relinkaConfig;
-    if (checkHelp(rawArgv)) {
-      await showUsage(command, parserOptions);
-      if (autoExit) process.exit(0);
-      return;
-    }
-    if (checkVersion(rawArgv)) {
-      if (command.meta?.name) {
-        relinka(
-          "log",
-          `${command.meta?.name} ${command.meta?.version ? `v${command.meta?.version}` : ""}`
+    if (parserOptions.fileBasedCmds?.enable && rawArgv.length > 0) {
+      const commandsDir = path.resolve(
+        parserOptions.fileBasedCmds.cmdsRootPath
+      );
+      const resolved = await resolveFileBasedCommandPath(commandsDir, rawArgv);
+      if (resolved) {
+        const { def: subCommand, leftoverArgv, path: pathSegments } = resolved;
+        const helpIdx = leftoverArgv.findIndex(
+          (arg) => arg === "help" || arg === "--help" || arg === "-h"
         );
+        if (helpIdx !== -1) {
+          await showUsage(subCommand, {
+            ...parserOptions,
+            _fileBasedCurrentDir: pathSegments.length ? path.join(commandsDir, ...pathSegments) : commandsDir,
+            _fileBasedPathSegments: pathSegments
+          });
+          if (autoExit) process.exit(0);
+          return;
+        }
       }
-      if (autoExit) process.exit(0);
-      return;
     }
     const fileBasedEnabled = parserOptions.fileBasedCmds?.enable;
     if (fileBasedEnabled && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
@@ -373,6 +375,18 @@ This can cause recursion or unexpected behavior.`
         }
       }
       if (subSpec) {
+        const helpIdx = subCmdArgv.findIndex(
+          (arg) => arg === "help" || arg === "--help" || arg === "-h"
+        );
+        if (helpIdx !== -1) {
+          const subCommandDef = await loadSubCommand(subSpec);
+          await showUsage(subCommandDef, {
+            ...parserOptions,
+            _isSubcommand: true
+          });
+          if (autoExit) process.exit(0);
+          return;
+        }
         try {
           const ctx = getParsedContext(command, rawArgv, parserOptions);
           if (typeof command.onCmdInit === "function")
@@ -380,7 +394,7 @@ This can cause recursion or unexpected behavior.`
           await runSubCommand(
             subSpec,
             subCmdArgv,
-            parserOptions,
+            { ...parserOptions, _isSubcommand: true },
             command.onCmdExit ? async (_subCtx) => {
               await command.onCmdExit?.(ctx);
             } : void 0
@@ -394,6 +408,22 @@ This can cause recursion or unexpected behavior.`
         }
       }
     }
+    await relinkaConfig;
+    if (rawArgv[0] === "help" || checkHelp(rawArgv)) {
+      await showUsage(command, parserOptions);
+      if (autoExit) process.exit(0);
+      return;
+    }
+    if (checkVersion(rawArgv)) {
+      if (command.meta?.name) {
+        relinka(
+          "info",
+          `${command.meta?.name} ${command.meta?.version ? `v${command.meta?.version}` : ""}`
+        );
+      }
+      if (autoExit) process.exit(0);
+      return;
+    }
     try {
       await runCommandWithArgs(command, rawArgv, parserOptions);
     } finally {
@@ -428,61 +458,67 @@ async function loadSubCommand(spec) {
   throw new Error("Subcommand import did not return a valid command");
 }
 async function runFileBasedSubCmd(subName, argv, fileCmdOpts, parserOptions, parentFinish) {
-  const subPathDir = path.join(fileCmdOpts.cmdsRootPath, subName);
-  let importPath;
-  const possibleFiles = [
-    // Only allow cmd.{ts,js} inside the subcommand directory
-    path.join(subPathDir, "cmd.js"),
-    path.join(subPathDir, "cmd.ts")
-  ];
-  const dirExists = await fs.pathExists(subPathDir);
-  let isDirCommand = false;
-  if (dirExists) {
-    const stats = await fs.stat(subPathDir);
-    isDirCommand = stats.isDirectory();
-  }
-  if (isDirCommand) {
-    for (const pattern of possibleFiles) {
-      if (await fs.pathExists(pattern)) {
-        importPath = pattern;
-        break;
+  async function resolveCmdPath(baseDir, args) {
+    if (args.length === 0 || isFlag(args[0])) {
+      const possibleFiles2 = [
+        path.join(baseDir, "cmd.js"),
+        path.join(baseDir, "cmd.ts")
+      ];
+      for (const file of possibleFiles2) {
+        if (await fs.pathExists(file)) {
+          return { importPath: file, leftoverArgv: args };
+        }
       }
-    }
-    if (!importPath) {
-      const attempted = [subName, ...argv].join(" ");
-      const expectedPath = path.relative(
-        process.cwd(),
-        path.join(fileCmdOpts.cmdsRootPath, subName, "cmd.{ts,js}")
-      );
       throw new Error(
-        `Unknown command or arguments: ${attempted}
+        `Unknown command or arguments: ${args.join(" ")}
 
-Info for this CLI's developer: No valid command directory found, expected: ${expectedPath}`
+Info for this CLI's developer: No valid command file found in ${baseDir}`
       );
     }
-  } else {
+    const nextDir = path.join(baseDir, args[0]);
+    if (await fs.pathExists(nextDir) && (await fs.stat(nextDir)).isDirectory()) {
+      return resolveCmdPath(nextDir, args.slice(1));
+    }
+    const possibleFiles = [
+      path.join(baseDir, "cmd.js"),
+      path.join(baseDir, "cmd.ts")
+    ];
+    for (const file of possibleFiles) {
+      if (await fs.pathExists(file)) {
+        return { importPath: file, leftoverArgv: args };
+      }
+    }
+    throw new Error(
+      `Unknown command or arguments: ${args.join(" ")}
+
+Info for this CLI's developer: No valid command file found in ${baseDir}`
+    );
+  }
+  const startDir = path.join(fileCmdOpts.cmdsRootPath, subName);
+  if (!await fs.pathExists(startDir) || !(await fs.stat(startDir)).isDirectory()) {
     const attempted = [subName, ...argv].join(" ");
-    const expectedPath2 = path.relative(
+    const expectedPath = path.relative(
       process.cwd(),
       path.join(fileCmdOpts.cmdsRootPath, subName, "cmd.{ts,js}")
     );
     throw new Error(
       `Unknown command or arguments: ${attempted}
 
-Info for this CLI's developer: No valid command directory found, expected: ${expectedPath2}`
+Info for this CLI's developer: No valid command directory found, expected: ${expectedPath}`
     );
   }
+  const { importPath, leftoverArgv } = await resolveCmdPath(startDir, argv);
   const imported = await import(path.resolve(importPath));
   const subCommand = imported.default;
   if (!subCommand) {
     throw new Error(
-      `File-based subcommand "${subName}" has no default export or is invalid.`
+      `File-based subcommand has no default export or is invalid: ${importPath}`
     );
   }
   try {
     const subCtx = await runCommandWithArgs(
       subCommand,
-      argv,
+      leftoverArgv,
       parserOptions,
       true
     );
@@ -494,6 +530,14 @@ Info for this CLI's developer: No valid command directory found, expected: ${exp
 async function runSubCommand(spec, argv, parserOptions, parentFinish) {
   const subCommand = await loadSubCommand(spec);
   try {
+    const helpIdx = argv.findIndex(
+      (arg) => arg === "help" || arg === "--help" || arg === "-h"
+    );
+    if (helpIdx !== -1) {
+      await showUsage(subCommand, { ...parserOptions, _isSubcommand: true });
+      if (parserOptions.autoExit !== false) process.exit(0);
+      return;
+    }
     const subCtx = await runCommandWithArgs(
       subCommand,
       argv,
@@ -597,7 +641,7 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
       const noSubcommandArgInCurrentCall = !argv.some((arg) => !isFlag(arg));
       if (isDispatcher && noSubcommandArgInCurrentCall) {
         relinka("warn", "Please specify a command");
-        await showUsage(command, parserOptions, true);
+        await showUsage(command, parserOptions);
         if (autoExit) process.exit(0);
         return;
       }
@@ -786,3 +830,32 @@ function getParsedContext(command, argv, parserOptions) {
   }
   return { args: finalArgs, raw: argv };
 }
+async function resolveFileBasedCommandPath(cmdsRoot, argv) {
+  let currentDir = cmdsRoot;
+  const pathSegments = [];
+  let leftover = [...argv];
+  while (leftover.length > 0 && !isFlag(leftover[0])) {
+    const nextDir = path.join(currentDir, leftover[0]);
+    if (await fs.pathExists(nextDir) && (await fs.stat(nextDir)).isDirectory()) {
+      currentDir = nextDir;
+      pathSegments.push(leftover[0]);
+      leftover = leftover.slice(1);
+    } else {
+      break;
+    }
+  }
+  for (const fname of ["cmd.ts", "cmd.js"]) {
+    const fpath = path.join(currentDir, fname);
+    if (await fs.pathExists(fpath)) {
+      const imported = await import(path.resolve(fpath));
+      if (imported.default) {
+        return {
+          def: imported.default,
+          path: pathSegments,
+          leftoverArgv: leftover
+        };
+      }
+    }
+  }
+  return null;
+}

package/package.json

@@ -28,7 +28,7 @@
   "license": "MIT",
   "name": "@reliverse/rempts",
   "type": "module",
-  "version": "1.7.4",
+  "version": "1.7.6",
   "author": "reliverse",
   "bugs": {
     "email": "blefnk@gmail.com",
@@ -44,7 +44,7 @@
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@eslint/js": "^9.26.0",
-    "@reliverse/dler": "^1.2.2",
+    "@reliverse/dler": "^1.2.3",
     "@reliverse/relidler-cfg": "^1.1.3",
     "@stylistic/eslint-plugin": "^4.2.0",
     "@total-typescript/ts-reset": "^0.6.1",