@agentuity/cli 2.0.12 → 2.0.13

package/src/tui/prompt.ts

@@ -14,6 +14,12 @@ export interface TextOptions {
 	message: string;
 	initial?: string;
 	hint?: string;
+	/**
+	 * Pre-generated suggestion shown dim in the hint line.
+	 * Submitting empty input accepts the placeholder.
+	 * Unlike `initial`, this is rendered visibly so the user knows what they'll get.
+	 */
+	placeholder?: string;
 	validate?: (value: string) => boolean | string | Promise<boolean | string>;
 }
 
@@ -92,27 +98,39 @@ export class PromptFlow {
 
 	/**
 	 * Text input prompt
+	 *
+	 * Two render paths:
+	 *  - With `placeholder`: custom raw-keypress renderer that paints the placeholder
+	 *    inline as dim ghost text at the cursor (autofill style). Vanishes on the first
+	 *    keystroke; Enter on an empty buffer accepts the placeholder.
+	 *  - Without `placeholder`: original readline-based renderer (untouched).
 	 */
 	async text(options: TextOptions): Promise<string> {
-		const { message, validate } = options;
-		const initial = options.initial ?? '';
-		const hasDefault = options.initial !== undefined;
+		const { message, validate, placeholder } = options;
+		// `placeholder` acts as a visible default: empty submit resolves to it.
+		// `initial` (legacy, invisible) still works but `placeholder` takes precedence.
+		const fallback = placeholder ?? options.initial ?? '';
+		const hasDefault = placeholder !== undefined || options.initial !== undefined;
 
 		if (!this.isInteractive()) {
 			if (hasDefault) {
-				const validationResult = validate ? await validate(initial) : true;
+				const validationResult = validate ? await validate(fallback) : true;
 				if (validationResult === true) {
-					return initial;
+					return fallback;
 				}
 				// Validation failed - include the error message if it's a string
 				const errorDetail = typeof validationResult === 'string' ? `: ${validationResult}` : '';
 				throw this.nonInteractiveError(
-					`Cannot prompt for "${message}" in non-interactive mode. Validation failed for default value "${initial}"${errorDetail}.`
+					`Cannot prompt for "${message}" in non-interactive mode. Validation failed for default value "${fallback}"${errorDetail}.`
 				);
 			}
 			throw this.nonInteractiveError(`Cannot prompt for "${message}" in non-interactive mode.`);
 		}
 
+		if (placeholder) {
+			return this.textWithGhost(options, placeholder);
+		}
+
 		return new Promise((resolve, reject) => {
 			const rl = readline.createInterface({
 				input: process.stdin,
@@ -139,8 +157,8 @@ export class PromptFlow {
 
 			rl.on('line', async (input) => {
 				const trimmed = input.trim();
-				// After a validation error, require explicit input - don't fall back to initial
-				const value = trimmed.length > 0 ? trimmed : hadValidationError ? '' : initial;
+				// After a validation error, require explicit input - don't fall back to default.
+				const value = trimmed.length > 0 ? trimmed : hadValidationError ? '' : fallback;
 
 				// Validate
 				if (validate) {
@@ -229,6 +247,194 @@ export class PromptFlow {
 		});
 	}
 
+	/**
+	 * Text input with inline ghost-text placeholder (autofill style).
+	 *
+	 * Layout:
+	 *   ◆  <message>
+	 *   │  <hint>           (optional)
+	 *   │  <typed>│<ghost>   ghost is dim, vanishes on first keystroke
+	 *
+	 * Behavior:
+	 *   - Typing any char hides the ghost permanently for this prompt instance.
+	 *   - Backspacing back to empty does NOT bring the ghost back.
+	 *   - Enter on empty buffer → resolves to placeholder.
+	 *   - Enter with typed text → resolves to typed text.
+	 *   - Validation error: shows inline error, ghost stays gone, user must type.
+	 *   - Ctrl+C: cancels.
+	 */
+	private async textWithGhost(options: TextOptions, placeholder: string): Promise<string> {
+		const { message, validate, hint } = options;
+
+		return new Promise((resolve, reject) => {
+			let buffer = '';
+			// Tracks whether the ghost should still be visible. Once any printable key is
+			// pressed it goes false and stays false for the rest of this prompt.
+			let ghostVisible = true;
+			let hasError = false;
+			let errorMsg = '';
+
+			const inputPrefix = `${colors.secondary(symbols.bar)}  `;
+			// Visible-character length of the input-line prefix ("│  " = 3 cells).
+			const PREFIX_VISIBLE = 3;
+
+			/**
+			 * Repaint everything from the message line down. Cursor must be on the
+			 * message line (column 0) when this is called for the first time, or we
+			 * just moved up to it after a clear.
+			 */
+			const paint = () => {
+				const symbol = hasError ? colors.error(symbols.error) : colors.active(symbols.active);
+				process.stdout.write(`${symbol}  ${message}\n`);
+
+				if (hasError) {
+					process.stdout.write(
+						`${colors.secondary(symbols.bar)}  ${colors.error(errorMsg)}\n`
+					);
+				} else if (hint) {
+					process.stdout.write(`${colors.secondary(symbols.bar)}  ${colors.muted(hint)}\n`);
+				}
+
+				// Input line.
+				process.stdout.write(inputPrefix);
+				process.stdout.write(buffer);
+
+				if (ghostVisible && buffer.length === 0) {
+					// Paint the ghost, then move the cursor back to the start of it so the
+					// caret sits where the user would start typing.
+					process.stdout.write(colors.muted(placeholder));
+					readline.moveCursor(process.stdout, -placeholder.length, 0);
+				}
+			};
+
+			/**
+			 * Number of terminal lines currently occupied by our render, so we know
+			 * how many to clear on the next repaint.
+			 * Always: message (1) + hint-or-error (0/1) + input (1).
+			 */
+			const renderedLines = (): number => {
+				let n = 1; // message
+				if (hasError || hint) n += 1;
+				n += 1; // input
+				return n;
+			};
+
+			const repaint = () => {
+				// Move cursor to column 0, then up to the start of our render block, then clear.
+				readline.cursorTo(process.stdout, 0);
+				readline.moveCursor(process.stdout, 0, -(renderedLines() - 1));
+				readline.clearScreenDown(process.stdout);
+				paint();
+			};
+
+			// Resume stdin if it was paused by a prior prompt.
+			if (process.stdin.isTTY && process.stdin.isPaused()) {
+				process.stdin.resume();
+			}
+
+			readline.emitKeypressEvents(process.stdin);
+			if (process.stdin.isTTY) {
+				process.stdin.setRawMode(true);
+			}
+
+			// Initial paint.
+			paint();
+
+			const cleanup = () => {
+				process.stdin.removeListener('keypress', onKeypress);
+				if (process.stdin.isTTY) {
+					process.stdin.setRawMode(false);
+					process.stdin.pause();
+				}
+			};
+
+			const finalize = (value: string) => {
+				// Repaint as completed: replace whole render block with the completed lines.
+				readline.cursorTo(process.stdout, 0);
+				readline.moveCursor(process.stdout, 0, -(renderedLines() - 1));
+				readline.clearScreenDown(process.stdout);
+
+				if (value === '') {
+					process.stdout.write(
+						`${colors.completed(symbols.completed)}  ${message}\n${colors.secondary(symbols.bar)}\n`
+					);
+				} else {
+					process.stdout.write(
+						`${colors.completed(symbols.completed)}  ${message}\n${colors.secondary(symbols.bar)}  ${colors.muted(value)}\n${colors.secondary(symbols.bar)}\n`
+					);
+				}
+
+				this.states.push({ type: 'completed', message, value });
+				cleanup();
+				resolve(value);
+			};
+
+			const onKeypress = async (str: string, key: KeypressEvent) => {
+				if (key.ctrl && key.name === 'c') {
+					cleanup();
+					console.log('\n');
+					this.cancel('Operation cancelled');
+					reject(new Error('User cancelled'));
+					return;
+				}
+
+				if (key.name === 'return') {
+					const trimmed = buffer.trim();
+					// Empty submit accepts the placeholder, but only if no error has occurred
+					// (after an error the user must type explicitly — same rule the readline
+					// path uses).
+					const value = trimmed.length > 0 ? trimmed : hasError ? '' : placeholder;
+
+					if (validate) {
+						try {
+							const result = await validate(value);
+							if (result !== true) {
+								errorMsg = typeof result === 'string' ? result : 'Invalid input';
+								hasError = true;
+								ghostVisible = false;
+								repaint();
+								return;
+							}
+						} catch (err) {
+							errorMsg = err instanceof Error ? err.message : 'Validation failed';
+							hasError = true;
+							ghostVisible = false;
+							repaint();
+							return;
+						}
+					}
+
+					finalize(value);
+					return;
+				}
+
+				if (key.name === 'backspace') {
+					if (buffer.length > 0) {
+						buffer = buffer.slice(0, -1);
+						repaint();
+					}
+					return;
+				}
+
+				// Printable single character (ignore arrow keys, function keys, etc.).
+				if (str && str.length === 1 && !key.ctrl && str >= ' ' && str !== '\x7f') {
+					buffer += str;
+					ghostVisible = false;
+					repaint();
+					return;
+				}
+
+				// Everything else (arrows, tab, etc.) is ignored.
+			};
+
+			// Mark the prefix length as used so the unused-var rule doesn't trip when we
+			// extend this in future. (Keeping it documented for cursor-math sanity.)
+			void PREFIX_VISIBLE;
+
+			process.stdin.on('keypress', onKeypress);
+		});
+	}
+
 	/**
 	 * Confirm (yes/no) prompt
 	 */