@reliverse/rempts 1.7.0 → 1.7.1

package/README.md

@@ -4,94 +4,138 @@
 
 [💬 Discord](https://discord.gg/3GawfWfAPe) — [📦 NPM](https://npmjs.com/package/@reliverse/rempts) — [🧠 Docs](https://docs.reliverse.org/reliverse/rempts) — [🌐 JSR](https://jsr.io/@reliverse/rempts) — [✨ GitHub](https://github.com/reliverse/rempts)
 
-## Stop Fighting Your CLI
+## Features
 
-- CLIs are still the sharpest tool in the builder's belt. But most libraries are either clunky or crusty.
-- **@reliverse/rempts** is your end-to-end CLI UI + command framework — made for developer experience, DX precision, and high-context terminal UX.
-- No more hacking together `inquirer`, `citty`, `commander`, `chalk`, and other friends.
-
-## What Makes It Different?
-
-- 📂 File-based commands (optional)
+- 🫂 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
-- 🎨 Customizable themes, styled output
-- 🧩 Router + argument parser built-in
 - ⚡ 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
-- 🏎️ Prompt engine that *feels* modern, actually is
 - 🧪 Scriptable for testing, stable for production
-- 🚨 Crash-safe (Ctrl+C, SIGINT, errors)
-- 🆕 Automatic commands creation via `rempts init --cmd my-cool-cmd`
+- 🆕 Automatic commands creation (via `dler init --cmd my-cool-cmd`)
+- 🏞️ No more hacking together `inquirer`, `citty`, `commander`, `chalk`
+
+## Installation
+
+```bash
+bun add @reliverse/rempts
+```
+
+## Usage Examples
+
+- [Prompts](#prompts)
+- [Launcher](#launcher)
 
 ## Screenshot
 
-![Rempts Example CLI Screenshot](./example.png)
+![Rempts Example CLI Screenshot](./example/example.png)
 
-## Terminology
+## API Overview
 
-- **Command/Subcommand**: A command is a function that defines the behavior of a CLI.
-- **Argument**: An argument is a value that is passed to a command.
-- **Flag**: A flag is a boolean argument that is used to enable or disable a feature.
-- **Option**: An option is a named argument that is used to configure a command.
+All main prompts APIs are available from the package root:
 
-## CLI Launcher (Router)
+```ts
+import {
+  // ...prompts
+  defineCommand, runMain, defineArgs,
+  inputPrompt, selectPrompt, multiselectPrompt, numberPrompt,
+  confirmPrompt, togglePrompt, spinnerTaskPrompt, progressTaskPrompt,
+  startPrompt, endPrompt, resultPrompt, nextStepsPrompt,
+  // ...hooks
+  useSpinner,
+  // ...launcher
+  runMain, defineCommand, defineArgs,
+  // ...types
+  // ...more
+} from "@reliverse/rempts";
+```
 
-Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'s so called "launcher" is a uniquely powerful and ergonomic CLI toolkit—one that helps you build delightful developer experiences with less code and more confidence. The launcher supports both programmatically defined subcommands and file-based routing, so you can structure your CLI however you like. It automatically detects and loads subcommands from your filesystem and provides robust usage and error handling out-of-the-box. The launcher is more than just a command runner—it's a robust, developer-friendly engine with several advanced features and thoughtful design choices:
+> See [`src/mod.ts`](./src/mod.ts) for the full list of exports.
 
-- **File-Based & Defined Subcommands:**  
-  Use `subCommands` in your command definition or let the launcher automatically load commands from a specified directory.
+## Prompts
 
-- **Automatic Command Detection:**  
-  The launcher scans your specified `cmdsRootPath` for command files matching common patterns such as:
-  - `arg-cmdName.{ts,js}`
-  - `cmdName/index.{ts,js}`
-  - `cmdName/cmdName-mod.{ts,js}`
-  - And more — with automatic usage output if a command file is not found.
+### Built-in Prompts
 
-- **Built-In Flag Handling:**  
-  Automatically processes global flags such as:
-  - `--help` and `-h` to show usage details.
-  - `--version` and `-v` to display version information.
-  - `--debug` for verbose logging during development.
+| Prompt                    | Description                                               |
+|---------------------------|-----------------------------------------------------------|
+| `inputPrompt`             | Single-line input (with mask support, e.g. for passwords) |
+| `selectPrompt`            | Single-choice radio menu                                  |
+| `multiselectPrompt`       | Multi-choice checkbox menu                                |
+| `numberPrompt`            | Type-safe number input                                    |
+| `confirmPrompt`           | Yes/No toggle                                             |
+| `togglePrompt`            | Custom on/off toggles                                     |
+| `progressTaskPrompt`      | Progress bar for async tasks                              |
+| `resultPrompt`            | Show results in a styled box                              |
+| `nextStepsPrompt`         | Show next steps in a styled list                          |
+| `startPrompt`/`endPrompt` | Makes CLI start/end flows look nice                       |
+| `spinnerTaskPrompt`       | Async loader with spinner (possibly will be deprecated)   |
+| `datePrompt`              | Date input with format validation                         |
+| `anykeyPrompt`            | Wait for any keypress                                     |
 
-- **Unified Argument Parsing:**  
-  Seamlessly combines positional and named arguments with zero configuration, auto-parsing booleans, strings, numbers, arrays, and even supporting negated flags like `--no-flag`.
+### Hooks
 
-- **Customizable Behavior:**  
-  Options such as `fileBasedCmds.enable`, `cmdsRootPath`, and `autoExit` allow you to tailor the launcher's behavior. For example, you can choose whether the process should exit automatically on error or allow manual error handling.
+| Hook         | Description        |
+|--------------|--------------------|
+| `useSpinner` | Start/stop spinner |
 
-- **Error Management & Usage Output:**  
-  The launcher provides clear error messages for missing required arguments, invalid types, or command import issues, and it automatically displays usage information for your CLI.
+### Notices
 
-- **Lifecycle Hooks:**
-  - You can define optional `setup` and `cleanup` functions in your main command. These hooks are called automatically before and after any command or subcommand runs (including file-based and programmatic subcommands). This is perfect for initializing resources or cleaning up after execution.
+- `setup`/`cleanup` are now `onCmdStart`/`onCmdEnd` (old names still work for now).
 
-- **Dynamic Usage Examples:**
-  - The launcher inspects your available subcommands and their argument definitions, then prints a plausible example CLI invocation for a random subcommand directly in the help output. This helps users understand real-world usage at a glance.
+### Prompts Usage Example
 
-- **File-Based & Programmatic Subcommands:**
-  - Both file-based and object subcommands are fully supported. The launcher can introspect their argument definitions and metadata for help, usage, and validation.
-  - File-based subcommands are auto-discovered from your filesystem, while programmatic subcommands can be defined inline in your main command.
+```ts
+import { relinka } from "@reliverse/relinka";
 
-- **Context-Aware Help Output:**
-  - The help/usage output adapts to your CLI's structure, showing available subcommands, their aliases, argument details, and even dynamic usage examples. It also displays global options and context-specific error messages.
+import {
+  startPrompt,
+  inputPrompt,
+  selectPrompt,
+  defineCommand,
+  runMain
+} from "@reliverse/rempts";
 
-- **Error Handling:**
-  - The launcher provides clear, actionable error messages for missing required arguments, invalid types, unknown commands, and import errors. It always shows relevant usage information to help users recover quickly.
+async function main() {
+  await startPrompt({ title: "Project Setup" });
 
-- **Unified Argument Parsing:**
-  - All arguments (positional, named, boolean, string, number, array) are parsed and validated automatically. Negated flags (like `--no-flag`) are supported out of the box.
+  const name = await inputPrompt({
+    title: "What's your project name?",
+    defaultValue: "my-cool-project",
+  });
 
-- **Extensible & Flexible:**
-  - The launcher is highly extensible. You can use it with both Bun and Node.js, and it works seamlessly with both file-based and programmatic command definitions. You can also customize its behavior with options like `autoExit`, `cmdsRootPath`, and more.
+  const framework = await selectPrompt({
+    title: "Pick your framework",
+    options: [
+      { value: "next", label: "Next.js" },
+      { value: "svelte", label: "SvelteKit" },
+      { value: "start", label: "TanStack Start" },
+    ],
+    defaultValue: "next",
+  });
 
-- **Bun & Node.js Support:**
-  - The launcher is designed to work in both Bun and Node.js environments, so you can use it in any modern JavaScript/TypeScript project.
+  console.log("Your result:", { name, framework });
+};
 
-- **Prompt-First, Modern UX:**
-  - The launcher integrates tightly with the prompt engine, so you can build interactive, delightful CLIs with minimal effort.
+await main();
+```
 
-### Launcher Usage Example
+## Launcher
+
+### Terminology
+
+- **Launcher/Router**: The main entry point for your CLI. Visit [CLI Launcher (Router)](#cli-launcher-router) section to learn more.
+- **Command/Subcommand**: A command is a function that defines the behavior of a CLI.
+- **Argument**: An argument is a value that is passed to a command.
+- **Flag**: A flag is a boolean argument that is used to enable or disable a feature.
+- **Option**: An option is a named argument that is used to configure a command.
+
+#### Launcher Usage Example
 
 ‼️ Go to [Usage Examples](#usage-examples) section for a more detailed example.
 
@@ -106,10 +150,10 @@ const main = defineCommand({
     version: "1.0.0",
     description: "Rempts Launcher Playground CLI",
   },
-  setup() {
+  onCmdStart() {
     relinka("success", "Setup");
   },
-  cleanup() {
+  onCmdEnd() {
     relinka("success", "Cleanup");
   },
   subCommands: {
@@ -126,7 +170,7 @@ await runMain(main);
 await runMain(myCommand, {
   fileBasedCmds: {
     enable: true,
-    cmdsRootPath: "./cli/args", // default is `./app`
+    cmdsRootPath: "my-cmds", // default is `./app`
   },
   // Optionally disable auto-exit to handle errors manually:
   autoExit: false,
@@ -135,7 +179,7 @@ await runMain(myCommand, {
 
 This flexibility allows you to easily build a rich, multi-command CLI with minimal boilerplate. The launcher even supports nested subcommands, making it simple to construct complex CLI applications.
 
-### File-Based Subcommands
+#### File-Based Subcommands
 
 Drop a `./src/cli/app/add/index.ts` and it's live.
 
@@ -169,22 +213,10 @@ export default defineCommand({
 
 **Hint**:
 
-- Install `bun i -g @reliverse/rempts-cli`
-- Use `rempts init --cmd my-cmd-1 my-cmd-2` to init commands automatically
+- Install `bun add -D @reliverse/dler`
+- Use `dler init --cmd cmd1 cmd2` to init commands for rempts launcher's automatically
 
-## 📦 Built-In Prompts
-
-- 🧠 `inputPrompt` – Single-line, password, masked
-- ✅ `selectPrompt` – Radio menu
-- 🧰 `multiselectPrompt` – Checkbox menu
-- 🔢 `numberPrompt` – Type-safe number input
-- 🔄 `confirmPrompt` – Yes/No toggle
-- 🚥 `togglePrompt` – Custom on/off toggles
-- ⏳ `spinnerPrompt` – Async loaders with status
-- 📜 `logPrompt` – Styled logs / steps
-- 🧼 `clearPrompt` – Clears console with style
-
-## 🧱 Minimal, Functional API
+### Advanced Minimal API
 
 ```ts
 defineCommand({
@@ -207,14 +239,14 @@ defineCommand({
 - Default values, validations, descriptions
 - Full help rendering from metadata
 
-## Theming + Customization
+### Theming + Customization
 
 - 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
 
-## Playground
+### Playground
 
 ```bash
 bun i -g @reliverse/rempts-cli
@@ -233,9 +265,9 @@ 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.
 
-## Usage Examples
+### Launcher Usage Examples
 
-### Minimal Usage Example
+#### Minimal Usage Example
 
 **1 Create a `src/mod.ts` file:**
 
@@ -262,7 +294,13 @@ export default defineCommand({
 });
 ```
 
-### Medium Usage Example
+**4. Test it:**
+
+```bash
+bun src/mod.ts
+```
+
+#### Medium Usage Example
 
 ```ts
 import { defineCommand, runMain } from "@reliverse/rempts";
@@ -279,7 +317,7 @@ const main = defineCommand({
 await runMain(main);
 ```
 
-### Classic Usage Example
+#### Classic Usage Example
 
 ```ts
 import { relinka } from "@reliverse/relinka";
@@ -307,7 +345,7 @@ const main = defineCommand({
   },
   async run({ args }) {
     await startPrompt({
-      title: "🚀 Project Setup",
+      title: "Project Setup",
     });
 
     const name = await inputPrompt({
@@ -331,7 +369,7 @@ const main = defineCommand({
 await runMain(main);
 ```
 
-### Advanced Usage Example
+#### Advanced Usage Example
 
 ```ts
 import { relinka } from "@reliverse/relinka";
@@ -409,7 +447,7 @@ const mainCommand = defineCommand({
 
     // Begin interactive session with a prompt.
     await startPrompt({
-      title: "🚀 Project Setup",
+      title: "Project Setup",
     });
 
     // Ask for the project name, falling back to provided argument or a default.
@@ -469,6 +507,97 @@ await runMain(mainCommand, {
 });
 ```
 
+### CLI Launcher (Router)
+
+Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'s so called "launcher" is a uniquely powerful and ergonomic CLI toolkit—one that helps you build delightful developer experiences with less code and more confidence. The launcher supports both programmatically defined subcommands and file-based routing, so you can structure your CLI however you like. It automatically detects and loads subcommands from your filesystem and provides robust usage and error handling out-of-the-box. The launcher is more than just a command runner—it's a robust, developer-friendly engine with several advanced features and thoughtful design choices:
+
+- **File-Based & Defined Subcommands:**  
+  Use `subCommands` in your command definition or let the launcher automatically load commands from a specified directory.
+
+- **Automatic Command Detection:**  
+  The launcher scans your specified `cmdsRootPath` for command files matching common patterns such as:
+  - `arg-cmdName.{ts,js}`
+  - `cmdName/index.{ts,js}`
+  - `cmdName/cmdName-mod.{ts,js}`
+  - And more — with automatic usage output if a command file is not found.
+
+- **Built-In Flag Handling:**  
+  Automatically processes global flags such as:
+  - `--help` and `-h` to show usage details.
+  - `--version` and `-v` to display version information.
+  - `--debug` for verbose logging during development.
+
+- **Unified Argument Parsing:**  
+  Seamlessly combines positional and named arguments with zero configuration, auto-parsing booleans, strings, numbers, arrays, and even supporting negated flags like `--no-flag`.
+
+- **Customizable Behavior:**  
+  Options such as `fileBasedCmds.enable`, `cmdsRootPath`, and `autoExit` allow you to tailor the launcher's behavior. For example, you can choose whether the process should exit automatically on error or allow manual error handling.
+
+- **Error Management & Usage Output:**  
+  The launcher provides clear error messages for missing required arguments, invalid types, or command import issues, and it automatically displays usage information for your CLI.
+
+- **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-subcommand, called before/after each subcommand, but NOT for the main `run()` handler)
+
+  **Global Hooks:**
+  - `onLauncherStart`: Called once, before any command/subcommand/run() is executed.
+  - `onLauncherEnd`: Called once, after all command/subcommand/run() logic is finished (even if an error occurs).
+
+  **Per-Subcommand Hooks:**
+  - `onCmdStart`: Called before each subcommand (not for main `run()`).
+  - `onCmdEnd`: Called after each subcommand (not for main `run()`).
+
+  This means:
+  - If your CLI has multiple subcommands, `onCmdStart` and `onCmdEnd` will be called for each subcommand invocation, not just once for the whole CLI process.
+  - If your main command has a `run()` handler (and no subcommand 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 subcommand execution.
+  - If you want logic to run only once for the entire CLI process, use `onLauncherStart` and `onLauncherEnd`.
+
+  **Example:**
+
+  ```ts
+  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 subcommand'); },
+    onCmdEnd() { relinka('info', 'Cleanup for each subcommand'); },
+    subCommands: { ... },
+    run() { relinka('info', 'Main run handler (no subcommand)'); },
+  });
+  // onLauncherStart/onLauncherEnd are called once per process
+  // onCmdStart/onCmdEnd are called for every subcommand (not for main run())
+  // If you want per-run() logic, use the run() handler or global hooks
+  ```
+
+  > **Note:** 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.
+
+- **Dynamic Usage Examples:**
+  - The launcher inspects your available subcommands and their argument definitions, then prints a plausible example CLI invocation for a random subcommand directly in the help output. This helps users understand real-world usage at a glance.
+
+- **File-Based & Programmatic Subcommands:**
+  - Both file-based and object subcommands are fully supported. The launcher can introspect their argument definitions and metadata for help, usage, and validation.
+  - File-based subcommands are auto-discovered from your filesystem, while programmatic subcommands can be defined inline in your main command.
+
+- **Context-Aware Help Output:**
+  - The help/usage output adapts to your CLI's structure, showing available subcommands, their aliases, argument details, and even dynamic usage examples. It also displays global options and context-specific error messages.
+
+- **Error Handling:**
+  - The launcher provides clear, actionable error messages for missing required arguments, invalid types, unknown commands, and import errors. It always shows relevant usage information to help users recover quickly.
+
+- **Unified Argument Parsing:**
+  - All arguments (positional, named, boolean, string, number, array) are parsed and validated automatically. Negated flags (like `--no-flag`) are supported out of the box.
+
+- **Extensible & Flexible:**
+  - The launcher is highly extensible. You can use it with both Bun and Node.js, and it works seamlessly with both file-based and programmatic command definitions. You can also customize its behavior with options like `autoExit`, `cmdsRootPath`, and more.
+
+- **Bun & Node.js Support:**
+  - The launcher is designed to work in both Bun and Node.js environments, so you can use it in any modern JavaScript/TypeScript project.
+
+- **Prompt-First, Modern UX:**
+  - The launcher integrates tightly with the prompt engine, so you can build interactive, delightful CLIs with minimal effort.
+
 ## Contributing
 
 Bug report? Prompt idea? Want to build the best DX possible?
@@ -481,6 +610,24 @@ You're in the right place:
 
 > *No classes. No magic. Just clean, composable tools for CLI devs.*
 
+### Notices For Contributors
+
+**TypeScript Support**:
+
+All APIs are fully typed. See [`src/types.ts`](./src/types.ts) for advanced customization and type inference.
+
+**Examples**:
+
+- **Classic CLI:** [`example/launcher/classic.ts`](./example/launcher/classic.ts)
+- **Modern Minimal CLI:** [`example/launcher/modern.ts`](./example/launcher/modern.ts)
+- **Full Prompt Demo:** [`example/prompts/mod.ts`](./example/prompts/mod.ts)
+
+**Components and Utilities**:
+
+- **components/**: All prompt UIs, CLI output, launcher logic, etc.
+- **utils/**: Color, error, validation, streaming, and system helpers.
+- **hooks/**: Useful hooks for prompt state and effects.
+
 ### Helpful Links
 
 - [CLI application with the Node.js Readline module](https://dev.to/camptocamp-geo/cli-application-with-the-nodejs-readline-module-48ic)

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

@@ -58,16 +58,60 @@ type DefineCommandOptions<A extends ArgDefinitions = EmptyArgs> = {
     args?: A;
     run?: CommandRun<InferArgTypes<A>>;
     subCommands?: SubCommandsMap;
+    /**
+     * Called before the command or subcommand runs
+     */
+    onCmdStart?: () => void | Promise<void>;
+    /**
+     * Called after the command or subcommand finishes
+     */
+    onCmdEnd?: () => void | Promise<void>;
+    /**
+     * @deprecated Use onCmdStart instead
+     */
     setup?: () => void | Promise<void>;
+    /**
+     * @deprecated Use onCmdEnd instead
+     */
     cleanup?: () => void | Promise<void>;
+    /**
+     * Called once per CLI process, before any command/subcommand/run() is executed
+     */
+    onLauncherStart?: () => void | Promise<void>;
+    /**
+     * Called once per CLI process, after all command/subcommand/run() logic is finished
+     */
+    onLauncherEnd?: () => void | Promise<void>;
 };
 export type Command<A extends ArgDefinitions = EmptyArgs> = {
     meta?: CommandMeta;
     args: A;
     run?: CommandRun<InferArgTypes<A>>;
     subCommands?: SubCommandsMap;
+    /**
+     * Called before the command or subcommand runs
+     */
+    onCmdStart?: () => void | Promise<void>;
+    /**
+     * Called after the command or subcommand finishes
+     */
+    onCmdEnd?: () => void | Promise<void>;
+    /**
+     * @deprecated Use onCmdStart instead
+     */
     setup?: () => void | Promise<void>;
+    /**
+     * @deprecated Use onCmdEnd instead
+     */
     cleanup?: () => void | Promise<void>;
+    /**
+     * Called once per CLI process, before any command/subcommand/run() is executed
+     */
+    onLauncherStart?: () => void | Promise<void>;
+    /**
+     * Called once per CLI process, after all command/subcommand/run() logic is finished
+     */
+    onLauncherEnd?: () => 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 {

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

@@ -57,13 +57,22 @@ function isFlag(str) {
   return str.startsWith("-");
 }
 export function defineCommand(options) {
+  const onCmdStart = options.onCmdStart || options.setup;
+  const onCmdEnd = options.onCmdEnd || options.cleanup;
+  const onLauncherStart = options.onLauncherStart;
+  const onLauncherEnd = options.onLauncherEnd;
   return {
     meta: options.meta,
     args: options.args || {},
     run: options.run,
     subCommands: options.subCommands,
-    setup: options.setup,
-    cleanup: options.cleanup
+    onCmdStart,
+    onCmdEnd,
+    onLauncherStart,
+    onLauncherEnd,
+    // Backward-compatible aliases
+    setup: onCmdStart,
+    cleanup: onCmdEnd
   };
 }
 let _cachedDefaultCliName;
@@ -228,146 +237,153 @@ export async function showUsage(command, parserOptions = {}, displayNotFoundMess
   }
 }
 export async function runMain(command, parserOptions = {}) {
-  if (!parserOptions.fileBasedCmds && !command.subCommands) {
-    let callerDir = process.cwd();
-    let callerFile;
-    try {
-      const err = new Error();
-      const stack = err.stack?.split("\n");
-      if (stack) {
-        for (const line of stack) {
-          const match = /\((.*):(\d+):(\d+)\)/.exec(line) || /at (.*):(\d+):(\d+)/.exec(line);
-          if (match?.[1] && !match[1].includes("launcher-mod")) {
-            callerFile = match[1];
-            break;
+  if (typeof command.onLauncherStart === "function")
+    await command.onLauncherStart();
+  try {
+    if (!parserOptions.fileBasedCmds && !command.subCommands) {
+      let callerDir = process.cwd();
+      let callerFile;
+      try {
+        const err = new Error();
+        const stack = err.stack?.split("\n");
+        if (stack) {
+          for (const line of stack) {
+            const match = /\((.*):(\d+):(\d+)\)/.exec(line) || /at (.*):(\d+):(\d+)/.exec(line);
+            if (match?.[1] && !match[1].includes("launcher-mod")) {
+              callerFile = match[1];
+              break;
+            }
           }
         }
-      }
-      if (callerFile) {
-        callerDir = path.dirname(callerFile);
-        const rel = path.relative(process.cwd(), callerFile);
-        if (/app[/][^/]+[/]cmd\.(ts|js)$/.test(rel)) {
-          relinka(
-            "error",
-            `runMain() should not be called from a file-based subcommand: ${rel}
+        if (callerFile) {
+          callerDir = path.dirname(callerFile);
+          const rel = path.relative(process.cwd(), callerFile);
+          if (/app[/][^/]+[/]cmd\.(ts|js)$/.test(rel)) {
+            relinka(
+              "error",
+              `runMain() should not be called from a file-based subcommand: ${rel}
 This can cause recursion or unexpected behavior.
 Move your runMain() call to your main CLI entry file.`
-          );
-          process.exit(1);
-        }
-        const mainEntry = process.argv[1] ? path.resolve(process.argv[1]) : void 0;
-        if (mainEntry && path.resolve(callerFile) !== mainEntry) {
-          relinka(
-            "error",
-            `runMain() should only be called from your main CLI entry file.
+            );
+            process.exit(1);
+          }
+          const mainEntry = process.argv[1] ? path.resolve(process.argv[1]) : void 0;
+          if (mainEntry && path.resolve(callerFile) !== mainEntry) {
+            relinka(
+              "error",
+              `runMain() should only be called from your main CLI entry file.
 Detected: ${callerFile}
 Main entry: ${mainEntry}
 This can cause recursion or unexpected behavior.`
-          );
-          process.exit(1);
+            );
+            process.exit(1);
+          }
         }
+      } catch (_e) {
       }
-    } catch (_e) {
+      const defaultCmdsRoot = path.resolve(callerDir, "app");
+      parserOptions.fileBasedCmds = {
+        enable: true,
+        cmdsRootPath: defaultCmdsRoot
+      };
     }
-    const defaultCmdsRoot = path.resolve(callerDir, "app");
-    parserOptions.fileBasedCmds = {
-      enable: true,
-      cmdsRootPath: defaultCmdsRoot
-    };
-  }
-  const rawArgv = process.argv.slice(2);
-  const autoExit = parserOptions.autoExit !== false;
-  if (!(parserOptions.fileBasedCmds?.enable || command.subCommands && Object.keys(command.subCommands).length > 0 || command.run)) {
-    relinka(
-      "error",
-      "Invalid CLI configuration: No file-based commands, subCommands, or run() handler are defined. This CLI will not do anything.\n\u2502   To fix: add file-based commands (./app), or provide at least one subCommand or a run() handler."
-    );
-    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) {
+    const rawArgv = process.argv.slice(2);
+    const autoExit = parserOptions.autoExit !== false;
+    if (!(parserOptions.fileBasedCmds?.enable || command.subCommands && Object.keys(command.subCommands).length > 0 || command.run)) {
       relinka(
-        "info",
-        `${command.meta?.name} ${command.meta?.version ? `v${command.meta?.version}` : ""}`
+        "error",
+        "Invalid CLI configuration: No file-based commands, subCommands, or run() handler are defined. This CLI will not do anything.\n\u2502   To fix: add file-based commands (./app), or provide at least one subCommand or a run() handler."
       );
+      process.exit(1);
     }
-    if (autoExit) process.exit(0);
-    return;
-  }
-  const fileBasedEnabled = parserOptions.fileBasedCmds?.enable;
-  if (fileBasedEnabled && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
-    const [subName, ...subCmdArgv] = rawArgv;
-    try {
-      if (typeof command.setup === "function") await command.setup();
-      await runFileBasedSubCmd(
-        subName,
-        subCmdArgv,
-        parserOptions.fileBasedCmds,
-        parserOptions,
-        command.cleanup
-      );
+    if (rawArgv[0] === "help") {
+      await showUsage(command, parserOptions);
       if (autoExit) process.exit(0);
       return;
-    } catch (err) {
-      relinka("error", "Error loading file-based subcommand:", err.message);
-      if (autoExit) process.exit(1);
-      throw err;
     }
-  }
-  if (!fileBasedEnabled && command.subCommands && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
-    const [maybeSub, ...subCmdArgv] = rawArgv;
-    let subSpec;
-    for (const [key, spec] of Object.entries(command.subCommands)) {
-      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 subcommand ${key}:`, err);
+    await relinkaConfig;
+    if (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;
     }
-    if (subSpec) {
+    const fileBasedEnabled = parserOptions.fileBasedCmds?.enable;
+    if (fileBasedEnabled && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
+      const [subName, ...subCmdArgv] = rawArgv;
       try {
-        if (typeof command.setup === "function") await command.setup();
-        await runSubCommand(
-          subSpec,
+        if (typeof command.onCmdStart === "function")
+          await command.onCmdStart();
+        await runFileBasedSubCmd(
+          subName,
           subCmdArgv,
+          parserOptions.fileBasedCmds,
           parserOptions,
-          command.cleanup
+          command.onCmdEnd
         );
         if (autoExit) process.exit(0);
         return;
       } catch (err) {
-        relinka("error", "Error running subcommand:", err.message);
+        relinka("error", "Error loading file-based subcommand:", err.message);
         if (autoExit) process.exit(1);
         throw err;
       }
     }
-  }
-  if (typeof command.setup === "function") await command.setup();
-  try {
-    await runCommandWithArgs(command, rawArgv, parserOptions);
+    if (!fileBasedEnabled && command.subCommands && rawArgv.length > 0 && !isFlag(rawArgv[0])) {
+      const [maybeSub, ...subCmdArgv] = rawArgv;
+      let subSpec;
+      for (const [key, spec] of Object.entries(command.subCommands)) {
+        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 subcommand ${key}:`, err);
+        }
+      }
+      if (subSpec) {
+        try {
+          if (typeof command.onCmdStart === "function")
+            await command.onCmdStart();
+          await runSubCommand(
+            subSpec,
+            subCmdArgv,
+            parserOptions,
+            command.onCmdEnd
+          );
+          if (autoExit) process.exit(0);
+          return;
+        } catch (err) {
+          relinka("error", "Error running subcommand:", err.message);
+          if (autoExit) process.exit(1);
+          throw err;
+        }
+      }
+    }
+    try {
+      await runCommandWithArgs(command, rawArgv, parserOptions);
+    } finally {
+    }
+    await relinkaShutdown();
   } finally {
-    if (typeof command.cleanup === "function") await command.cleanup();
+    if (typeof command.onLauncherEnd === "function")
+      await command.onLauncherEnd();
   }
-  await relinkaShutdown();
 }
 function checkHelp(argv) {
   return argv.includes("--help") || argv.includes("-h");
@@ -392,7 +408,7 @@ async function loadSubCommand(spec) {
   }
   throw new Error("Subcommand import did not return a valid command");
 }
-async function runFileBasedSubCmd(subName, argv, fileCmdOpts, parserOptions, parentCleanup) {
+async function runFileBasedSubCmd(subName, argv, fileCmdOpts, parserOptions, parentFinish) {
   const subPathDir = path.join(fileCmdOpts.cmdsRootPath, subName);
   let importPath;
   const possibleFiles = [
@@ -447,15 +463,15 @@ Info for this CLI's developer: No valid command directory found, expected: ${exp
   try {
     await runCommandWithArgs(subCommand, argv, parserOptions);
   } finally {
-    if (typeof parentCleanup === "function") await parentCleanup();
+    if (typeof parentFinish === "function") await parentFinish();
   }
 }
-async function runSubCommand(spec, argv, parserOptions, parentCleanup) {
+async function runSubCommand(spec, argv, parserOptions, parentFinish) {
   const subCommand = await loadSubCommand(spec);
   try {
     await runCommandWithArgs(subCommand, argv, parserOptions);
   } finally {
-    if (typeof parentCleanup === "function") await parentCleanup();
+    if (typeof parentFinish === "function") await parentFinish();
   }
 }
 async function runCommandWithArgs(command, argv, parserOptions) {

package/package.json

@@ -28,7 +28,7 @@
   "license": "MIT",
   "name": "@reliverse/rempts",
   "type": "module",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "author": "reliverse",
   "bugs": {
     "email": "blefnk@gmail.com",
@@ -51,7 +51,7 @@
     "@types/bun": "^1.2.13",
     "@types/figlet": "^1.7.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^22.15.17",
+    "@types/node": "^22.15.18",
     "@types/terminal-kit": "^2.5.7",
     "@types/wrap-ansi": "^8.1.0",
     "eslint": "^9.26.0",