suaveplan/openspec/archive/2026-04-20-enterprise-readline/specs/readline/spec.md

Spec: @suaveplan/readline

Purpose

Terminal I/O primitive: async line reader, interactive readline interface, and byte scanner engine. Depends only on @suaveplan/error, @suaveplan/types, @opentelemetry/api, zod.

ADDED Requirements

readLines

• readLines(stream: NodeJS.ReadableStream, signal?: AbortSignal): AsyncGenerator<string>
• Yields each newline-delimited UTF-8 line
• Terminates cleanly on AbortSignal or stream close

createInterface

• createInterface(opts: { input, output?, signal? }): ReadlineInterface
• Returns { question(prompt): Promise<string>, close(): void }
• OTel span per question() call
• AbortSignal aborts pending question

ByteScanner

• Internal engine for buffered byte-level scanning