@reliverse/rempts 1.7.29 → 1.7.30

package/README.md

@@ -59,14 +59,13 @@ All main prompts APIs are available from the package root:
 ```ts
 import {
   // ...prompts
-  defineCommand, runMain, defineArgs,
   inputPrompt, selectPrompt, multiselectPrompt, numberPrompt,
   confirmPrompt, togglePrompt, taskSpinPrompt, taskProgressPrompt,
   startPrompt, endPrompt, resultPrompt, nextStepsPrompt,
   // ...hooks
   useSpinner,
   // ...launcher
-  runMain, defineCommand, defineArgs,
+  createCli, defineCommand, defineArgs,
   // ...types
   // ...more
 } from "@reliverse/rempts";
@@ -218,6 +217,8 @@ await main();
 
 ## Launcher
 
+> **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.
+
 ### Terminology
 
 - **Launcher/Router**: The main entry point for your CLI. Visit [CLI Launcher (Router)](#cli-launcher-router) section to learn more.
@@ -228,12 +229,12 @@ await main();
 
 #### Launcher Usage Example
 
-**Important**: Ensure your commands don't have `await main();`, `await runMain();`, or something like that — to prevent any unexpected behavior. Only main command should have it.
+**Important**: Ensure your commands don't have `await main();`, `await createCli();`, or something like that — to prevent any unexpected behavior. Only main command should have it.
 
 ```ts
 import { relinka } from "@reliverse/relinka";
 
-import { defineCommand, runMain } from "@reliverse/rempts";
+import { defineCommand, createCli } from "@reliverse/rempts";
 
 const main = defineCommand({
   meta: {
@@ -254,12 +255,20 @@ const main = defineCommand({
   },
 });
 
-await runMain(main);
-```
+// New object format (recommended)
+await createCli({
+  mainCommand: main,
+  fileBased: {
+    enable: true,
+    cmdsRootPath: "my-cmds", // default is `./app`
+  },
+  // Optionally disable auto-exit to handle errors manually:
+  autoExit: false,
+});
 
-```ts
-await runMain(myCommand, {
-  fileBasedCmds: {
+// Legacy format (still supported)
+await createCli(main, {
+  fileBased: {
     enable: true,
     cmdsRootPath: "my-cmds", // default is `./app`
   },
@@ -375,9 +384,15 @@ bun dev
 **1 Create a `src/mod.ts` file:**
 
 ```ts
-import { runMain, defineCommand } from "@reliverse/rempts";
+import { createCli, defineCommand } from "@reliverse/rempts";
+
+// New object format (recommended)
+await createCli({
+  mainCommand: defineCommand({}),
+});
 
-await runMain(defineCommand({}));
+// Legacy format (still supported)
+await createCli(defineCommand({}));
 ```
 
 **2 Run the following:**
@@ -406,7 +421,7 @@ bun src/mod.ts
 #### Medium Usage Example
 
 ```ts
-import { defineCommand, runMain } from "@reliverse/rempts";
+import { defineCommand, createCli } from "@reliverse/rempts";
 
 const main = defineCommand({
   meta: {
@@ -417,7 +432,13 @@ const main = defineCommand({
   },
 });
 
-await runMain(main);
+// New object format (recommended)
+await createCli({
+  mainCommand: main,
+});
+
+// Legacy format (still supported)
+await createCli(main);
 ```
 
 #### Classic Usage Example
@@ -430,7 +451,7 @@ import {
   inputPrompt,
   selectPrompt,
   defineCommand,
-  runMain
+  createCli
 } from "@reliverse/rempts";
 
 const main = defineCommand({
@@ -469,7 +490,13 @@ const main = defineCommand({
   },
 });
 
-await runMain(main);
+// New object format (recommended)
+await createCli({
+  mainCommand: main,
+});
+
+// Legacy format (still supported)
+await createCli(main);
 ```
 
 #### Advanced Usage Example
@@ -584,7 +611,7 @@ const mainCommand = defineCommand({
 });
 
 /**
- * The `runMain()` function sets up the launcher with several advanced features:
+ * The `createCli()` function sets up the launcher with several advanced features:
  *
  * - File-Based Commands: Enables scanning for commands within the "app" directory.
  * - Alias Mapping: Shorthand flags (e.g., `-v`) are mapped to their full names (e.g., `--verbose`).
@@ -592,8 +619,28 @@ const mainCommand = defineCommand({
  * - Negated Boolean Support: Allows flags to be negated (e.g., `--no-verbose`).
  * - Custom Unknown Flag Handler: Provides custom handling for unrecognized flags.
  */
-await runMain(mainCommand, {
-  fileBasedCmds: {
+// New object format (recommended)
+await createCli({
+  mainCommand: mainCommand,
+  fileBased: {
+    enable: true, // Enables file-based command detection.
+    cmdsRootPath: "app", // Directory to scan for commands.
+  },
+  alias: {
+    v: "verbose", // Maps shorthand flag -v to --verbose.
+  },
+  strict: false, // Do not throw errors for unknown flags.
+  warnOnUnknown: false, // Warn when encountering unknown flags.
+  negatedBoolean: true, // Support for negated booleans (e.g., --no-verbose).
+  // unknown: (flagName) => {
+  //   relinka("warn", "Unknown flag encountered:", flagName);
+  //   return false;
+  // },
+});
+
+// Legacy format (still supported)
+await createCli(mainCommand, {
+  fileBased: {
     enable: true, // Enables file-based command detection.
     cmdsRootPath: "app", // Directory to scan for commands.
   },
@@ -634,7 +681,7 @@ Finally, a full-featured CLI launcher without the ceremony. `@reliverse/rempts`'
   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.
+  Options such as `fileBased.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.
@@ -833,7 +880,7 @@ export default defineCommand({
 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";
+import { defineCommand, createCli } from "@reliverse/rempts";
 
 const main = defineCommand({
   meta: {
@@ -877,7 +924,13 @@ const main = defineCommand({
   },
 });
 
-await runMain(main);
+// New object format (recommended)
+await createCli({
+  mainCommand: main,
+});
+
+// Legacy format (still supported)
+await createCli(main);
 ```
 
 ### Example CLI Invocations
@@ -1048,13 +1101,7 @@ The validation happens after type casting, so for example with numbers, the inpu
 
 Bug report? Prompt idea? Want to build the best DX possible?
 
-You're in the right place:
-
-- ✨ [Star the repo](https://github.com/reliverse/rempts)
-- 💬 [Join the Discord](https://discord.gg/3GawfWfAPe)
-- ❤️ [Sponsor @blefnk](https://github.com/sponsors/blefnk)
-
-> *No classes. No magic. Just clean, composable tools for CLI devs.*
+You're in the right place! Please help us make the best CLI toolkit possible.
 
 ### Notices For Contributors
 
@@ -1078,6 +1125,10 @@ All APIs are fully typed. See [`src/types.ts`](./src/types.ts) for advanced cust
 
 - [CLI application with the Node.js Readline module](https://dev.to/camptocamp-geo/cli-application-with-the-nodejs-readline-module-48ic)
 
+## 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)
+
 ## Related
 
 - [`@reliverse/cli`](https://npmjs.com/package/@reliverse/cli) – CLI-first toolkit for fullstack workflows
@@ -1089,6 +1140,18 @@ All APIs are fully typed. See [`src/types.ts`](./src/types.ts) for advanced cust
 
 - [citty](https://github.com/unjs/citty#readme) - launcher design inspiration
 
+## Support
+
+Bug report? Prompt idea? Want to build the best DX possible?
+
+You're in the right place:
+
+- ✨ [Star the repo](https://github.com/reliverse/rempts)
+- 💬 [Join the Discord](https://discord.gg/3GawfWfAPe)
+- ❤️ [Sponsor @blefnk](https://github.com/sponsors/blefnk)
+
+> *No classes. No magic. Just clean, composable tools for CLI devs.*
+
 ## License
 
-💖 MIT © [blefnk (Nazar Kornienko)](https://github.com/blefnk)
+💖 MIT (see [LICENSE](./LICENSE) and [LICENCES](./LICENSES)) © [blefnk (Nazar Kornienko)](https://github.com/blefnk)

package/bin/{components/animate/animate.js → libs/animate/animate-mod.js}

@@ -3,10 +3,7 @@ import {
 } from "@figliolia/chalk-animation";
 import { relinka } from "@reliverse/relinka";
 import { msg } from "../msg-fmt/messages.js";
-import {
-  deleteLastLine,
-  getTerminalWidth
-} from "../msg-fmt/terminal.js";
+import { deleteLastLine, getTerminalWidth } from "../msg-fmt/terminal.js";
 export const animationMap = {
   rainbow: ChalkAnimation.rainbow,
   pulse: ChalkAnimation.pulse,

package/bin/{components → libs}/anykey/anykey-mod.js

@@ -1,8 +1,8 @@
 import logUpdate from "log-update";
 import { cursor } from "sisteransi";
 import { fmt } from "../msg-fmt/messages.js";
-import { outroPrompt } from "../outro/outro-end.js";
-import { streamText } from "../../utils/stream-text.js";
+import { outroPrompt } from "../outro/outro-mod.js";
+import { streamText } from "../utils/stream-text.js";
 const DEFAULT_MESSAGE = "Press any key to continue...";
 const CTRL_C_CODE = 3;
 const terminal = {

package/bin/libs/confirm/confirm-alias.d.ts

@@ -0,0 +1 @@
+export declare const confirm: any;

package/bin/libs/confirm/confirm-alias.js

@@ -0,0 +1,2 @@
+import { confirmPrompt } from "./confirm-mod.js";
+export const confirm = confirmPrompt;

package/bin/{components/confirm/confirm-prompt.js → libs/confirm/confirm-mod.js}

@@ -3,7 +3,7 @@ import { stdin as input, stdout as output } from "node:process";
 import readline from "node:readline/promises";
 import { bar, msg } from "../msg-fmt/messages.js";
 import { deleteLastLine } from "../msg-fmt/terminal.js";
-import { completePrompt } from "../../utils/prompt-end.js";
+import { completePrompt } from "../utils/prompt-end.js";
 function renderPrompt(params) {
   const {
     title,

package/bin/{components → libs}/editor/editor-mod.js

@@ -192,11 +192,11 @@ function renderEditor() {
       const lineNum = String(fileLineIndex + 1).padStart(3);
       term(state.theme.lineNumber(`${lineNum} `));
       const line = state.lines[fileLineIndex];
-      const displayLine = line.substring(
+      const displayLine = line?.substring(
         state.leftCol,
         state.leftCol + displayWidth
       );
-      const highlightedDisplayLine = applySyntaxHighlighting(displayLine);
+      const highlightedDisplayLine = applySyntaxHighlighting(displayLine ?? "");
       term(highlightedDisplayLine);
       term.eraseLineAfter();
     } else {
@@ -237,8 +237,8 @@ function deleteCharBackward() {
     const currentLine = state.lines.splice(state.cursorY, 1)[0];
     state.cursorY--;
     const prevLine = state.lines[state.cursorY];
-    state.cursorX = prevLine.length;
-    state.lines[state.cursorY] = prevLine + currentLine;
+    state.cursorX = prevLine?.length ?? 0;
+    state.lines[state.cursorY] = prevLine + (currentLine ?? "");
     updateModifiedStatus();
   }
 }
@@ -368,7 +368,7 @@ async function confirmAction(promptMessage = "Are you sure? (y/N)") {
       no: ["n", "N", "ENTER"]
     }).promise;
     term.moveTo(1, term.height).eraseLine();
-    return confirm;
+    return confirm ?? false;
   } catch (_error) {
     term.moveTo(1, term.height).eraseLine();
     state.statusMessage = "Cancelled";
@@ -537,7 +537,7 @@ async function findText() {
   for (let y = state.cursorY; y < state.lines.length; y++) {
     const line = state.lines[y];
     const startIdx = y === state.cursorY ? state.cursorX + 1 : 0;
-    const matchIndex = line.indexOf(termToUse, startIdx);
+    const matchIndex = line?.indexOf(termToUse, startIdx) ?? -1;
     if (matchIndex !== -1) {
       state.cursorY = y;
       state.cursorX = matchIndex;
@@ -549,8 +549,8 @@ async function findText() {
     state.statusMessage = `Search wrapped: ${termToUse}`;
     for (let y = 0; y <= state.cursorY; y++) {
       const line = state.lines[y];
-      const endIdx = y === state.cursorY ? state.cursorX + 1 : line.length;
-      const matchIndex = line.substring(0, endIdx).indexOf(termToUse);
+      const endIdx = y === state.cursorY ? state.cursorX + 1 : line?.length ?? 0;
+      const matchIndex = line?.substring(0, endIdx).indexOf(termToUse) ?? -1;
       if (matchIndex !== -1) {
         state.cursorY = y;
         state.cursorX = matchIndex;

package/bin/{components → libs}/figures/figures-mod.d.ts

@@ -229,7 +229,7 @@ export declare const mainSymbols: {
     lineSlash: string;
 };
 export declare const fallbackSymbols: Record<string, string>;
-declare const figures: {
+export declare const figures: Record<string, string> | {
     tick: string;
     info: string;
     warning: string;
@@ -458,5 +458,4 @@ declare const figures: {
     lineCross: string;
     lineBackslash: string;
     lineSlash: string;
-} | Record<string, string>;
-export default figures;
+};

package/bin/{components → libs}/figures/figures-mod.js

@@ -282,5 +282,4 @@ export const fallbackSymbols = {
   ...specialFallbackSymbols
 };
 const shouldUseMain = isUnicodeSupported();
-const figures = shouldUseMain ? mainSymbols : fallbackSymbols;
-export default figures;
+export const figures = shouldUseMain ? mainSymbols : fallbackSymbols;

package/bin/libs/input/input-alias.d.ts

@@ -0,0 +1,4 @@
+import type { InputPromptOptions } from "../../types.js";
+export declare const input: any;
+export declare const text: any;
+export declare const password: (options: Omit<InputPromptOptions, "mode">) => any;

package/bin/libs/input/input-alias.js

@@ -0,0 +1,4 @@
+import { inputPrompt } from "./input-mod.js";
+export const input = inputPrompt;
+export const text = inputPrompt;
+export const password = (options) => inputPrompt({ ...options, mode: "password" });

package/bin/{components/input/input-prompt.js → libs/input/input-mod.js}

@@ -3,8 +3,8 @@ import { isUnicodeSupported } from "@reliverse/runtime";
 import readline from "node:readline/promises";
 import { bar, msg, msgUndoAll } from "../msg-fmt/messages.js";
 import { deleteLastLine } from "../msg-fmt/terminal.js";
-import { completePrompt } from "../../utils/prompt-end.js";
-import { streamText } from "../../utils/stream-text.js";
+import { completePrompt } from "../utils/prompt-end.js";
+import { streamText } from "../utils/stream-text.js";
 const unicode = isUnicodeSupported();
 const S_MASK = unicode ? "\u258B" : "*";
 function getMaskChar(customMask) {

package/bin/libs/intro/intro-alias.d.ts

@@ -0,0 +1,2 @@
+export declare const startPrompt: any;
+export declare const intro: any;

package/bin/libs/intro/intro-alias.js

@@ -0,0 +1,3 @@
+import { introPrompt } from "./intro-mod.js";
+export const startPrompt = introPrompt;
+export const intro = introPrompt;

package/bin/{components/intro/intro-start.js → libs/intro/intro-mod.js}

@@ -1,6 +1,5 @@
 import { relinka } from "@reliverse/relinka";
 import { getCurrentTerminalName } from "@reliverse/runtime";
-import { createAsciiArt } from "../ascii-art/ascii-art.js";
 import { msg } from "../msg-fmt/messages.js";
 import {
   getExactTerminalWidth,
@@ -11,8 +10,9 @@ import {
   preventWrongTerminalSize,
   preventWindowsHomeDirRoot,
   preventUnsupportedTTY
-} from "../../utils/prevent.js";
-import { pm, reliversePrompts } from "../../utils/system.js";
+} from "../utils/prevent.js";
+import { pm, reliversePrompts } from "../utils/system.js";
+import { createAsciiArt } from "../visual/visual-mod.js";
 export async function introPrompt(optionsOrTitle) {
   const options = typeof optionsOrTitle === "string" ? { title: optionsOrTitle } : optionsOrTitle;
   const {

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

@@ -0,0 +1,2 @@
+import { createCli } from "./launcher-mod";
+export declare const runMain: typeof createCli;

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

@@ -0,0 +1,2 @@
+import { createCli } from "./launcher-mod.js";
+export const runMain = createCli;

package/bin/{components → libs}/launcher/launcher-mod.d.ts

@@ -1,5 +1,5 @@
 import type { ReliArgParserOptions } from "@reliverse/reliarg";
-import type { ArgDefinitions, Command, DefineCommandOptions, EmptyArgs, FileBasedCmdsOptions } from "./launcher-types.js";
+import type { ArgDefinitions, Command, DefineCommandOptions, EmptyArgs, FileBasedOptions } from "./launcher-types.js";
 /**
  * Defines a command with metadata, argument definitions,
  * an execution function, and (optional) subCommands.
@@ -9,7 +9,7 @@ export declare function defineCommand<A extends ArgDefinitions = EmptyArgs>(opti
  * Show usage for a given command.
  */
 export declare function showUsage<A extends ArgDefinitions>(command: Command<A>, parserOptions?: ReliArgParserOptions & {
-    fileBasedCmds?: FileBasedCmdsOptions;
+    fileBased?: FileBasedOptions;
     autoExit?: boolean;
     metaSettings?: {
         showDescriptionOnMain?: boolean;
@@ -17,6 +17,10 @@ export declare function showUsage<A extends ArgDefinitions>(command: Command<A>,
     _fileBasedCurrentDir?: string;
     _fileBasedPathSegments?: string[];
     _isSubcommand?: boolean;
+}, globalCliMeta?: {
+    name?: string;
+    version?: string;
+    description?: string;
 }): Promise<void>;
 /**
  * Primary entry point to run a command. This function supports:
@@ -28,13 +32,41 @@ export declare function showUsage<A extends ArgDefinitions>(command: Command<A>,
  * This function passes along remaining arguments to command runners to ensure
  * consistent parsing.
  */
-export declare function runMain<A extends ArgDefinitions = EmptyArgs>(command: Command<A>, parserOptions?: ReliArgParserOptions & {
-    fileBasedCmds?: FileBasedCmdsOptions;
+export declare function createCli<A extends ArgDefinitions = EmptyArgs>(options: Command<A> | {
+    name?: string;
+    version?: string;
+    description?: string;
+    mainCommand?: Command<A>;
+    fileBased?: FileBasedOptions;
     autoExit?: boolean;
     metaSettings?: {
         showDescriptionOnMain?: boolean;
     };
-}): Promise<void>;
+    meta?: Command<A>["meta"];
+    args?: Command<A>["args"];
+    run?: Command<A>["run"];
+    commands?: Command<A>["commands"];
+    onCmdInit?: Command<A>["onCmdInit"];
+    onCmdExit?: Command<A>["onCmdExit"];
+    onLauncherInit?: Command<A>["onLauncherInit"];
+    onLauncherExit?: Command<A>["onLauncherExit"];
+}, legacyParserOptions?: ReliArgParserOptions & {
+    fileBased?: FileBasedOptions;
+    autoExit?: boolean;
+    metaSettings?: {
+        showDescriptionOnMain?: boolean;
+    };
+}): {
+    /**
+     * @deprecated Use createCli() directly instead. This method will be removed in a future version.
+     * @example
+     * // Instead of:
+     * createCli({...}).run()
+     * // Use:
+     * await createCli({...})
+     */
+    run(_ctx?: any): Promise<void>;
+};
 /**
  * Helper to define argument definitions with improved type inference
  * for IntelliSense and validation for array defaults against options.