cliedit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# cliedit
+
+A lightweight, zero-dependency (other than `keypress`), raw-mode terminal editor component for Node.js.
+
+`cliedit` is designed to be imported into your own CLI application to provide a full-featured, TTY-based text editing experience. It's perfect for applications that need to ask the user for multi-line input, edit configuration files, or write commit messages.
+
+It includes line wrapping, visual navigation, undo/redo, text selection, and clipboard support.
+
+## Features
+
+- **Raw Mode TTY:** Takes over the terminal for a full "app-like" feel.
+- **Visual Line Wrapping:** Text wraps to fit the terminal width.
+- **Visual Navigation:** `Up`/`Down` arrows move by visual rows, not logical lines.
+- **Undo/Redo:** `Ctrl+Z` / `Ctrl+Y` for persistent history.
+- **Text Selection:** `Ctrl+Arrow` keys to select text.
+- **Clipboard Support:** `Ctrl+C` (Copy), `Ctrl+X` (Cut), `Ctrl+V` (Paste) for system clipboard (macOS/Windows).
+- **File I/O:** Loads from and saves to the filesystem.
+- **Search:** `Ctrl+W` to find text.
+
+## Installation
+```bash
+npm install cliedit
+```
+
+## Usage
+
+The package exports an `async` function `openEditor` that returns a `Promise`. The promise resolves when the user quits the editor.
+```javascript
+import { openEditor } from 'cliedit';
+import path from 'path';
+
+async function getCommitMessage() {
+  const tempFile = path.resolve(process.cwd(), 'COMMIT_MSG.txt');
+  console.log('Opening editor for commit message...');
+
+  try {
+    const result = await openEditor(tempFile);
+
+    // Give the terminal a moment to restore
+    await new Promise(res => setTimeout(res, 50));
+
+    if (result.saved) {
+      console.log('Message saved!');
+      console.log('---------------------');
+      console.log(result.content);
+      console.log('---------------------');
+    } else {
+      console.log('Editor quit without saving.');
+    }
+  } catch (err) {
+    console.error('Editor failed to start:', err);
+  }
+}
+
+getCommitMessage();
+```
+
+## Public API
+
+`openEditor(filepath: string)`
+
+Opens the editor for the specified file. If the file doesn't exist, it will be created upon saving.
+- **Returns:** `Promise<{ saved: boolean; content: string }>`
+    * `saved`: `true` if the user saved (Ctrl+S), `false` otherwise (Ctrl+Q).
+    * `content`: The final content of the file as a string.
+
+`CliEditor`
+
+The main editor class. You can import this directly if you need to extend or instantiate the editor with custom logic.
+```javascript
+import { CliEditor } from 'cliedit';
+```
+
+### Types
+
+Key types are also exported for convenience:
+```javascript
+import type {
+  DocumentState,
+  VisualRow,
+  EditorMode,
+  NormalizedRange,
+} from 'cliedit';
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/constants.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ANSI escape codes for terminal manipulation.
+ */
+export declare const ANSI: {
+    CLEAR_SCREEN: string;
+    CLEAR_LINE: string;
+    MOVE_CURSOR_TOP_LEFT: string;
+    HIDE_CURSOR: string;
+    SHOW_CURSOR: string;
+    INVERT_COLORS: string;
+    RESET_COLORS: string;
+    ENTER_ALTERNATE_SCREEN: string;
+    EXIT_ALTERNATE_SCREEN: string;
+};
+/**
+ * Key definitions for special keypresses (using Ctrl+ keys for reliable detection).
+ */
+export declare const KEYS: {
+    CTRL_C: string;
+    CTRL_Q: string;
+    CTRL_S: string;
+    CTRL_W: string;
+    CTRL_G: string;
+    CTRL_Z: string;
+    CTRL_Y: string;
+    CTRL_K: string;
+    CTRL_U: string;
+    CTRL_X: string;
+    CTRL_V: string;
+    CTRL_ARROW_UP: string;
+    CTRL_ARROW_DOWN: string;
+    CTRL_ARROW_RIGHT: string;
+    CTRL_ARROW_LEFT: string;
+    ENTER: string;
+    BACKSPACE: string;
+    ESCAPE: string;
+    ARROW_UP: string;
+    ARROW_DOWN: string;
+    ARROW_RIGHT: string;
+    ARROW_LEFT: string;
+    DELETE: string;
+    HOME: string;
+    END: string;
+    PAGE_UP: string;
+    PAGE_DOWN: string;
+    TAB: string;
+};

package/dist/constants.js

@@ -0,0 +1,52 @@
+// src/constants.ts
+/**
+ * ANSI escape codes for terminal manipulation.
+ */
+export const ANSI = {
+    CLEAR_SCREEN: '\x1b[2J', // Clear entire screen
+    CLEAR_LINE: '\x1b[K', // Clear from cursor to end of line
+    MOVE_CURSOR_TOP_LEFT: '\x1b[H', // Move cursor to top-left (1;1)
+    HIDE_CURSOR: '\x1b[?25l', // Hide cursor
+    SHOW_CURSOR: '\x1b[?25h', // Show cursor
+    INVERT_COLORS: '\x1b[7m', // Invert background/foreground colors
+    RESET_COLORS: '\x1b[0m', // Reset colors
+    ENTER_ALTERNATE_SCREEN: '\x1b[?1049h', // Enter alternate screen
+    EXIT_ALTERNATE_SCREEN: '\x1b[?1049l', // Exit alternate screen
+};
+/**
+ * Key definitions for special keypresses (using Ctrl+ keys for reliable detection).
+ */
+export const KEYS = {
+    // Control Sequences
+    CTRL_C: '\x03', // Copy/Quit (contextual)
+    CTRL_Q: '\x11', // Quit
+    CTRL_S: '\x13', // Save
+    CTRL_W: '\x17', // Find (Where is)
+    CTRL_G: '\x07', // Go to next
+    CTRL_Z: '\x1a', // Undo
+    CTRL_Y: '\x19', // Redo
+    CTRL_K: '\x0b', // Cut/Kill line
+    CTRL_U: '\x15', // Paste/Un-kill
+    CTRL_X: '\x18', // Cut Selection
+    CTRL_V: '\x16', // Paste Selection
+    // Selection Keys (Mapped to Ctrl+Arrow for reliable detection)
+    CTRL_ARROW_UP: 'C-up',
+    CTRL_ARROW_DOWN: 'C-down',
+    CTRL_ARROW_RIGHT: 'C-right',
+    CTRL_ARROW_LEFT: 'C-left',
+    // Standard Keys
+    ENTER: '\r', // Carriage Return
+    BACKSPACE: '\x7f', // DEL (usually Backspace)
+    ESCAPE: '\x1b',
+    // Escape sequences for navigation keys (used by keypress.name)
+    ARROW_UP: 'up',
+    ARROW_DOWN: 'down',
+    ARROW_RIGHT: 'right',
+    ARROW_LEFT: 'left',
+    DELETE: 'delete',
+    HOME: 'home',
+    END: 'end',
+    PAGE_UP: 'pageup',
+    PAGE_DOWN: 'pagedown',
+    TAB: '\t',
+};

package/dist/editor.clipboard.d.ts

@@ -0,0 +1,35 @@
+import { CliEditor } from './editor.js';
+/**
+ * Methods related to system clipboard interaction (Copy/Paste/Cut).
+ */
+declare function setClipboard(this: CliEditor, text: string): Promise<void>;
+declare function getClipboard(this: CliEditor): Promise<string>;
+/**
+ * Cuts the current line and copies it to the clipboard.
+ * Falls back to line-based behavior if no selection.
+ */
+declare function cutLine(this: CliEditor): Promise<void>;
+/**
+ * Pastes the clipboard content at the cursor position.
+ * Handles single-line and multi-line pastes.
+ */
+declare function pasteLine(this: CliEditor): Promise<void>;
+/**
+ * Cuts the current selection to the clipboard. Returns a promise.
+ * Renamed to avoid collision with command handler in editor.keys.ts
+ */
+declare function cutSelectionAsync(this: CliEditor): Promise<void>;
+/**
+ * Pastes clipboard content at the cursor position.
+ * Always deletes selection if one exists.
+ */
+declare function pasteSelection(this: CliEditor): Promise<void>;
+export declare const clipboardMethods: {
+    setClipboard: typeof setClipboard;
+    getClipboard: typeof getClipboard;
+    cutLine: typeof cutLine;
+    pasteLine: typeof pasteLine;
+    cutSelectionAsync: typeof cutSelectionAsync;
+    pasteSelection: typeof pasteSelection;
+};
+export {};

package/dist/editor.clipboard.js

@@ -0,0 +1,129 @@
+// src/editor.clipboard.ts
+import { platform } from 'os';
+import { exec } from 'child_process';
+/**
+ * Methods related to system clipboard interaction (Copy/Paste/Cut).
+ */
+// --- Helper Functions (Clipboard Access) ---
+function setClipboard(text) {
+    return new Promise((resolve, reject) => {
+        let command;
+        switch (platform()) {
+            case 'darwin':
+                command = 'pbcopy';
+                break;
+            case 'win32':
+                command = 'clip';
+                break;
+            default:
+                this.setStatusMessage('Clipboard only supported on macOS/Windows for now');
+                return resolve();
+        }
+        const process = exec(command, (error) => {
+            if (error) {
+                this.setStatusMessage(`Clipboard error: ${error.message}`);
+                return reject(error);
+            }
+            this.setStatusMessage('Text copied to clipboard', 1000);
+            resolve();
+        });
+        if (process.stdin) {
+            process.stdin.write(text);
+            process.stdin.end();
+        }
+    });
+}
+function getClipboard() {
+    return new Promise((resolve, reject) => {
+        let command;
+        switch (platform()) {
+            case 'darwin':
+                command = 'pbpaste';
+                break;
+            case 'win32':
+                command = 'powershell -command "Get-Clipboard"';
+                break;
+            default:
+                this.setStatusMessage('Clipboard only supported on macOS/Windows for now');
+                return resolve('');
+        }
+        exec(command, (error, stdout) => {
+            if (error) {
+                this.setStatusMessage(`Paste error: ${error.message}`);
+                return reject(error);
+            }
+            resolve(stdout);
+        });
+    });
+}
+// --- Clipboard Actions ---
+/**
+ * Cuts the current line and copies it to the clipboard.
+ * Falls back to line-based behavior if no selection.
+ */
+async function cutLine() {
+    if (this.lines.length > 1 || (this.lines.length === 1 && this.lines[0] !== '')) {
+        const lineToCut = this.lines[this.cursorY];
+        await this.setClipboard(lineToCut);
+        this.lines.splice(this.cursorY, 1);
+        if (this.cursorY >= this.lines.length) {
+            this.cursorY = Math.max(0, this.lines.length - 1);
+        }
+        if (this.lines.length === 0) {
+            this.lines = [''];
+        }
+        this.cursorX = 0;
+        this.setDirty();
+        this.setStatusMessage('Line cut to clipboard', 1000);
+    }
+}
+/**
+ * Pastes the clipboard content at the cursor position.
+ * Handles single-line and multi-line pastes.
+ */
+async function pasteLine() {
+    try {
+        const textToPaste = await this.getClipboard();
+        if (!textToPaste)
+            return;
+        const pasteLines = textToPaste.split(/\r?\n/);
+        if (this.selectionAnchor) {
+            this.deleteSelectedText();
+        }
+        this.insertContentAtCursor(pasteLines);
+    }
+    catch (error) {
+        this.setStatusMessage(`Paste failed: ${error.message}`);
+    }
+}
+/**
+ * Cuts the current selection to the clipboard. Returns a promise.
+ * Renamed to avoid collision with command handler in editor.keys.ts
+ */
+async function cutSelectionAsync() {
+    if (!this.selectionAnchor) {
+        await this.cutLine();
+    }
+    else {
+        const textToCut = this.getSelectedText();
+        await this.setClipboard(textToCut);
+        this.deleteSelectedText();
+        this.setDirty();
+        this.setStatusMessage('Selection cut!', 1000);
+    }
+}
+/**
+ * Pastes clipboard content at the cursor position.
+ * Always deletes selection if one exists.
+ */
+async function pasteSelection() {
+    await this.pasteLine();
+}
+export const clipboardMethods = {
+    setClipboard,
+    getClipboard,
+    cutLine,
+    pasteLine,
+    cutSelectionAsync, // Renamed
+    pasteSelection,
+};

package/dist/editor.d.ts

@@ -0,0 +1,78 @@
+import { HistoryManager } from './history.js';
+import { VisualRow, EditorMode } from './types.js';
+declare module 'keypress' {
+    interface KeypressEvent {
+        name?: string;
+        ctrl: boolean;
+        meta: boolean;
+        shift: boolean;
+        sequence: string;
+    }
+}
+import { editingMethods } from './editor.editing.js';
+import { clipboardMethods } from './editor.clipboard.js';
+import { navigationMethods } from './editor.navigation.js';
+import { renderingMethods } from './editor.rendering.js';
+import { searchMethods } from './editor.search.js';
+import { historyMethods } from './editor.history.js';
+import { ioMethods } from './editor.io.js';
+import { TKeyHandlingMethods } from './editor.keys.js';
+import { TSelectionMethods } from './editor.selection.js';
+type TEditingMethods = typeof editingMethods;
+type TClipboardMethods = typeof clipboardMethods;
+type TNavigationMethods = typeof navigationMethods;
+type TRenderingMethods = typeof renderingMethods;
+type TSearchMethods = typeof searchMethods;
+type THistoryMethods = typeof historyMethods;
+type TIOMethods = typeof ioMethods;
+export interface CliEditor extends TEditingMethods, TClipboardMethods, TNavigationMethods, TRenderingMethods, TSearchMethods, THistoryMethods, TIOMethods, TKeyHandlingMethods, TSelectionMethods {
+}
+/**
+ * Main editor class managing application state, TTY interaction, and rendering.
+ */
+export declare class CliEditor {
+    lines: string[];
+    filepath: string;
+    isDirty: boolean;
+    cursorX: number;
+    cursorY: number;
+    selectionAnchor: {
+        x: number;
+        y: number;
+    } | null;
+    rowOffset: number;
+    screenRows: number;
+    screenCols: number;
+    gutterWidth: number;
+    screenStartRow: number;
+    visualRows: VisualRow[];
+    mode: EditorMode;
+    statusMessage: string;
+    statusTimeout: NodeJS.Timeout | null;
+    isMessageCustom: boolean;
+    quitConfirm: boolean;
+    readonly DEFAULT_STATUS = "HELP: Ctrl+S = Save & Quit | Ctrl+Q = Quit | Ctrl+C = Copy All | Ctrl+Arrow = Select";
+    searchQuery: string;
+    searchResults: {
+        y: number;
+        x: number;
+    }[];
+    searchResultIndex: number;
+    history: HistoryManager;
+    isCleanedUp: boolean;
+    resolvePromise: ((value: {
+        saved: boolean;
+        content: string;
+    }) => void) | null;
+    rejectPromise: ((reason?: any) => void) | null;
+    isExiting: boolean;
+    constructor(initialContent: string, filepath: string);
+    run(): Promise<{
+        saved: boolean;
+        content: string;
+    }>;
+    private setupTerminal;
+    private handleResize;
+    private updateScreenSize;
+}
+export {};

package/dist/editor.editing.d.ts

@@ -0,0 +1,39 @@
+import { CliEditor } from './editor.js';
+/**
+ * Core methods for editing the document content (insert, delete, split/join lines).
+ */
+/**
+ * Inserts content (potentially multi-line) at the current cursor position.
+ * Note: This function ASSUMES the selection has already been deleted.
+ * @param contentLines An array of strings to insert.
+ */
+declare function insertContentAtCursor(this: CliEditor, contentLines: string[]): void;
+/**
+ * Inserts a single character at the cursor position.
+ */
+declare function insertCharacter(this: CliEditor, char: string): void;
+/**
+ * Inserts a soft tab (4 spaces).
+ */
+declare function insertSoftTab(this: CliEditor): void;
+/**
+ * Inserts a new line, splitting the current line at the cursor position.
+ */
+declare function insertNewLine(this: CliEditor): void;
+/**
+ * Deletes the character before the cursor, or joins the current line with the previous one.
+ */
+declare function deleteBackward(this: CliEditor): void;
+/**
+ * Deletes the character after the cursor, or joins the current line with the next one.
+ */
+declare function deleteForward(this: CliEditor): void;
+export declare const editingMethods: {
+    insertContentAtCursor: typeof insertContentAtCursor;
+    insertCharacter: typeof insertCharacter;
+    insertSoftTab: typeof insertSoftTab;
+    insertNewLine: typeof insertNewLine;
+    deleteBackward: typeof deleteBackward;
+    deleteForward: typeof deleteForward;
+};
+export {};

package/dist/editor.editing.js

@@ -0,0 +1,115 @@
+// src/editor.editing.ts
+/**
+ * Core methods for editing the document content (insert, delete, split/join lines).
+ */
+/**
+ * Inserts content (potentially multi-line) at the current cursor position.
+ * Note: This function ASSUMES the selection has already been deleted.
+ * @param contentLines An array of strings to insert.
+ */
+function insertContentAtCursor(contentLines) {
+    const pasteLength = contentLines.length;
+    if (pasteLength === 1) {
+        const line = this.lines[this.cursorY] || '';
+        this.lines[this.cursorY] = line.slice(0, this.cursorX) + contentLines[0] + line.slice(this.cursorX);
+        this.cursorX += contentLines[0].length;
+    }
+    else {
+        // Multi-line paste logic
+        const line = this.lines[this.cursorY] || '';
+        const remainder = line.slice(this.cursorX);
+        // 1. Update current line with the first part of the paste
+        this.lines[this.cursorY] = line.slice(0, this.cursorX) + contentLines[0];
+        const linesToInsert = contentLines.slice(1, -1);
+        const lastPasteLine = contentLines[contentLines.length - 1];
+        // 2. Insert middle lines
+        if (linesToInsert.length > 0) {
+            this.lines.splice(this.cursorY + 1, 0, ...linesToInsert);
+        }
+        // 3. Insert last line and append remainder
+        this.lines.splice(this.cursorY + 1 + linesToInsert.length, 0, lastPasteLine + remainder);
+        // 4. Update cursor position
+        this.cursorY += pasteLength - 1;
+        this.cursorX = lastPasteLine.length;
+    }
+    this.setDirty();
+    this.recalculateVisualRows();
+}
+/**
+ * Inserts a single character at the cursor position.
+ */
+function insertCharacter(char) {
+    const line = this.lines[this.cursorY] || '';
+    this.lines[this.cursorY] = line.slice(0, this.cursorX) + char + line.slice(this.cursorX);
+    this.cursorX += char.length;
+}
+/**
+ * Inserts a soft tab (4 spaces).
+ */
+function insertSoftTab() {
+    this.insertCharacter('    ');
+}
+/**
+ * Inserts a new line, splitting the current line at the cursor position.
+ */
+function insertNewLine() {
+    const line = this.lines[this.cursorY] || '';
+    const remainder = line.slice(this.cursorX);
+    this.lines[this.cursorY] = line.slice(0, this.cursorX);
+    this.lines.splice(this.cursorY + 1, 0, remainder);
+    this.cursorY++;
+    this.cursorX = 0;
+    this.setDirty();
+}
+/**
+ * Deletes the character before the cursor, or joins the current line with the previous one.
+ */
+function deleteBackward() {
+    if (this.cursorX > 0) {
+        const line = this.lines[this.cursorY] || '';
+        this.lines[this.cursorY] = line.slice(0, this.cursorX - 1) + line.slice(this.cursorX);
+        this.cursorX--;
+    }
+    else if (this.cursorY > 0) {
+        const currentLine = this.lines[this.cursorY];
+        const previousLine = this.lines[this.cursorY - 1];
+        this.cursorX = previousLine.length;
+        this.lines[this.cursorY - 1] = previousLine + currentLine;
+        this.lines.splice(this.cursorY, 1);
+        this.cursorY--;
+    }
+    if (this.lines.length === 0) {
+        this.lines = [''];
+        this.cursorY = 0;
+        this.cursorX = 0;
+    }
+    this.setDirty();
+}
+/**
+ * Deletes the character after the cursor, or joins the current line with the next one.
+ */
+function deleteForward() {
+    const line = this.lines[this.cursorY] || '';
+    if (this.cursorX < line.length) {
+        this.lines[this.cursorY] = line.slice(0, this.cursorX) + line.slice(this.cursorX + 1);
+    }
+    else if (this.cursorY < this.lines.length - 1) {
+        const nextLine = this.lines[this.cursorY + 1];
+        this.lines[this.cursorY] = line + nextLine;
+        this.lines.splice(this.cursorY + 1, 1);
+    }
+    if (this.lines.length === 0) {
+        this.lines = [''];
+        this.cursorY = 0;
+        this.cursorX = 0;
+    }
+    this.setDirty();
+}
+export const editingMethods = {
+    insertContentAtCursor,
+    insertCharacter,
+    insertSoftTab,
+    insertNewLine,
+    deleteBackward,
+    deleteForward,
+};

package/dist/editor.history.d.ts

@@ -0,0 +1,33 @@
+import { CliEditor } from './editor.js';
+import { DocumentState } from './types.js';
+/**
+ * Methods related to Undo/Redo operations.
+ */
+/**
+ * Gets the current document state (content and cursor position).
+ */
+declare function getCurrentState(this: CliEditor): DocumentState;
+/**
+ * Saves the current state to the history manager.
+ */
+declare function saveState(this: CliEditor, initial?: boolean): void;
+/**
+ * Loads a document state from the history manager.
+ */
+declare function loadState(this: CliEditor, state: DocumentState): void;
+/**
+ * Performs an undo operation.
+ */
+declare function undo(this: CliEditor): void;
+/**
+ * Performs a redo operation.
+ */
+declare function redo(this: CliEditor): void;
+export declare const historyMethods: {
+    getCurrentState: typeof getCurrentState;
+    saveState: typeof saveState;
+    loadState: typeof loadState;
+    undo: typeof undo;
+    redo: typeof redo;
+};
+export {};