@reliverse/rempts 1.6.2 → 1.7.0

package/LICENSE

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2025 Nazar Kornienko (blefnk), Reliverse
+Copyright (c) Nazar Kornienko (blefnk), Reliverse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,8 @@
-# @reliverse/rempts
+# rempts • powerful js/ts cli builder
 
-[💬 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)
+> @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.
 
-> @reliverse/rempts is a prompt library built with developer joy in mind. File-based commands. Flexible. Fast. Forget the clutter, it just works. This is a typesafe toolkit for building delightful CLI experiences.
+[💬 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
 
@@ -27,11 +27,16 @@
 
 ![Rempts Example CLI Screenshot](./example.png)
 
-## CLI Launcher (Router)
+## Terminology
+
+- **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.
 
-Finally, a full-featured CLI launcher without the ceremony. 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.
+## CLI Launcher (Router)
 
-**Key Features:**
+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.
@@ -58,13 +63,70 @@ Finally, a full-featured CLI launcher without the ceremony. The launcher support
 - **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.
 
-**Usage Example:**
+- **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.
+
+- **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.
+
+### Launcher Usage Example
+
+‼️ Go to [Usage Examples](#usage-examples) section for a more detailed example.
+
+```ts
+import { relinka } from "@reliverse/relinka";
+
+import { defineCommand, runMain } from "~/mod.js";
+
+const main = defineCommand({
+  meta: {
+    name: "rempts",
+    version: "1.0.0",
+    description: "Rempts Launcher Playground CLI",
+  },
+  setup() {
+    relinka("success", "Setup");
+  },
+  cleanup() {
+    relinka("success", "Cleanup");
+  },
+  subCommands: {
+    build: () => import("./app/build/cmd.js").then((r) => r.default),
+    deploy: () => import("./app/deploy/cmd.js").then((r) => r.default),
+    debug: () => import("./app/debug/cmd.js").then((r) => r.default),
+  },
+});
+
+await runMain(main);
+```
 
 ```ts
 await runMain(myCommand, {
   fileBasedCmds: {
     enable: true,
-    cmdsRootPath: "./cli/args",
+    cmdsRootPath: "./cli/args", // default is `./app`
   },
   // Optionally disable auto-exit to handle errors manually:
   autoExit: false,
@@ -75,9 +137,10 @@ This flexibility allows you to easily build a rich, multi-command CLI with minim
 
 ### File-Based Subcommands
 
-Drop a `./src/cli/args/add/index.ts` and it's live.
+Drop a `./src/cli/app/add/index.ts` and it's live.
 
 ```ts
+import { defineArgs, defineCommand } from "@reliverse/rempts";
 export default defineCommand({
   meta: {
     name: "add",
@@ -85,11 +148,11 @@ export default defineCommand({
     description: "Add stuff to your project",
   },
   args: {
-    name: {
+    name: defineArgs({ // 💡 PRO TIP: use defineArgs() to get fully correct intellisense
       type: "string",
       required: true,
       description: "Name of what to add",
-    },
+    }),
   },
   async run({ args }) {
     relinka("info", "Adding:", args.name);
@@ -170,8 +233,37 @@ 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
+
 ### Minimal Usage Example
 
+**1 Create a `src/mod.ts` file:**
+
+```ts
+import { runMain, defineCommand } from "@reliverse/rempts";
+
+await runMain(defineCommand({}));
+```
+
+**2 Run the following:**
+
+```bash
+bun add -D @reliverse/dler # or: bun i -g @reliverse/dler
+bun dler init --cmd my-cmd-1 # or: dler 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
+```
+
+**3 Visit `src/app/my-cmd-1/mod.ts` and edit it:**
+
+```ts
+export default defineCommand({
+  run() { console.log("Hello, world!"); },
+});
+```
+
+### Medium Usage Example
+
 ```ts
 import { defineCommand, runMain } from "@reliverse/rempts";
 
@@ -187,7 +279,7 @@ const main = defineCommand({
 await runMain(main);
 ```
 
-### Medium Usage Example
+### Classic Usage Example
 
 ```ts
 import { relinka } from "@reliverse/relinka";
@@ -209,7 +301,7 @@ const main = defineCommand({
   args: {
     name: {
       type: "string",
-      required: false,
+      required: true,
       description: "The name of the project",
     },
   },
@@ -220,7 +312,7 @@ const main = defineCommand({
 
     const name = await inputPrompt({
       title: "What's your project name?",
-      placeholder: args.name ?? "my-cool-cli",
+      placeholder: args.name,
     });
 
     const framework = await selectPrompt({
@@ -258,7 +350,7 @@ import {
  * This command demonstrates the full range of launcher features along with all supported argument types:
  *
  * - Global Usage Handling: Automatically processes `--help` and `--version`.
- * - File-Based Subcommands: Scans "src/cli/args" for subcommands (e.g., `init`).
+ * - File-Based Subcommands: Scans "app" for subcommands (e.g., `init`).
  * - Comprehensive Argument Parsing: Supports positional, boolean, string, number, and array arguments.
  * - Interactive Prompts: Uses built-in prompt functions for an engaging CLI experience.
  */
@@ -273,12 +365,10 @@ const mainCommand = defineCommand({
     // Positional arguments
     inputFile: {
       type: "positional",
-      required: false,
       description: "Path to the input file (only for the main command).",
     },
     config: {
       type: "positional",
-      required: false,
       description: "Path to the configuration file.",
     },
     // Boolean arguments
@@ -295,20 +385,17 @@ const mainCommand = defineCommand({
     // String argument
     name: {
       type: "string",
-      required: false,
       description: "The name of the project.",
     },
     // Number argument
     timeout: {
       type: "number",
-      required: false,
       default: 30,
       description: "Timeout in seconds for the CLI operation.",
     },
     // Array argument
     tags: {
       type: "array",
-      required: false,
       default: ["cli", "rempts"],
       description: "List of tags associated with the project.",
     },
@@ -358,7 +445,7 @@ const mainCommand = defineCommand({
 /**
  * The `runMain()` function sets up the launcher with several advanced features:
  *
- * - File-Based Subcommands: Enables scanning for subcommands within the "src/cli/args" directory.
+ * - File-Based Subcommands: Enables scanning for subcommands within the "app" directory.
  * - Alias Mapping: Shorthand flags (e.g., `-v`) are mapped to their full names (e.g., `--verbose`).
  * - Strict Mode & Unknown Flag Warnings: Unknown flags are either warned about or handled via a callback.
  * - Negated Boolean Support: Allows flags to be negated (e.g., `--no-verbose`).
@@ -367,7 +454,7 @@ const mainCommand = defineCommand({
 await runMain(mainCommand, {
   fileBasedCmds: {
     enable: true, // Enables file-based subcommand detection.
-    cmdsRootPath: "src/cli/args", // Directory to scan for subcommands.
+    cmdsRootPath: "app", // Directory to scan for subcommands.
   },
   alias: {
     v: "verbose", // Maps shorthand flag -v to --verbose.

package/bin/{core-impl → components}/anykey/anykey-mod.d.ts

@@ -1,4 +1,4 @@
-import type { ColorName } from "../../core-types.js";
+import type { ColorName } from "../../types.js";
 type Options = {
     ctrlC?: number | false | "reject";
     preserveLog?: boolean;

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

@@ -2,7 +2,7 @@ import logUpdate from "log-update";
 import { cursor } from "sisteransi";
 import { fmt } from "../msg-fmt/messages.js";
 import { endPrompt } from "../st-end/end.js";
-import { streamText } from "../utils/stream-text.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/{core-impl → components}/date/date.d.ts

@@ -1,2 +1,2 @@
-import type { DatePromptOptions } from "../../core-types.js";
+import type { DatePromptOptions } from "../../types.js";
 export declare function datePrompt(opts: DatePromptOptions): Promise<string>;

package/bin/{core-impl → components}/editor/editor-mod.d.ts

@@ -1,4 +1,4 @@
-import type { EditorExitResult } from "../../core-types.js";
+import type { EditorExitResult } from "../../types.js";
 type EditorConfig = {
     syntaxHighlighting?: boolean;
     theme?: "auto" | "light" | "dark";

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

@@ -43,11 +43,11 @@ let state = {
   theme: {
     // Default Light Theme
     text: (str) => str,
-    statusBarBg: (str) => re.bgGray(str),
+    statusBarBg: (str) => re.bgBrown(str),
     statusBarText: (str) => re.white(str),
-    highlight: (str) => re.invert(str),
+    highlight: (str) => re.bgYellow(re.black(str)),
     // For search results, etc.
-    lineNumber: (str) => re.gray(str)
+    lineNumber: (str) => re.blue(str)
   },
   syntaxHighlightToggle: false,
   // Toggled state for syntax highlighting
@@ -91,7 +91,7 @@ function setupTheme(configTheme) {
   } else {
     state.theme = {
       text: (str) => re.black(str),
-      statusBarBg: (str) => re.bgGray(str),
+      statusBarBg: (str) => re.bgBrown(str),
       statusBarText: (str) => re.white(str),
       highlight: (str) => re.bgCyan(re.black(str)),
       lineNumber: (str) => re.gray(str)
@@ -808,10 +808,10 @@ async function initializeEditorState(options) {
     state.theme = {
       // Reset theme based on config
       text: (str) => str,
-      statusBarBg: (str) => re.bgGray(str),
+      statusBarBg: (str) => re.bgBrown(str),
       statusBarText: (str) => re.white(str),
-      highlight: (str) => re.invert(str),
-      lineNumber: (str) => re.gray(str)
+      highlight: (str) => re.bgYellow(re.black(str)),
+      lineNumber: (str) => re.blue(str)
     };
     setupTheme(state.editorConfig.theme);
   } catch (error) {

package/bin/{core-impl → components}/input/confirm-prompt.d.ts

@@ -1,4 +1,4 @@
-import type { ConfirmPromptOptions } from "../../core-types.js";
+import type { ConfirmPromptOptions } from "../../types.js";
 /**
  * Prompts the user with a yes/no question, returning a boolean based on their input.
  */

package/bin/{core-impl → components}/input/confirm-prompt.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/{core-impl → components}/input/input-prompt.d.ts

@@ -1,4 +1,4 @@
-import type { InputPromptOptions } from "../../core-types.js";
+import type { InputPromptOptions } from "../../types.js";
 /**
  * inputPrompt()
  *

package/bin/{core-impl → components}/input/input-prompt.js

@@ -1,14 +1,10 @@
 import { re } from "@reliverse/relico";
 import { isUnicodeSupported } from "@reliverse/runtime";
 import readline from "node:readline/promises";
-import {
-  bar,
-  msg,
-  msgUndoAll
-} from "../msg-fmt/messages.js";
+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/{core-impl → components}/launcher/deprecated/_parser.ts.txt

@@ -2,7 +2,7 @@ import type {
   Default,
   ParserArgv,
   ParserOptions,
-} from "~/libs/core/core-types.js";
+} from "~/types.js";
 
 function toArr(any: any) {
   // biome-ignore lint/suspicious/noDoubleEquals: <explanation>

package/bin/{core-impl → components}/launcher/deprecated/_utils.ts.txt

@@ -1,4 +1,4 @@
-import type { Resolvable } from "~/libs/core/core-types.js";
+import type { Resolvable } from "~/types.js";
 
 export function toArray(val: any) {
   if (Array.isArray(val)) {

package/bin/{core-impl → components}/launcher/deprecated/args.ts.txt

@@ -1,6 +1,6 @@
 import { kebabCase, camelCase } from "scule";
 
-import type { Arg, ArgsDef, ParsedArgs } from "~/libs/core/core-types.js";
+import type { Arg, ArgsDef, ParsedArgs } from "~/types.js";
 
 import { parseRawArgs } from "./_parser.js";
 import { CLIError, toArray } from "./_utils.js";

package/bin/{core-impl → components}/launcher/deprecated/command.ts.txt

@@ -3,7 +3,7 @@ import type {
   CommandContext,
   CommandDef,
   RunCommandOptions,
-} from "~/libs/core/core-types.js";
+} from "~/types.js";
 
 import { CLIError, resolveValue } from "./_utils.js";
 import { parseArgs } from "./args.js";

package/bin/{core-impl → components}/launcher/deprecated/launcher-mod.ts.txt

@@ -1,6 +1,6 @@
 import { relinka } from "@reliverse/relinka";
 
-import type { ArgsDef, CommandDef } from "~/libs/core/core-types.js";
+import type { ArgsDef, CommandDef } from "~/types.js";
 
 import { CLIError } from "./_utils.js";
 import { resolveSubCommand, runCommand } from "./command.js";

package/bin/{core-impl → components}/launcher/deprecated/usage.ts.txt

@@ -1,7 +1,7 @@
 import { re } from "@reliverse/relico";
 import { relinka } from "@reliverse/relinka";
 
-import type { ArgsDef, CommandDef } from "~/libs/core/core-types.js";
+import type { ArgsDef, CommandDef } from "~/types.js";
 
 import { formatLineColumns, resolveValue } from "./_utils.js";
 import { resolveArgs } from "./args.js";

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

@@ -1,25 +1,34 @@
 import type { ReliArgParserOptions } from "@reliverse/reliarg";
+type InvalidDefaultError<O extends readonly string[]> = {
+    __error__: "Default value(s) must be a subset of options";
+    options: O;
+};
 type EmptyArgs = Record<string, never>;
-type BaseArgDefinition = {
+type BaseArgProps = {
     description?: string;
     required?: boolean;
-    default?: any;
 };
 type PositionalArgDefinition = {
     type: "positional";
-} & BaseArgDefinition;
+    default?: string;
+} & BaseArgProps;
 type BooleanArgDefinition = {
     type: "boolean";
-} & BaseArgDefinition;
+    default?: boolean;
+} & BaseArgProps;
 type StringArgDefinition = {
     type: "string";
-} & BaseArgDefinition;
+    default?: string;
+} & BaseArgProps;
 type NumberArgDefinition = {
     type: "number";
-} & BaseArgDefinition;
+    default?: number;
+} & BaseArgProps;
 type ArrayArgDefinition = {
     type: "array";
-} & BaseArgDefinition;
+    default?: string | readonly string[];
+    options: readonly string[];
+} & BaseArgProps;
 export type ArgDefinition = PositionalArgDefinition | BooleanArgDefinition | StringArgDefinition | NumberArgDefinition | ArrayArgDefinition;
 export type ArgDefinitions = Record<string, ArgDefinition>;
 type CommandMeta = {
@@ -45,19 +54,37 @@ type CommandContext<ARGS> = {
 };
 type CommandRun<ARGS> = (ctx: CommandContext<ARGS>) => void | Promise<void>;
 type DefineCommandOptions<A extends ArgDefinitions = EmptyArgs> = {
-    meta: CommandMeta;
+    meta?: CommandMeta;
     args?: A;
-    run: CommandRun<InferArgTypes<A>>;
+    run?: CommandRun<InferArgTypes<A>>;
     subCommands?: SubCommandsMap;
+    setup?: () => void | Promise<void>;
+    cleanup?: () => void | Promise<void>;
 };
 export type Command<A extends ArgDefinitions = EmptyArgs> = {
-    meta: CommandMeta;
+    meta?: CommandMeta;
     args: A;
-    run: CommandRun<InferArgTypes<A>>;
+    run?: CommandRun<InferArgTypes<A>>;
     subCommands?: SubCommandsMap;
+    setup?: () => void | Promise<void>;
+    cleanup?: () => 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 ArrayArgDefinition ? string[] : never;
+    [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 {
+        type: "array";
+        options: infer O extends readonly string[];
+    } ? O[number][] : never;
+};
+type ValidateArrayDefaults<A extends ArgDefinitions> = {
+    [K in keyof A]: A[K] extends {
+        type: "array";
+        options: infer O extends readonly string[];
+        default?: infer D;
+    } ? D extends undefined ? A[K] : D extends O[number] ? A[K] : D extends readonly (infer E)[] ? E extends O[number] ? A[K] : Omit<A[K], "default"> & {
+        default: InvalidDefaultError<O>;
+    } : Omit<A[K], "default"> & {
+        default: InvalidDefaultError<O>;
+    } : A[K];
 };
 export type FileBasedCmdsOptions = {
     enable: boolean;
@@ -74,7 +101,10 @@ export declare function defineCommand<A extends ArgDefinitions = EmptyArgs>(opti
 export declare function showUsage<A extends ArgDefinitions>(command: Command<A>, parserOptions?: ReliArgParserOptions & {
     fileBasedCmds?: FileBasedCmdsOptions;
     autoExit?: boolean;
-}): Promise<void>;
+    metaSettings?: {
+        showDescriptionOnMain?: boolean;
+    };
+}, displayNotFoundMessage?: boolean): Promise<void>;
 /**
  * Primary entry point to run a command. This function supports:
  *
@@ -88,5 +118,16 @@ export declare function showUsage<A extends ArgDefinitions>(command: Command<A>,
 export declare function runMain<A extends ArgDefinitions = EmptyArgs>(command: Command<A>, parserOptions?: ReliArgParserOptions & {
     fileBasedCmds?: FileBasedCmdsOptions;
     autoExit?: boolean;
+    metaSettings?: {
+        showDescriptionOnMain?: boolean;
+    };
 }): Promise<void>;
+/**
+ * Helper to define argument definitions with improved type inference
+ * for IntelliSense and validation for array defaults against options.
+ *
+ * **Note:** For array types, use `as const` on the `options` array to enable
+ * precise default value validation (e.g., `options: ["a", "b"] as const`).
+ */
+export declare function defineArgs<A extends ArgDefinitions>(args: A & ValidateArrayDefaults<A>): A;
 export {};