@teammates/cli 0.1.0 → 0.2.0

package/dist/console/interactive-readline.js

@@ -0,0 +1,132 @@
+/**
+ * InteractiveReadline — a batteries-included readline wrapper for CLI REPLs.
+ *
+ * Composes MutableOutput, PasteHandler, Dropdown, and Wordwheel into a
+ * single cohesive readline experience with:
+ *
+ * - Paste detection (multi-line collapse, long single-line truncation)
+ * - Autocomplete dropdown with keyboard navigation
+ * - Mutable output for suppressing echo
+ * - Cross-platform (Windows + macOS)
+ *
+ * Usage:
+ *   const irl = new InteractiveReadline({
+ *     prompt: "my-app> ",
+ *     getItems: (line, cursor) => [...],
+ *     onLine: async (input) => { ... },
+ *   });
+ *   await irl.start();
+ */
+import { createInterface, } from "node:readline";
+import { esc } from "@teammates/consolonia";
+import { Dropdown } from "./dropdown.js";
+import { MutableOutput } from "./mutable-output.js";
+import { PasteHandler } from "./paste-handler.js";
+import { Wordwheel } from "./wordwheel.js";
+export class InteractiveReadline {
+    rl;
+    output;
+    dropdown;
+    wordwheel;
+    pasteHandler;
+    dispatching = false;
+    prompt;
+    onLine;
+    constructor(options) {
+        this.prompt = options.prompt;
+        this.onLine = options.onLine;
+        // 1. Create mutable output
+        this.output = new MutableOutput();
+        // 2. Create readline
+        this.rl = createInterface({
+            input: process.stdin,
+            output: this.output,
+            prompt: options.prompt,
+            terminal: true,
+        });
+        // 3. Create dropdown (hooks _refreshLine)
+        this.dropdown = new Dropdown(this.rl);
+        // 4. Create wordwheel
+        this.wordwheel = new Wordwheel({
+            rl: this.rl,
+            dropdown: this.dropdown,
+            getItems: options.getItems ?? (() => []),
+            formatHighlighted: options.formatHighlighted,
+            formatNormal: options.formatNormal,
+        });
+        // 5. Create paste handler
+        this.pasteHandler = new PasteHandler({
+            rl: this.rl,
+            output: this.output,
+            debounceMs: options.pasteDebounceMs,
+            longPasteThreshold: options.longPasteThreshold,
+            formatPrompt: () => this.prompt,
+            onLine: async (result) => {
+                if (!result.input || this.dispatching) {
+                    this.rl.prompt();
+                    return;
+                }
+                this.dispatching = true;
+                try {
+                    await this.onLine(result.input, result.attachments);
+                }
+                catch (err) {
+                    console.log(`Error: ${err.message}`);
+                }
+                finally {
+                    this.dispatching = false;
+                }
+                this.rl.prompt();
+            },
+        });
+        // 6. Install keyboard interceptor
+        this.installKeyHandler();
+        // 7. Handle close
+        this.rl.on("close", () => {
+            options.onClose?.();
+        });
+    }
+    /** Start the REPL — shows the prompt. */
+    start() {
+        this.rl.prompt();
+    }
+    /** Clear the terminal and re-show the prompt. */
+    clearScreen() {
+        process.stdout.write(esc.clearScreen + esc.moveTo(0, 0));
+    }
+    /** Reset all state (paste buffers, wordwheel, etc.). */
+    reset() {
+        this.pasteHandler.reset();
+        this.wordwheel.clear();
+    }
+    /** Access the current line text. */
+    get line() {
+        return this.rl.line ?? "";
+    }
+    /** Set the current line text and cursor. */
+    setLine(text) {
+        this.rl.line = text;
+        this.rl.cursor = text.length;
+        this.rl._refreshLine();
+    }
+    installKeyHandler() {
+        const origTtyWrite = this.rl._ttyWrite.bind(this.rl);
+        this.rl._ttyWrite = (s, key) => {
+            // Track keystroke timing for paste detection
+            this.pasteHandler.onKeystroke();
+            // Let wordwheel handle navigation keys
+            if (this.wordwheel.handleKey(key))
+                return;
+            // Enter: accept wordwheel selection first, then process normally
+            if (key && key.name === "return") {
+                this.wordwheel.handleEnter();
+                origTtyWrite(s, key);
+                return;
+            }
+            // All other keys: pass to readline, then update wordwheel
+            this.wordwheel.clear();
+            origTtyWrite(s, key);
+            this.wordwheel.update();
+        };
+    }
+}

package/dist/console/markdown-table.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Markdown table → box-drawing renderer.
+ *
+ * Parses markdown pipe tables from text and replaces them with
+ * Unicode box-drawing equivalents:
+ *
+ *   ┌──────┬───────┐
+ *   │ Name │ Role  │
+ *   ├──────┼───────┤
+ *   │ alice│ dev   │
+ *   └──────┴───────┘
+ */
+/**
+ * Find and replace all markdown tables in a block of text with
+ * box-drawing rendered versions.
+ */
+export declare function renderMarkdownTables(text: string, maxWidth?: number): string;

package/dist/console/markdown-table.js

@@ -0,0 +1,270 @@
+/**
+ * Markdown table → box-drawing renderer.
+ *
+ * Parses markdown pipe tables from text and replaces them with
+ * Unicode box-drawing equivalents:
+ *
+ *   ┌──────┬───────┐
+ *   │ Name │ Role  │
+ *   ├──────┼───────┤
+ *   │ alice│ dev   │
+ *   └──────┴───────┘
+ */
+import chalk from "chalk";
+// ── Box-drawing characters ──────────────────────────────────────
+const BOX = {
+    topLeft: "┌",
+    topRight: "┐",
+    bottomLeft: "└",
+    bottomRight: "┘",
+    horizontal: "─",
+    vertical: "│",
+    teeDown: "┬",
+    teeUp: "┴",
+    teeRight: "├",
+    teeLeft: "┤",
+    cross: "┼",
+};
+function parseAlignment(sep) {
+    const trimmed = sep.trim();
+    const left = trimmed.startsWith(":");
+    const right = trimmed.endsWith(":");
+    if (left && right)
+        return "center";
+    if (right)
+        return "right";
+    return "left";
+}
+function padCell(text, width, align) {
+    const len = text.length;
+    const diff = width - len;
+    if (diff <= 0)
+        return text;
+    switch (align) {
+        case "right":
+            return " ".repeat(diff) + text;
+        case "center": {
+            const left = Math.floor(diff / 2);
+            return " ".repeat(left) + text + " ".repeat(diff - left);
+        }
+        default:
+            return text + " ".repeat(diff);
+    }
+}
+// ── Parsing ─────────────────────────────────────────────────────
+/** Parse a pipe-delimited row into trimmed cell strings. */
+function parseRow(line) {
+    // Strip leading/trailing pipe and split
+    let s = line.trim();
+    if (s.startsWith("|"))
+        s = s.slice(1);
+    if (s.endsWith("|"))
+        s = s.slice(0, -1);
+    return s.split("|").map((c) => c.trim());
+}
+/** Check if a line is a separator row (e.g. |---|---:|:---:|). */
+function isSeparatorRow(line) {
+    return /^\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/.test(line.trim());
+}
+/** Check if a line looks like a table row (has pipes). */
+function isTableRow(line) {
+    const trimmed = line.trim();
+    return trimmed.includes("|") && !trimmed.startsWith("```");
+}
+function parseTable(lines) {
+    if (lines.length < 2)
+        return null;
+    const headerLine = lines[0];
+    const sepLine = lines[1];
+    if (!isTableRow(headerLine) || !isSeparatorRow(sepLine))
+        return null;
+    const headers = parseRow(headerLine);
+    const seps = parseRow(sepLine);
+    const alignments = seps.map(parseAlignment);
+    // Pad alignments to match header count
+    while (alignments.length < headers.length)
+        alignments.push("left");
+    const rows = [];
+    for (let i = 2; i < lines.length; i++) {
+        if (!isTableRow(lines[i]))
+            break;
+        if (isSeparatorRow(lines[i]))
+            continue;
+        const cells = parseRow(lines[i]);
+        // Pad to header count
+        while (cells.length < headers.length)
+            cells.push("");
+        rows.push(cells.slice(0, headers.length));
+    }
+    return { headers, alignments, rows };
+}
+/** Wrap text to fit within a given width, breaking at word boundaries. */
+function wrapText(text, width) {
+    if (width <= 0)
+        return [text];
+    if (text.length <= width)
+        return [text];
+    const words = text.split(/\s+/);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current.length === 0) {
+            // Force-break words longer than width
+            if (word.length > width) {
+                for (let i = 0; i < word.length; i += width) {
+                    lines.push(word.slice(i, i + width));
+                }
+                current = "";
+                // Last chunk becomes current line if it didn't fill the width
+                if (lines.length > 0 && lines[lines.length - 1].length < width) {
+                    current = lines.pop();
+                }
+            }
+            else {
+                current = word;
+            }
+        }
+        else if (current.length + 1 + word.length <= width) {
+            current += ` ${word}`;
+        }
+        else {
+            lines.push(current);
+            // Force-break words longer than width
+            if (word.length > width) {
+                for (let i = 0; i < word.length; i += width) {
+                    lines.push(word.slice(i, i + width));
+                }
+                current = "";
+                if (lines.length > 0 && lines[lines.length - 1].length < width) {
+                    current = lines.pop();
+                }
+            }
+            else {
+                current = word;
+            }
+        }
+    }
+    if (current.length > 0)
+        lines.push(current);
+    return lines.length > 0 ? lines : [""];
+}
+function renderTable(table, maxWidth) {
+    const { headers, alignments, rows } = table;
+    const colCount = headers.length;
+    const termWidth = maxWidth ?? (process.stdout.columns || 80);
+    // Calculate natural column widths (max of header + all rows, + 2 for padding)
+    const naturalWidths = [];
+    for (let c = 0; c < colCount; c++) {
+        let max = headers[c].length;
+        for (const row of rows) {
+            if (row[c] && row[c].length > max)
+                max = row[c].length;
+        }
+        naturalWidths.push(max + 2); // 1 space padding each side
+    }
+    // Total width = sum of column widths + (colCount + 1) border characters
+    const borderChars = colCount + 1;
+    const totalNatural = naturalWidths.reduce((a, b) => a + b, 0) + borderChars;
+    let widths;
+    if (totalNatural <= termWidth) {
+        widths = naturalWidths;
+    }
+    else {
+        // Shrink columns proportionally to fit terminal width
+        const available = termWidth - borderChars;
+        const minColWidth = 4; // minimum: 2 padding + 2 chars
+        // First pass: give each column at least minColWidth, then distribute remaining proportionally
+        const totalContent = naturalWidths.reduce((a, b) => a + b, 0);
+        widths = naturalWidths.map((w) => {
+            const share = Math.floor((w / totalContent) * available);
+            return Math.max(share, minColWidth);
+        });
+        // Adjust rounding: distribute any leftover space to wider columns
+        let used = widths.reduce((a, b) => a + b, 0);
+        let idx = 0;
+        while (used < available && idx < colCount) {
+            widths[idx]++;
+            used++;
+            idx++;
+        }
+        // If we overshot, trim from the widest columns
+        while (used > available) {
+            let maxIdx = 0;
+            for (let c = 1; c < colCount; c++) {
+                if (widths[c] > widths[maxIdx])
+                    maxIdx = c;
+            }
+            if (widths[maxIdx] <= minColWidth)
+                break;
+            widths[maxIdx]--;
+            used--;
+        }
+    }
+    const hLine = (left, mid, right) => left + widths.map((w) => BOX.horizontal.repeat(w)).join(mid) + right;
+    /** Render a row that may have multi-line wrapped cells. */
+    const renderRow = (cells, bold) => {
+        // Wrap each cell
+        const wrapped = cells.map((cell, i) => wrapText(cell, widths[i] - 2));
+        const maxLines = Math.max(...wrapped.map((w) => w.length));
+        // Pad each cell's wrapped lines to have the same count
+        const lines = [];
+        for (let line = 0; line < maxLines; line++) {
+            const parts = cells.map((_, i) => {
+                const text = wrapped[i][line] || "";
+                const padded = padCell(text, widths[i] - 2, alignments[i]);
+                return bold ? ` ${chalk.bold(padded)} ` : ` ${padded} `;
+            });
+            lines.push(chalk.gray(BOX.vertical) +
+                parts.join(chalk.gray(BOX.vertical)) +
+                chalk.gray(BOX.vertical));
+        }
+        return lines;
+    };
+    const out = [];
+    // Top border
+    out.push(chalk.gray(hLine(BOX.topLeft, BOX.teeDown, BOX.topRight)));
+    // Header row (with wrapping)
+    out.push(...renderRow(headers, true));
+    // Header separator
+    out.push(chalk.gray(hLine(BOX.teeRight, BOX.cross, BOX.teeLeft)));
+    // Data rows (with wrapping)
+    for (const row of rows) {
+        out.push(...renderRow(row, false));
+    }
+    // Bottom border
+    out.push(chalk.gray(hLine(BOX.bottomLeft, BOX.teeUp, BOX.bottomRight)));
+    return out.join("\n");
+}
+// ── Public API ──────────────────────────────────────────────────
+/**
+ * Find and replace all markdown tables in a block of text with
+ * box-drawing rendered versions.
+ */
+export function renderMarkdownTables(text, maxWidth) {
+    const lines = text.split("\n");
+    const result = [];
+    let i = 0;
+    while (i < lines.length) {
+        // Look for a table start: a pipe row followed by a separator row
+        if (i + 1 < lines.length &&
+            isTableRow(lines[i]) &&
+            isSeparatorRow(lines[i + 1])) {
+            // Collect all contiguous table lines
+            const tableLines = [lines[i], lines[i + 1]];
+            let j = i + 2;
+            while (j < lines.length && isTableRow(lines[j])) {
+                tableLines.push(lines[j]);
+                j++;
+            }
+            const table = parseTable(tableLines);
+            if (table) {
+                result.push(renderTable(table, maxWidth));
+                i = j;
+                continue;
+            }
+        }
+        result.push(lines[i]);
+        i++;
+    }
+    return result.join("\n");
+}

package/dist/console/markdown-table.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/console/markdown-table.test.js

@@ -0,0 +1,130 @@
+import chalk from "chalk";
+import { describe, expect, it } from "vitest";
+import { renderMarkdownTables } from "./markdown-table.js";
+// Force chalk color output off so we can compare raw box-drawing chars
+chalk.level = 0;
+describe("renderMarkdownTables", () => {
+    it("renders a simple 2-column table", () => {
+        const input = [
+            "| Name  | Role |",
+            "| ----- | ---- |",
+            "| Alice | Dev  |",
+            "| Bob   | PM   |",
+        ].join("\n");
+        const result = renderMarkdownTables(input);
+        // Should contain box-drawing characters
+        expect(result).toContain("┌");
+        expect(result).toContain("┐");
+        expect(result).toContain("└");
+        expect(result).toContain("┘");
+        expect(result).toContain("│");
+        expect(result).toContain("─");
+        expect(result).toContain("├");
+        expect(result).toContain("┤");
+        expect(result).toContain("┼");
+        // Should contain the cell values
+        expect(result).toContain("Name");
+        expect(result).toContain("Role");
+        expect(result).toContain("Alice");
+        expect(result).toContain("Bob");
+        expect(result).toContain("Dev");
+        expect(result).toContain("PM");
+    });
+    it("renders a table with alignment markers", () => {
+        const input = [
+            "| Left | Center | Right |",
+            "|:-----|:------:|------:|",
+            "| a    |   b    |     c |",
+        ].join("\n");
+        const result = renderMarkdownTables(input);
+        // Should still produce a box-drawn table
+        expect(result).toContain("┌");
+        expect(result).toContain("Left");
+        expect(result).toContain("Center");
+        expect(result).toContain("Right");
+        expect(result).toContain("a");
+        expect(result).toContain("b");
+        expect(result).toContain("c");
+    });
+    it("renders a table with no alignment markers (default left)", () => {
+        const input = [
+            "| Col1 | Col2 |",
+            "| ---- | ---- |",
+            "| x    | y    |",
+        ].join("\n");
+        const result = renderMarkdownTables(input);
+        expect(result).toContain("┌");
+        expect(result).toContain("Col1");
+        expect(result).toContain("x");
+    });
+    it("passes through text with no tables unchanged", () => {
+        const input = "Hello world\nThis is plain text\nNo tables here";
+        const result = renderMarkdownTables(input);
+        expect(result).toBe(input);
+    });
+    it("handles mixed text and tables", () => {
+        const input = [
+            "Some intro text",
+            "",
+            "| A | B |",
+            "|---|---|",
+            "| 1 | 2 |",
+            "",
+            "Some outro text",
+        ].join("\n");
+        const result = renderMarkdownTables(input);
+        // Non-table text should be preserved
+        expect(result).toContain("Some intro text");
+        expect(result).toContain("Some outro text");
+        // Table should be rendered with box drawing
+        expect(result).toContain("┌");
+        expect(result).toContain("A");
+        expect(result).toContain("1");
+    });
+    it("handles empty table cells", () => {
+        const input = ["| H1 | H2 |", "|----|-----|", "|    | val |"].join("\n");
+        const result = renderMarkdownTables(input);
+        expect(result).toContain("┌");
+        expect(result).toContain("H1");
+        expect(result).toContain("val");
+    });
+    it("wraps text in columns when table exceeds maxWidth", () => {
+        const input = [
+            "| File | What changed |",
+            "|------|-------------|",
+            "| ci.yml | Added concurrency controls and security audit step and coverage reporting |",
+            "| release.yml | Added validation job with lint typecheck build test |",
+        ].join("\n");
+        // Force narrow width
+        const result = renderMarkdownTables(input, 50);
+        // Should contain data (some cells may be split across lines)
+        expect(result).toContain("What changed");
+        expect(result).toContain("concurrency");
+        // The text should be wrapped, so the table should have more visual lines than rows
+        const lines = result.split("\n");
+        // 2 data rows + 1 header + 3 borders = 6 minimum; wrapping adds more
+        expect(lines.length).toBeGreaterThan(6);
+        // No line should exceed maxWidth
+        for (const line of lines) {
+            expect(line.length).toBeLessThanOrEqual(50);
+        }
+    });
+    it("does not wrap when table fits within maxWidth", () => {
+        const input = ["| A | B |", "|---|---|", "| 1 | 2 |"].join("\n");
+        const result = renderMarkdownTables(input, 120);
+        const lines = result.split("\n");
+        // Should be exactly 5 lines: top border, header, separator, 1 data row, bottom border
+        expect(lines.length).toBe(5);
+    });
+    it("handles a single column table", () => {
+        const input = ["| Only |", "| ---- |", "| data |"].join("\n");
+        const result = renderMarkdownTables(input);
+        expect(result).toContain("┌");
+        expect(result).toContain("Only");
+        expect(result).toContain("data");
+        // Single column should not have cross or tee-down connectors
+        expect(result).not.toContain("┬");
+        expect(result).not.toContain("┴");
+        expect(result).not.toContain("┼");
+    });
+});

package/dist/console/mutable-output.d.ts

@@ -0,0 +1,21 @@
+/**
+ * MutableOutput — a Writable stream wrapper around stdout that can be muted.
+ *
+ * Readline requires an output stream for echoing characters. By wrapping
+ * stdout in a mutable stream, we can suppress echo during paste detection
+ * or any other time we need to control what appears on screen.
+ *
+ * Also proxies TTY methods (cursorTo, clearLine, etc.) so readline works
+ * correctly on both Windows and macOS.
+ */
+import { Writable } from "node:stream";
+export declare class MutableOutput extends Writable {
+    private _muted;
+    constructor();
+    get muted(): boolean;
+    /** Mute all output — nothing written to stdout. */
+    mute(): void;
+    /** Unmute — resume writing to stdout. */
+    unmute(): void;
+    _write(chunk: Buffer | string, _encoding: string, callback: () => void): void;
+}

package/dist/console/mutable-output.js

@@ -0,0 +1,51 @@
+/**
+ * MutableOutput — a Writable stream wrapper around stdout that can be muted.
+ *
+ * Readline requires an output stream for echoing characters. By wrapping
+ * stdout in a mutable stream, we can suppress echo during paste detection
+ * or any other time we need to control what appears on screen.
+ *
+ * Also proxies TTY methods (cursorTo, clearLine, etc.) so readline works
+ * correctly on both Windows and macOS.
+ */
+import { Writable } from "node:stream";
+export class MutableOutput extends Writable {
+    _muted = false;
+    constructor() {
+        super();
+        // Proxy TTY properties from real stdout
+        const self = this;
+        const out = process.stdout;
+        self.columns = out.columns;
+        self.rows = out.rows;
+        self.isTTY = out.isTTY;
+        // Proxy methods readline needs
+        self.cursorTo = out.cursorTo?.bind(out);
+        self.clearLine = out.clearLine?.bind(out);
+        self.moveCursor = out.moveCursor?.bind(out);
+        self.getWindowSize = () => [out.columns || 80, out.rows || 24];
+        // Forward resize events
+        process.stdout.on("resize", () => {
+            self.columns = out.columns;
+            self.rows = out.rows;
+            this.emit("resize");
+        });
+    }
+    get muted() {
+        return this._muted;
+    }
+    /** Mute all output — nothing written to stdout. */
+    mute() {
+        this._muted = true;
+    }
+    /** Unmute — resume writing to stdout. */
+    unmute() {
+        this._muted = false;
+    }
+    _write(chunk, _encoding, callback) {
+        if (!this._muted) {
+            process.stdout.write(chunk);
+        }
+        callback();
+    }
+}

package/dist/console/paste-handler.d.ts

@@ -0,0 +1,63 @@
+/**
+ * PasteHandler — detects and manages pasted text in a readline REPL.
+ *
+ * Handles:
+ * - Multi-line pastes: collapses into a numbered placeholder, expands on Enter
+ * - Long single-line pastes: dispatches directly with truncated preview
+ * - File drag & drop: detects pasted file paths, converts to [Image #N] / [File #N] tags
+ *
+ * Works on both Windows and macOS terminals.
+ */
+import type { Interface as ReadlineInterface } from "node:readline";
+import { type FileAttachment, FileDropHandler } from "./file-drop.js";
+import type { MutableOutput } from "./mutable-output.js";
+export interface PasteResult {
+    /** The final input text (with placeholders expanded). */
+    input: string;
+    /** Whether the input contained expanded paste placeholders. */
+    hadPaste: boolean;
+    /** File attachments referenced in the input. */
+    attachments: FileAttachment[];
+}
+export interface PasteHandlerOptions {
+    /** Readline interface */
+    rl: ReadlineInterface;
+    /** Mutable output stream for suppressing echo */
+    output: MutableOutput;
+    /** Debounce timeout in ms (default: 30) */
+    debounceMs?: number;
+    /** Minimum chunk size to consider a single-line paste (default: 100) */
+    longPasteThreshold?: number;
+    /** Callback when a line (or expanded paste) is ready to dispatch. */
+    onLine: (result: PasteResult) => void;
+    /** Optional: format the prompt string for re-rendering. */
+    formatPrompt?: () => string;
+    /** Optional: format a file tag for display (receives attachment, returns styled string). */
+    formatFileTag?: (attachment: FileAttachment) => string;
+    /** Optional: format the "file attached" hint shown after a drop. */
+    formatFileHint?: (attachment: FileAttachment) => string;
+}
+export declare class PasteHandler {
+    private buffer;
+    private timer;
+    private count;
+    private storedTexts;
+    private prePastePrefix;
+    private lastKeystrokeTime;
+    readonly fileDrop: FileDropHandler;
+    private rl;
+    private output;
+    private debounceMs;
+    private longPasteThreshold;
+    private onLine;
+    private formatPrompt;
+    private formatFileTag;
+    private formatFileHint;
+    constructor(options: PasteHandlerOptions);
+    /** Call from _ttyWrite override to track keystroke timing. */
+    onKeystroke(): void;
+    /** Clear all stored paste data (e.g. on session reset). */
+    reset(): void;
+    private installHooks;
+    private processPaste;
+}