@reliverse/rempts 1.7.3 → 1.7.5

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
@@ -94,7 +99,7 @@ import {
 
 ### Notices
 
-- `setup`/`cleanup` are now `onCmdStart`/`onCmdEnd` (old names still work for now).
+- `setup`/`cleanup` are now `onCmdInit`/`onCmdExit` (old names still work for now).
 
 ### Prompts Usage Example
 
@@ -158,10 +163,10 @@ const main = defineCommand({
     version: "1.0.0",
     description: "Rempts Launcher Playground CLI",
   },
-  onCmdStart() {
+  onCmdInit() {
     relinka("success", "Setup");
   },
-  onCmdEnd() {
+  onCmdExit() {
     relinka("success", "Cleanup");
   },
   commands: {
@@ -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
@@ -547,18 +564,18 @@ 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)
-  - `onCmdStart` and `onCmdEnd` (per-command, called before/after each command, but NOT for the main `run()` handler)
+  - `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).
 
   **Per-Command Hooks:**
-  - `onCmdStart`: Called before each command (not for main `run()`).
-  - `onCmdEnd`: Called after each command (not for main `run()`).
+  - `onCmdInit`: Called before each command (not for main `run()`).
+  - `onCmdExit`: Called after each command (not for main `run()`).
 
   This means:
-  - If your CLI has multiple commands, `onCmdStart` and `onCmdEnd` will be called for each command invocation, not just once for the whole CLI process.
+  - 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`.
@@ -569,18 +586,18 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
   const main = defineCommand({
     onLauncherStart() { relinka('info', 'Global setup (once per process)'); },
     onLauncherEnd() { relinka('info', 'Global cleanup (once per process)'); },
-    onCmdStart() { relinka('info', 'Setup for each command'); },
-    onCmdEnd() { relinka('info', 'Cleanup for each command'); },
+    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
-  // onCmdStart/onCmdEnd are called for every command (not for main run())
+  // onCmdInit/onCmdExit are called for every command (not for main run())
   // If you want per-run() logic, use the run() handler or global hooks
   ```
 
 - **Deprecation Notice**
-  - The legacy `setup` and `cleanup` names are still supported as aliases for per-command hooks, but will be removed in a future major version. Prefer `onCmdStart` and `onCmdEnd` going forward.
+  - The legacy `setup` and `cleanup` names are still supported as aliases for per-command hooks, but will be removed in a future major version. Prefer `onCmdInit` and `onCmdExit` going forward.
   - The `subCommands` property is deprecated as well. Please use `commands` instead. `subCommands` will be removed in a future major version.
 
 - **Dynamic Usage Examples:**

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

@@ -69,17 +69,17 @@ type DefineCommandOptions<A extends ArgDefinitions = EmptyArgs> = {
     /**
      * Called before the command runs. Receives `{ args, raw }` (parsed args and raw argv).
      */
-    onCmdStart?: CommandHook<InferArgTypes<A>>;
+    onCmdInit?: CommandHook<InferArgTypes<A>>;
     /**
      * Called after the command finishes. Receives `{ args, raw }` (parsed args and raw argv).
      */
-    onCmdEnd?: CommandHook<InferArgTypes<A>>;
+    onCmdExit?: CommandHook<InferArgTypes<A>>;
     /**
-     * @deprecated Use onCmdStart instead
+     * @deprecated Use onCmdInit instead
      */
     setup?: CommandHook<InferArgTypes<A>>;
     /**
-     * @deprecated Use onCmdEnd instead
+     * @deprecated Use onCmdExit instead
      */
     cleanup?: CommandHook<InferArgTypes<A>>;
     /**
@@ -106,17 +106,17 @@ export type Command<A extends ArgDefinitions = EmptyArgs> = {
     /**
      * Called before the command runs. Receives `{ args, raw }` (parsed args and raw argv).
      */
-    onCmdStart?: CommandHook<InferArgTypes<A>>;
+    onCmdInit?: CommandHook<InferArgTypes<A>>;
     /**
      * Called after the command finishes. Receives `{ args, raw }` (parsed args and raw argv).
      */
-    onCmdEnd?: CommandHook<InferArgTypes<A>>;
+    onCmdExit?: CommandHook<InferArgTypes<A>>;
     /**
-     * @deprecated Use onCmdStart instead
+     * @deprecated Use onCmdInit instead
      */
     setup?: CommandHook<InferArgTypes<A>>;
     /**
-     * @deprecated Use onCmdEnd instead
+     * @deprecated Use onCmdExit instead
      */
     cleanup?: CommandHook<InferArgTypes<A>>;
     /**

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

@@ -57,8 +57,8 @@ function isFlag(str) {
   return str.startsWith("-");
 }
 export function defineCommand(options) {
-  const onCmdStart = options.onCmdStart || options.setup;
-  const onCmdEnd = options.onCmdEnd || options.cleanup;
+  const onCmdInit = options.onCmdInit || options.setup;
+  const onCmdExit = options.onCmdExit || options.cleanup;
   const onLauncherStart = options.onLauncherStart;
   const onLauncherEnd = options.onLauncherEnd;
   let commands = options.commands;
@@ -70,13 +70,13 @@ export function defineCommand(options) {
     args: options.args || {},
     run: options.run,
     commands,
-    onCmdStart,
-    onCmdEnd,
+    onCmdInit,
+    onCmdExit,
     onLauncherStart,
     onLauncherEnd,
     // Backward-compatible aliases
-    setup: onCmdStart,
-    cleanup: onCmdEnd
+    setup: onCmdInit,
+    cleanup: onCmdExit
   };
   Object.defineProperty(cmdObj, "subCommands", {
     get() {
@@ -335,15 +335,15 @@ This can cause recursion or unexpected behavior.`
       const [subName, ...subCmdArgv] = rawArgv;
       try {
         const ctx = getParsedContext(command, rawArgv, parserOptions);
-        if (typeof command.onCmdStart === "function")
-          await command.onCmdStart(ctx);
+        if (typeof command.onCmdInit === "function")
+          await command.onCmdInit(ctx);
         await runFileBasedSubCmd(
           subName,
           subCmdArgv,
           parserOptions.fileBasedCmds,
           parserOptions,
-          command.onCmdEnd ? async (_subCtx) => {
-            await command.onCmdEnd?.(ctx);
+          command.onCmdExit ? async (_subCtx) => {
+            await command.onCmdExit?.(ctx);
           } : void 0
         );
         if (autoExit) process.exit(0);
@@ -375,14 +375,14 @@ This can cause recursion or unexpected behavior.`
       if (subSpec) {
         try {
           const ctx = getParsedContext(command, rawArgv, parserOptions);
-          if (typeof command.onCmdStart === "function")
-            await command.onCmdStart(ctx);
+          if (typeof command.onCmdInit === "function")
+            await command.onCmdInit(ctx);
           await runSubCommand(
             subSpec,
             subCmdArgv,
             parserOptions,
-            command.onCmdEnd ? async (_subCtx) => {
-              await command.onCmdEnd?.(ctx);
+            command.onCmdExit ? async (_subCtx) => {
+              await command.onCmdExit?.(ctx);
             } : void 0
           );
           if (autoExit) process.exit(0);
@@ -428,61 +428,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
     );
@@ -512,7 +518,9 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
   );
   const defaultMap = {};
   for (const [argKey, def] of Object.entries(command.args || {})) {
-    if (def.default !== void 0) {
+    if (def.type === "boolean") {
+      defaultMap[argKey] = def.default !== void 0 ? def.default : false;
+    } else if (def.default !== void 0) {
       if (def.type === "array" && typeof def.default === "string") {
         defaultMap[argKey] = [def.default];
       } else {
@@ -561,7 +569,11 @@ async function runCommandWithArgs(command, argv, parserOptions, returnCtx) {
       else throw new Error(`Missing required argument: --${key}`);
     }
     try {
-      finalArgs[key] = castArgValue(def, rawVal, key);
+      if (def.type === "boolean") {
+        finalArgs[key] = rawVal !== void 0 ? castArgValue(def, rawVal, key) : false;
+      } else {
+        finalArgs[key] = castArgValue(def, rawVal, key);
+      }
       if (def.type === "array" && def.options && finalArgs[key]) {
         const values = finalArgs[key];
         const invalidOptions = values.filter(
@@ -663,7 +675,9 @@ export async function runCmd(command, argv = [], parserOptions = {}) {
   );
   const defaultMap = {};
   for (const [argKey, def] of Object.entries(command.args || {})) {
-    if (def.default !== void 0) {
+    if (def.type === "boolean") {
+      defaultMap[argKey] = def.default !== void 0 ? def.default : false;
+    } else if (def.default !== void 0) {
       if (def.type === "array" && typeof def.default === "string") {
         defaultMap[argKey] = [def.default];
       } else {
@@ -734,7 +748,9 @@ function getParsedContext(command, argv, parserOptions) {
   );
   const defaultMap = {};
   for (const [argKey, def] of Object.entries(command.args || {})) {
-    if (def.default !== void 0) {
+    if (def.type === "boolean") {
+      defaultMap[argKey] = def.default !== void 0 ? def.default : false;
+    } else if (def.default !== void 0) {
       if (def.type === "array" && typeof def.default === "string") {
         defaultMap[argKey] = [def.default];
       } else {
@@ -768,7 +784,11 @@ function getParsedContext(command, argv, parserOptions) {
     if (def.type === "array" && rawVal !== void 0 && !Array.isArray(rawVal)) {
       rawVal = [rawVal];
     }
-    finalArgs[key] = castArgValue(def, rawVal, key);
+    if (def.type === "boolean") {
+      finalArgs[key] = rawVal !== void 0 ? castArgValue(def, rawVal, key) : false;
+    } else {
+      finalArgs[key] = castArgValue(def, rawVal, key);
+    }
   }
   return { args: finalArgs, raw: argv };
 }

package/package.json

@@ -28,7 +28,7 @@
   "license": "MIT",
   "name": "@reliverse/rempts",
   "type": "module",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "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",