@reliverse/rempts-core 1.6.1 → 2.3.1

package/README.md

@@ -1,102 +1,398 @@
-# @reliverse/prompts
-
-[💖 GitHub Sponsors](https://github.com/sponsors/blefnk) • [💬 Discord](https://discord.gg/3GawfWfAPe) • [📦 NPM](https://npmjs.com/package/@reliverse/prompts) • [📚 Docs](https://docs.reliverse.org/reliverse/prompts) • [✨ GitHub](https://github.com/reliverse/prompts)
-
-**@reliverse/prompts** is your modern, type-safe toolkit for building delightful CLI experiences. It's fast, flexible, and built with developer joy in mind. Forget the clutter — this is how CLI should feel.
-
-## ⚡ Why It Rocks
-
-- ✨ **TypeScript-first** — fully typed prompts and helpers, with great DX
-- 🔧 **Flexible Prompt Types** — input, password, select, multiselect, confirm, toggle, number, spinner, and more
-- 🧠 **Smart validation** — works with Zod, TypeBox, or your own validators
-- 🌈 **Accessible & Adaptive** — meets WCAG AA, handles terminal resizing & color contrast
-- 🧯 **Crash-resistant** — gracefully exits on Ctrl+C or unexpected input
-- 🎨 **Custom theming** — make it match your CLI style
-- 🚀 **Zero boilerplate** — focus on the logic, not the wiring
-
-## 🛠️ Install
-
-```bash
-bun add @reliverse/prompts
-# or npm, pnpm, yarn
-```
-
-Make sure you have [Bun](https://bun.sh), [Node.js](https://nodejs.org), and [Git](https://git-scm.com/downloads) installed.
-
-## 🧪 Try It Out (Playground Mode)
-
-Wanna test drive before integrating? Clone the repo and run:
-
-```bash
-git clone https://github.com/reliverse/prompts.git
-cd prompts
-bun i
-bun dev
-```
-
-Then open `examples/launcher.ts` and explore different prompts.
-
-![example](./examples/main.png)
-
-## 🧩 Example Usage
-
-```ts
-import {
-  startPrompt, // Initialize prompt session (optional)
-  inputPrompt, // Ask for user input
-} from "@reliverse/prompts";
-
-await startPrompt({
-  clearConsole: true,
-  titleColor: "inverse",
-  packageName: "@reliverse/cli",
-  packageVersion: "1.0.0",
-});
-
-const username = await inputPrompt({
-  id: "username",
-  title: "Welcome!",
-  content: "What's your name?",
-});
-
-console.log(`Hey there, ${username}!`);
-```
-
-> 🔎 You can also use `selectPrompt`, `multiselectPrompt`, `confirmPrompt`, `numberPrompt`, `spinnerPrompt`, and more.
-
-## 🧠 Bonus Goodies
-
-- ⚙️ **Built-in argument parsing** — parse CLI args without a separate lib
-- 🧪 **Unit-test friendly** — prompts can be mocked/stubbed
-- 📚 **Minimal API surface** — easy to learn, hard to outgrow
-- 💅 **Custom styles** — tweak colors, formats, and transitions
-
-## 🔍 Why not Inquirer or Clack?
-
-While we love other tools, `@reliverse/prompts` was built for:
-
-- Dev-first ergonomics
-- Fully typed workflows
-- Configurable theming
-- Better crash handling & UX polish
-
-[See feature comparison →](https://docs.reliverse.org/reliverse/prompts/#prompts-library-comparison)
-
-## 💡 Contributing
-
-Wanna improve prompts or add something cool? PRs welcome!  
-This project favors functional programming over OOP — no classes, just clean, composable logic.
-
-Open a PR or discussion on [GitHub](https://github.com/reliverse/prompts).
-
-## 🙏 Shoutout
-
-This wouldn't exist without these gems:
-
-- [sboudrias/inquirer.js](https://github.com/sboudrias/inquirer.js)
-- [unjs/citty](https://github.com/unjs/citty)
-- [lukeed/mri](https://github.com/lukeed/mri)
-
-## 📄 License
-
-💖 MIT © 2025 [blefnk Nazar Kornienko](https://github.com/blefnk)
+# rempts-core
+
+The minimal, type-safe CLI framework for Bun.
+
+## Installation
+
+```bash
+bun add rempts-core
+```
+
+## Quick Start
+
+```typescript
+import { defineCommand, option } from '@reliverse/rempts-core'
+import { type } from 'arktype'
+
+export default defineCommand({
+  name: 'greet',
+  description: 'A friendly greeting',
+  options: {
+    name: option(
+      type("string", ">0"),
+      { description: 'Name to greet', short: 'n' }
+    ),
+    excited: option(
+      type("boolean", "=", false),
+      { description: 'Add excitement', short: 'e' }
+    )
+  },
+  handler: async ({ flags }) => {
+    const greeting = `Hello, ${flags.name}${flags.excited ? '!' : '.'}`
+    console.log(greeting)
+  }
+})
+```
+
+## Features
+
+- 🚀 **Type-safe** - Full TypeScript support with automatic type inference
+- ⚡ **Fast** - Powered by Bun's native speed
+- 📦 **Zero config** - Works out of the box with sensible defaults
+- 🎯 **Minimal API** - Learn once, use everywhere
+- 🔌 **Extensible** - Plugin system for custom functionality
+- 🧪 **Testable** - First-class testing utilities included
+
+## Core Concepts
+
+### Commands
+
+Define commands with automatic type inference:
+
+```typescript
+import { defineCommand } from '@reliverse/rempts-core'
+
+export default defineCommand({
+  name: 'build',
+  description: 'Build the project',
+  handler: async () => {
+    console.log('Building...')
+  }
+})
+```
+
+### Options
+
+Use the `option` helper with Standard Schema validation:
+
+```typescript
+import { defineCommand, option } from '@reliverse/rempts-core'
+import { type } from 'arktype'
+
+export default defineCommand({
+  name: 'deploy',
+  options: {
+    env: option(
+      type("'dev'|'staging'|'prod'"),
+      { description: 'Target environment' }
+    ),
+    force: option(
+      type("boolean", "=", false),
+      { description: 'Force deployment', short: 'f' }
+    )
+  },
+  handler: async ({ flags }) => {
+    // TypeScript knows:
+    // flags.env is 'dev' | 'staging' | 'prod'
+    // flags.force is boolean
+  }
+})
+```
+
+### Multi-Command CLIs
+
+Create complex CLIs with multiple commands:
+
+```typescript
+import { createCLI } from '@reliverse/rempts-core'
+import build from './commands/build'
+import deploy from './commands/deploy'
+import test from './commands/test'
+
+const cli = createCLI({
+  name: 'my-tool',
+  version: '1.0.0',
+  description: 'My awesome CLI tool',
+  commands: [build, deploy, test]
+})
+
+await cli.run()
+```
+
+## API Reference
+
+### `defineCommand(config)`
+
+Creates a command definition with full type inference.
+
+### `option(schema, config)`
+
+Creates a typed option with schema validation.
+
+### `createCLI(config)`
+
+Creates a multi-command CLI application.
+
+### `defineConfig(config)`
+
+Defines shared configuration for your CLI.
+
+## Plugin System
+
+Rempts provides a powerful plugin system with compile-time type safety:
+
+### Basic Plugin
+
+```typescript
+import { RemptsPlugin, createPlugin } from '@reliverse/rempts-core'
+
+interface MyPluginStore {
+  apiKey: string
+  isAuthenticated: boolean
+}
+
+const myPlugin: RemptsPlugin<MyPluginStore> = {
+  name: 'my-plugin',
+  version: '1.0.0',
+
+  // Define the plugin's store
+  store: {
+    apiKey: '',
+    isAuthenticated: false
+  },
+
+  // Lifecycle hooks
+  setup(context) {
+    // One-time initialization
+    context.updateConfig({ customField: 'value' })
+  },
+
+  configResolved(config) {
+    // Called after all configuration is resolved
+  },
+
+  beforeCommand(context) {
+    // Called before each command - context.store is type-safe!
+    context.store.apiKey = process.env.API_KEY || ''
+    context.store.isAuthenticated = !!context.store.apiKey
+  },
+
+  afterCommand(context) {
+    // Called after each command with results
+    if (context.error) {
+      console.error('Command failed:', context.error)
+    }
+  }
+}
+```
+
+### Plugin Factory
+
+Use `createPlugin` for better ergonomics:
+
+```typescript
+import { createPlugin } from '@reliverse/rempts-core'
+
+export const authPlugin = createPlugin((options: AuthOptions) => {
+  return {
+    name: 'auth-plugin',
+    store: {
+      token: '',
+      user: null as User | null
+    },
+    async beforeCommand(context) {
+      const token = await loadToken()
+      context.store.token = token
+      context.store.user = await fetchUser(token)
+    }
+  }
+})
+```
+
+### Using Plugins with Type Safety
+
+```typescript
+const cli = await createCLI({
+  name: 'my-cli',
+  version: '1.0.0',
+  plugins: [
+    authPlugin({ provider: 'github' }),
+    myPlugin
+  ]
+})
+
+// In your command files (e.g., cmds/deploy/cmd.ts), the store is fully typed!
+// cmds/deploy/cmd.ts
+import { defineCommand } from '@reliverse/rempts-core'
+
+export default defineCommand({
+  name: 'deploy',
+  handler: async ({ context }) => {
+    // TypeScript knows about all plugin stores!
+    if (!context?.store.isAuthenticated) {
+      throw new Error('Not authenticated')
+    }
+    console.log(`Deploying as ${context.store.user?.name}`)
+  }
+})
+```
+
+### Plugin Development Utilities
+
+Rempts provides utilities for plugin development and testing:
+
+```typescript
+import {
+  createTestPlugin,
+  composePlugins,
+  createMockPluginContext,
+  testPluginHooks,
+  assertPluginBehavior
+} from '@reliverse/rempts-core/plugin'
+
+// Create a test plugin
+const testPlugin = createTestPlugin(
+  { count: 0, message: '' },
+  {
+    beforeCommand(context) {
+      context.store.count++
+      console.log(`Count: ${context.store.count}`)
+    }
+  }
+)
+
+// Compose multiple plugins
+const composedPlugin = composePlugins(
+  authPlugin({ provider: 'github' }),
+  loggingPlugin({ level: 'debug' }),
+  metricsPlugin({ enabled: true })
+)
+
+// Test plugin behavior
+const results = await testPluginHooks(testPlugin, {
+  config: { name: 'test-cli', version: '1.0.0' },
+  store: { count: 0, message: 'test' }
+})
+
+assertPluginBehavior(results, {
+  beforeCommandShouldSucceed: true
+})
+```
+
+### Module Augmentation
+
+Plugins can extend Rempts's interfaces:
+
+```typescript
+declare module '@reliverse/rempts-core' {
+  interface EnvironmentInfo {
+    isCI: boolean
+    ciProvider?: string
+  }
+}
+```
+
+## Runtime Validation
+
+Rempts provides runtime validation utilities for dynamic type checking:
+
+```typescript
+import {
+  validateValue,
+  validateValues,
+  isValueOfType,
+  createValidator,
+  createBatchValidator
+} from '@reliverse/rempts-core'
+
+// Validate a single value
+const result = await validateValue(
+  'hello',
+  type("string", ">0"),
+  { option: 'message', command: 'greet' }
+)
+
+// Validate multiple values
+const validated = await validateValues(
+  { name: 'John', age: 25 },
+  {
+    name: type("string"),
+    age: type("number")
+  },
+  'user'
+)
+
+// Check value types
+if (isValueOfType(value, 'string')) {
+  console.log('Value is a string')
+}
+
+// Create reusable validators
+const nameValidator = createValidator(type("string", ">0"))
+const userValidator = createBatchValidator({
+  name: type("string"),
+  age: type("number")
+})
+```
+
+## Type Utilities
+
+Rempts exports advanced TypeScript type utilities for complex type manipulation:
+
+```typescript
+import {
+  UnionToIntersection,
+  MergeAll,
+  Expand,
+  DeepPartial,
+  Constrain,
+  NonEmptyArray,
+  IsNever,
+  IsAny,
+  IsUnknown
+} from '@reliverse/rempts-core'
+```
+
+### Key Utilities
+
+**UnionToIntersection** - Convert union types to intersection types:
+
+```typescript
+type Example = UnionToIntersection<{ a: string } | { b: number }>
+// Result: { a: string } & { b: number }
+```
+
+**MergeAll** - Merge multiple object types:
+
+```typescript
+type Example = MergeAll<[{ a: string }, { b: number }, { c: boolean }]>
+// Result: { a: string; b: number; c: boolean }
+```
+
+**Expand** - Expand complex types for better IntelliSense:
+
+```typescript
+type Example = Expand<{ nested: { deep: { value: string } } }>
+// Shows full type structure in IDE
+```
+
+**DeepPartial** - Make all properties optional recursively:
+
+```typescript
+type Example = DeepPartial<{ user: { name: string; age: number } }>
+// Result: { user?: { name?: string; age?: number } }
+```
+
+**Constrain** - Constrain types with fallback:
+
+```typescript
+type Example = Constrain<string, 'a' | 'b' | 'c', 'a'>
+// Result: 'a' | 'b' | 'c' (or 'a' if string doesn't match)
+```
+
+
+## Related Packages
+
+- **[rempts-generator](/docs/packages/generator)** - Generate TypeScript definitions from commands
+- **[rempts-utils](/docs/packages/utils)** - Shared utilities for CLI development
+- **[rempts-test](/docs/packages/test)** - Testing utilities for CLI applications
+
+## Documentation
+
+- [Getting Started](/docs/getting-started) - Step-by-step tutorial
+- [Type Generation Guide](/docs/guides/type-generation) - Learn about code generation
+- [API Reference](/docs/api) - Complete API documentation
+
+## License
+
+MIT © blefnk

package/dist/cli.d.ts

@@ -0,0 +1,32 @@
+import type { MergePluginStores, Plugin } from "./plugin/types.js";
+import type { CLI, RemptsConfig } from "./types.js";
+export declare function createApp<TPlugins extends readonly Plugin[] = [], TDefaultCommand extends string | undefined = undefined>(options?: {
+    /**
+     * CLI configuration override
+     */
+    config?: Partial<RemptsConfig> & {
+        plugins?: TPlugins;
+    };
+    /**
+     * Default command to run when no arguments are provided
+     */
+    defaultCommand?: TDefaultCommand;
+    /**
+     * Whether to auto-initialize commands from config
+     * @default true
+     */
+    autoInit?: boolean;
+    /**
+     * Custom config directory (overrides --cwd detection)
+     */
+    configDir?: string;
+    /**
+     * Entry file path (e.g., import.meta.path or __filename)
+     * If not provided, will be auto-detected from call stack
+     * Commands directory will be <entry-file-dir>/cmds
+     */
+    entryFile?: string;
+}): Promise<CLI<MergePluginStores<TPlugins>>>;
+export declare function createCLI<TPlugins extends readonly Plugin[] = []>(configOverride?: Partial<RemptsConfig> & {
+    plugins?: TPlugins;
+}, entryFile?: string): Promise<CLI<MergePluginStores<TPlugins>>>;