mepcli 2.0.0-beta.2 → 2.0.0-beta.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 CodeTease
+Copyright (c) 2025-2026 CodeTease
 
 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

@@ -255,6 +255,26 @@ const result = await new Pipeline<Context>()
     .run();
 ```
 
+## Extensions (Custom Prompts)
+
+Mep is fully extensible. You can register your own prompt components and access them through the unified `MepCLI.prompt()` API with full Type Safety.
+
+```typescript
+import { MepCLI } from 'mepcli';
+import { MyPrompt } from './MyPrompt';
+
+// 1. Register
+MepCLI.register('custom', MyPrompt);
+
+// 2. Use with full type support
+const result = await MepCLI.prompt({
+    type: 'custom',
+    message: 'Hello from extension!'
+});
+```
+
+See the **[Extension Registry Guide](./docs/guides/extension-registry.md)** for more details.
+
 ## Keyboard & Mouse Support
 
 For a detailed list of shortcuts and mouse interactions, please refer to the **[Shortcuts Documentation](./docs/features/shortcuts.md)**.

package/dist/ansi.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ANSI Escape Codes
+ * Manual definitions to maintain zero-dependency status.
+ */
+export declare const ANSI: {
+    RESET: string;
+    BOLD: string;
+    DIM: string;
+    ITALIC: string;
+    UNDERLINE: string;
+    REVERSE: string;
+    FG_GREEN: string;
+    FG_CYAN: string;
+    FG_YELLOW: string;
+    FG_RED: string;
+    FG_GRAY: string;
+    FG_WHITE: string;
+    FG_BLUE: string;
+    FG_MAGENTA: string;
+    FG_BLACK: string;
+    BG_YELLOW: string;
+    BG_BLUE: string;
+    BG_CYAN: string;
+    BG_GREEN: string;
+    BG_RED: string;
+    ERASE_LINE: string;
+    ERASE_DOWN: string;
+    CURSOR_LEFT: string;
+    HIDE_CURSOR: string;
+    SHOW_CURSOR: string;
+    UP: string;
+    DOWN: string;
+    SET_ANY_EVENT_MOUSE: string;
+    SET_SGR_EXT_MODE_MOUSE: string;
+    DISABLE_MOUSE: string;
+};

package/dist/ansi.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});Object.defineProperty(exports,"ANSI",{enumerable:true,get:function(){return ANSI}});const ANSI={RESET:"\x1b[0m",BOLD:"\x1b[1m",DIM:"\x1b[2m",ITALIC:"\x1b[3m",UNDERLINE:"\x1b[4m",REVERSE:"\x1b[7m",FG_GREEN:"\x1b[32m",FG_CYAN:"\x1b[36m",FG_YELLOW:"\x1b[33m",FG_RED:"\x1b[31m",FG_GRAY:"\x1b[90m",FG_WHITE:"\x1b[37m",FG_BLUE:"\x1b[34m",FG_MAGENTA:"\x1b[35m",FG_BLACK:"\x1b[30m",BG_YELLOW:"\x1b[43m",BG_BLUE:"\x1b[44m",BG_CYAN:"\x1b[46m",BG_GREEN:"\x1b[42m",BG_RED:"\x1b[41m",ERASE_LINE:"\x1b[2K",ERASE_DOWN:"\x1b[J",CURSOR_LEFT:"\x1b[1000D",HIDE_CURSOR:"\x1b[?25l",SHOW_CURSOR:"\x1b[?25h",UP:"\x1b[A",DOWN:"\x1b[B",SET_ANY_EVENT_MOUSE:"\x1b[?1003h",SET_SGR_EXT_MODE_MOUSE:"\x1b[?1006h",DISABLE_MOUSE:"\x1b[?1003l\x1b[?1006l"};

package/dist/base.d.ts

@@ -0,0 +1,61 @@
+import { MouseEvent } from './types';
+import { detectCapabilities } from './utils';
+/**
+ * Abstract base class for all prompts.
+ * Implements a Robust Linear Scan Diffing Engine.
+ */
+export type PromptConstructor<T, O> = new (options: O) => Prompt<T, O>;
+export declare abstract class Prompt<T, O> {
+    protected options: O;
+    protected value: any;
+    protected stdin: NodeJS.ReadStream;
+    protected stdout: NodeJS.WriteStream;
+    private _resolve?;
+    private _reject?;
+    private _inputParser;
+    private _onKeyHandler?;
+    private _onDataHandler?;
+    private static warnedComponents;
+    protected lastRenderLines: string[];
+    protected lastRenderHeight: number;
+    protected capabilities: ReturnType<typeof detectCapabilities>;
+    constructor(options: O);
+    /**
+     * Checks if running on Windows and logs a warning message once per component type.
+     * Call this in the constructor of problematic prompts.
+     */
+    protected checkWindowsAttention(): void;
+    /**
+     * Warn about experimental prompts.
+     * Call this in the constructor of experimental prompts.
+     */
+    protected warnExperimental(): void;
+    protected abstract render(firstRender: boolean): void;
+    protected abstract handleInput(char: string, key: Buffer): void;
+    protected handleMouse(_event: MouseEvent): void;
+    protected print(text: string): void;
+    run(): Promise<T>;
+    /**
+     * Pauses the input stream and removes listeners.
+     * Useful for yielding control to child processes.
+     */
+    protected pauseInput(): void;
+    /**
+     * Resumes the input stream and re-attaches listeners.
+     */
+    protected resumeInput(): void;
+    protected cleanup(): void;
+    protected submit(result: T): void;
+    protected cancel(reason: any): void;
+    /**
+     * Renders the frame using a linear scan diffing algorithm.
+     * Prevents flicker and handles height changes (expand/collapse) robustly.
+     */
+    protected renderFrame(content: string): void;
+    protected stripAnsi(str: string): string;
+    protected truncate(str: string, width: number): string;
+    protected isUp(char: string): boolean;
+    protected isDown(char: string): boolean;
+    protected isRight(char: string): boolean;
+    protected isLeft(char: string): boolean;
+}

package/dist/base.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});Object.defineProperty(exports,"Prompt",{enumerable:true,get:function(){return Prompt}});const _ansi=require("./ansi");const _input=require("./input");const _utils=require("./utils");function _define_property(obj,key,value){if(key in obj){Object.defineProperty(obj,key,{value:value,enumerable:true,configurable:true,writable:true})}else{obj[key]=value}return obj}let Prompt=class Prompt{checkWindowsAttention(){const componentName=this.constructor.name;if(process.platform==="win32"&&!Prompt.warnedComponents.has(componentName)){console.warn(`${_ansi.ANSI.FG_YELLOW}Warning:${_ansi.ANSI.RESET} ${componentName} may hang on Windows TTY after multiple cycles. `+`Press 'Enter' if unresponsive.`);Prompt.warnedComponents.add(componentName)}}warnExperimental(){const componentName=this.constructor.name;if(!Prompt.warnedComponents.has(componentName)){console.warn(`${_ansi.ANSI.FG_YELLOW}Warning:${_ansi.ANSI.RESET} ${componentName} is an experimental prompt and may have bugs or unexpected behavior. `+`Use with caution.`);Prompt.warnedComponents.add(componentName)}}handleMouse(_event){}print(text){this.stdout.write(text)}run(){return new Promise((resolve,reject)=>{this._resolve=resolve;this._reject=reject;if(typeof this.stdin.setRawMode==="function"){this.stdin.setRawMode(true)}this.stdin.resume();this.stdin.setEncoding("utf8");const shouldEnableMouse=this.options.mouse!==false&&this.capabilities.hasMouse;if(shouldEnableMouse){this.print(_ansi.ANSI.SET_ANY_EVENT_MOUSE+_ansi.ANSI.SET_SGR_EXT_MODE_MOUSE)}this.print(_ansi.ANSI.HIDE_CURSOR);this.render(true);this._onKeyHandler=(char,buffer)=>{if(char==="\x03"){this.cleanup();this.print(_ansi.ANSI.SHOW_CURSOR+"\n");if(this._reject)this._reject(new Error("User force closed"));return}this.handleInput(char,buffer)};this._inputParser.on("keypress",this._onKeyHandler);this._inputParser.on("mouse",event=>{this.handleMouse(event)});this._onDataHandler=buffer=>{this._inputParser.feed(buffer)};this.stdin.on("data",this._onDataHandler)})}pauseInput(){if(this._onDataHandler){this.stdin.removeListener("data",this._onDataHandler)}if(typeof this.stdin.setRawMode==="function"){this.stdin.setRawMode(false)}this.stdin.pause()}resumeInput(){if(typeof this.stdin.setRawMode==="function"){this.stdin.setRawMode(true)}this.stdin.resume();if(this._onDataHandler){this.stdin.on("data",this._onDataHandler)}}cleanup(){if(this._onDataHandler){this.stdin.removeListener("data",this._onDataHandler)}if(this._onKeyHandler){this._inputParser.removeListener("keypress",this._onKeyHandler)}this.print(_ansi.ANSI.DISABLE_MOUSE);if(typeof this.stdin.setRawMode==="function"){this.stdin.setRawMode(false)}this.stdin.pause();this.print(_ansi.ANSI.SHOW_CURSOR)}submit(result){this.cleanup();this.print("\n");if(this._resolve)this._resolve(result)}cancel(reason){this.cleanup();this.print("\n");if(this._reject)this._reject(reason)}renderFrame(content){const width=this.stdout.columns||80;const rawLines=content.split("\n");const newLines=rawLines.map(line=>this.truncate(line,width));if(this.lastRenderLines.length===0){this.print(newLines.join("\n"));this.lastRenderLines=newLines;this.lastRenderHeight=newLines.length;return}let outputBuffer="";if(this.lastRenderHeight>1){outputBuffer+=`\x1b[${this.lastRenderHeight-1}A`}outputBuffer+="\r";for(let i=0;i<newLines.length;i++){const newLine=newLines[i];if(i>0){if(i<this.lastRenderLines.length){outputBuffer+="\x1b[B\r"}else{outputBuffer+="\n"}}if(i<this.lastRenderLines.length){const oldLine=this.lastRenderLines[i];if(newLine!==oldLine){outputBuffer+=_ansi.ANSI.ERASE_LINE+newLine}}else{outputBuffer+=newLine}}if(newLines.length<this.lastRenderLines.length){outputBuffer+="\n";outputBuffer+=_ansi.ANSI.ERASE_DOWN;outputBuffer+=`\x1b[A`}this.print(outputBuffer);this.lastRenderLines=newLines;this.lastRenderHeight=newLines.length}stripAnsi(str){return(0,_utils.stripAnsi)(str)}truncate(str,width){const visualWidth=(0,_utils.stringWidth)(str);if(visualWidth<=width){return str}let currentWidth=0;let cutIndex=0;let inAnsi=false;for(let i=0;i<str.length;i++){if(str[i]==="\x1b")inAnsi=true;if(!inAnsi){const code=str.charCodeAt(i);const charWidth=code>255?2:1;if(currentWidth+charWidth>width-3){break}currentWidth+=charWidth}else{if(str[i]==="m"||str[i]>="A"&&str[i]<="Z")inAnsi=false}cutIndex=i+1}return str.substring(0,cutIndex)+"..."+_ansi.ANSI.RESET}isUp(char){return char==="\x1b[A"||char==="\x1bOA"}isDown(char){return char==="\x1b[B"||char==="\x1bOB"}isRight(char){return char==="\x1b[C"||char==="\x1bOC"}isLeft(char){return char==="\x1b[D"||char==="\x1bOD"}constructor(options){_define_property(this,"options",void 0);_define_property(this,"value",void 0);_define_property(this,"stdin",void 0);_define_property(this,"stdout",void 0);_define_property(this,"_resolve",void 0);_define_property(this,"_reject",void 0);_define_property(this,"_inputParser",void 0);_define_property(this,"_onKeyHandler",void 0);_define_property(this,"_onDataHandler",void 0);_define_property(this,"lastRenderLines",[]);_define_property(this,"lastRenderHeight",0);_define_property(this,"capabilities",void 0);this.options=options;this.stdin=process.stdin;this.stdout=process.stdout;this._inputParser=new _input.InputParser;this.capabilities=(0,_utils.detectCapabilities)()}};_define_property(Prompt,"warnedComponents",new Set);