@teammates/cli 0.1.0 → 0.2.0

package/dist/console/dropdown.js

@@ -0,0 +1,63 @@
+/**
+ * Dropdown — renders lines below the readline prompt without disrupting input.
+ *
+ * Hooks readline's internal _refreshLine to append dropdown content below
+ * the prompt, then repositions the cursor back to the input line.
+ *
+ * Works on both Windows and macOS terminals.
+ */
+import { esc, stripAnsi, truncateAnsi } from "@teammates/consolonia";
+import { cursorToCol } from "./ansi.js";
+export class Dropdown {
+    rl;
+    lines = [];
+    out = process.stdout;
+    refreshing = false;
+    constructor(rl) {
+        this.rl = rl;
+        this.installHook();
+    }
+    /** Number of lines currently rendered below the prompt. */
+    get rendered() {
+        return this.lines.length;
+    }
+    /** Set dropdown content and trigger a re-render. */
+    render(newLines) {
+        this.lines = newLines;
+        this.rl._refreshLine();
+    }
+    /** Clear dropdown content. Next _refreshLine won't append anything. */
+    clear() {
+        this.lines = [];
+    }
+    installHook() {
+        const origRefresh = this.rl._refreshLine.bind(this.rl);
+        this.rl._refreshLine = () => {
+            if (this.refreshing) {
+                origRefresh();
+                return;
+            }
+            this.refreshing = true;
+            // Run original: clears below, writes prompt, positions cursor
+            origRefresh();
+            // Append dropdown lines below the prompt
+            if (this.lines.length > 0) {
+                const cols = this.out.columns || 120;
+                let buf = "";
+                for (const line of this.lines) {
+                    buf += `\n${truncateAnsi(line, cols - 1)}`;
+                }
+                this.out.write(buf);
+                // Move cursor back to the prompt line
+                const n = this.lines.length;
+                this.out.write(esc.moveUp(n));
+                // Restore cursor column position
+                const promptText = this.rl._prompt ?? "";
+                const promptLen = stripAnsi(promptText).length;
+                const cursor = this.rl.cursor ?? 0;
+                this.out.write(cursorToCol(promptLen + cursor + 1));
+            }
+            this.refreshing = false;
+        };
+    }
+}

package/dist/console/file-drop.d.ts

@@ -0,0 +1,59 @@
+/**
+ * FileDropHandler — detects dragged/dropped files in terminal input.
+ *
+ * When a file is dragged into a terminal, the OS pastes the file path as text.
+ * This handler detects path-like input and converts it to file attachment tags.
+ *
+ * Supports images (png, jpg, gif, webp, svg) and general files.
+ * Works on both Windows (C:\...) and macOS/Linux (/...) terminals.
+ */
+export interface FileAttachment {
+    /** Unique ID for this attachment. */
+    id: number;
+    /** Absolute path to the file. */
+    path: string;
+    /** File basename. */
+    name: string;
+    /** Whether this is an image file. */
+    isImage: boolean;
+    /** File size in bytes. */
+    size: number;
+}
+export declare class FileDropHandler {
+    private nextId;
+    private attachments;
+    /** All current attachments. */
+    getAll(): FileAttachment[];
+    /** Get a specific attachment by ID. */
+    get(id: number): FileAttachment | undefined;
+    /** Remove an attachment by ID. */
+    remove(id: number): boolean;
+    /** Clear all attachments. */
+    clear(): void;
+    /**
+     * Check if a string looks like a file path that was drag-and-dropped.
+     * Returns the cleaned path if it's a valid file, null otherwise.
+     */
+    detectFilePath(input: string): string | null;
+    /**
+     * Try to convert input text into file attachments.
+     * Returns the modified input (with file tags inserted) and whether any files were detected.
+     */
+    processInput(input: string): {
+        text: string;
+        filesDetected: boolean;
+    };
+    /**
+     * Expand file tags in a string, replacing [Image #N] / [File #N] with
+     * the actual file path for downstream processing.
+     */
+    expandTags(input: string): {
+        text: string;
+        attachments: FileAttachment[];
+    };
+    private addFile;
+    /** Format an attachment as an inline tag. */
+    formatTag(attachment: FileAttachment): string;
+    /** Format a human-readable summary of an attachment. */
+    formatSummary(attachment: FileAttachment): string;
+}

package/dist/console/file-drop.js

@@ -0,0 +1,186 @@
+/**
+ * FileDropHandler — detects dragged/dropped files in terminal input.
+ *
+ * When a file is dragged into a terminal, the OS pastes the file path as text.
+ * This handler detects path-like input and converts it to file attachment tags.
+ *
+ * Supports images (png, jpg, gif, webp, svg) and general files.
+ * Works on both Windows (C:\...) and macOS/Linux (/...) terminals.
+ */
+import { statSync } from "node:fs";
+import { basename, extname, resolve } from "node:path";
+const IMAGE_EXTENSIONS = new Set([
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".webp",
+    ".svg",
+    ".bmp",
+    ".ico",
+    ".tiff",
+    ".tif",
+]);
+const _KNOWN_EXTENSIONS = new Set([
+    ...IMAGE_EXTENSIONS,
+    ".pdf",
+    ".txt",
+    ".md",
+    ".json",
+    ".csv",
+    ".xml",
+    ".yaml",
+    ".yml",
+    ".ts",
+    ".js",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".c",
+    ".cpp",
+    ".h",
+    ".html",
+    ".css",
+    ".sql",
+    ".sh",
+    ".bat",
+    ".ps1",
+    ".log",
+    ".env",
+    ".toml",
+    ".ini",
+    ".cfg",
+]);
+export class FileDropHandler {
+    nextId = 1;
+    attachments = new Map();
+    /** All current attachments. */
+    getAll() {
+        return [...this.attachments.values()];
+    }
+    /** Get a specific attachment by ID. */
+    get(id) {
+        return this.attachments.get(id);
+    }
+    /** Remove an attachment by ID. */
+    remove(id) {
+        return this.attachments.delete(id);
+    }
+    /** Clear all attachments. */
+    clear() {
+        this.attachments.clear();
+    }
+    /**
+     * Check if a string looks like a file path that was drag-and-dropped.
+     * Returns the cleaned path if it's a valid file, null otherwise.
+     */
+    detectFilePath(input) {
+        let candidate = input.trim();
+        // Strip surrounding quotes (Windows often wraps paths in quotes)
+        if ((candidate.startsWith('"') && candidate.endsWith('"')) ||
+            (candidate.startsWith("'") && candidate.endsWith("'"))) {
+            candidate = candidate.slice(1, -1);
+        }
+        // Must look like an absolute path
+        const isAbsoluteWindows = /^[A-Za-z]:\\/.test(candidate);
+        const isAbsoluteUnix = candidate.startsWith("/");
+        if (!isAbsoluteWindows && !isAbsoluteUnix)
+            return null;
+        // Should not contain newlines or control characters
+        if (/[\n\r\t]/.test(candidate))
+            return null;
+        // Resolve and check existence
+        const resolved = resolve(candidate);
+        try {
+            const st = statSync(resolved);
+            if (st.isFile())
+                return resolved;
+        }
+        catch {
+            // File doesn't exist
+        }
+        return null;
+    }
+    /**
+     * Try to convert input text into file attachments.
+     * Returns the modified input (with file tags inserted) and whether any files were detected.
+     */
+    processInput(input) {
+        // Check if the entire input is a single file path
+        const singlePath = this.detectFilePath(input);
+        if (singlePath) {
+            const attachment = this.addFile(singlePath);
+            const tag = this.formatTag(attachment);
+            return { text: `${tag} `, filesDetected: true };
+        }
+        // Check for file paths mixed with text — look for path-like tokens
+        let modified = input;
+        let detected = false;
+        // Match Windows paths: C:\... or "C:\..."
+        // Match Unix paths: /home/... or "/home/..."
+        const pathPattern = /(?:"([A-Za-z]:\\[^"]+)"|'([A-Za-z]:\\[^']+)'|([A-Za-z]:\\[^\s]+)|"(\/[^"]+)"|'(\/[^']+)'|(\/[^\s]+\.\w{1,5}))/g;
+        let match;
+        const replacements = [];
+        while ((match = pathPattern.exec(input)) !== null) {
+            const rawMatch = match[0];
+            const path = match[1] ?? match[2] ?? match[3] ?? match[4] ?? match[5] ?? match[6];
+            const resolved = this.detectFilePath(path);
+            if (resolved) {
+                const attachment = this.addFile(resolved);
+                replacements.push({ from: rawMatch, to: this.formatTag(attachment) });
+                detected = true;
+            }
+        }
+        for (const { from, to } of replacements) {
+            modified = modified.replace(from, to);
+        }
+        return { text: modified, filesDetected: detected };
+    }
+    /**
+     * Expand file tags in a string, replacing [Image #N] / [File #N] with
+     * the actual file path for downstream processing.
+     */
+    expandTags(input) {
+        const used = [];
+        const expanded = input.replace(/\[(Image|File) #(\d+)\]/g, (_match, _type, num) => {
+            const id = parseInt(num, 10);
+            const attachment = this.attachments.get(id);
+            if (attachment) {
+                used.push(attachment);
+                return attachment.path;
+            }
+            return _match;
+        });
+        return { text: expanded, attachments: used };
+    }
+    addFile(filePath) {
+        // Check if this file is already attached
+        for (const existing of this.attachments.values()) {
+            if (existing.path === filePath)
+                return existing;
+        }
+        const ext = extname(filePath).toLowerCase();
+        const st = statSync(filePath);
+        const attachment = {
+            id: this.nextId++,
+            path: filePath,
+            name: basename(filePath),
+            isImage: IMAGE_EXTENSIONS.has(ext),
+            size: st.size,
+        };
+        this.attachments.set(attachment.id, attachment);
+        return attachment;
+    }
+    /** Format an attachment as an inline tag. */
+    formatTag(attachment) {
+        const type = attachment.isImage ? "Image" : "File";
+        return `[${type} #${attachment.id}]`;
+    }
+    /** Format a human-readable summary of an attachment. */
+    formatSummary(attachment) {
+        const type = attachment.isImage ? "Image" : "File";
+        const sizeKB = (attachment.size / 1024).toFixed(1);
+        return `${type} #${attachment.id}: ${attachment.name} (${sizeKB}KB)`;
+    }
+}

package/dist/console/file-drop.test.d.ts

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

package/dist/console/file-drop.test.js

@@ -0,0 +1,145 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { FileDropHandler } from "./file-drop.js";
+let handler;
+let testDir;
+let testFile;
+let testImage;
+beforeEach(() => {
+    handler = new FileDropHandler();
+    testDir = join(tmpdir(), `file-drop-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(testDir, { recursive: true });
+    testFile = join(testDir, "example.txt");
+    testImage = join(testDir, "photo.png");
+    writeFileSync(testFile, "hello world");
+    writeFileSync(testImage, "fake png data");
+});
+afterEach(() => {
+    rmSync(testDir, { recursive: true, force: true });
+});
+describe("detectFilePath", () => {
+    it("detects a valid absolute path", () => {
+        const result = handler.detectFilePath(testFile);
+        expect(result).toBe(testFile);
+    });
+    it("detects a quoted absolute path", () => {
+        const result = handler.detectFilePath(`"${testFile}"`);
+        expect(result).toBe(testFile);
+    });
+    it("detects a single-quoted absolute path", () => {
+        const result = handler.detectFilePath(`'${testFile}'`);
+        expect(result).toBe(testFile);
+    });
+    it("returns null for relative paths", () => {
+        const result = handler.detectFilePath("relative/path.txt");
+        expect(result).toBeNull();
+    });
+    it("returns null for URLs", () => {
+        expect(handler.detectFilePath("https://example.com/file.txt")).toBeNull();
+        expect(handler.detectFilePath("http://localhost:3000")).toBeNull();
+    });
+    it("returns null for empty strings", () => {
+        expect(handler.detectFilePath("")).toBeNull();
+        expect(handler.detectFilePath("   ")).toBeNull();
+    });
+    it("returns null for paths with newlines", () => {
+        expect(handler.detectFilePath("/some/path\nwith\nnewlines")).toBeNull();
+    });
+    it("returns null for non-existent files", () => {
+        const result = handler.detectFilePath(join(testDir, "nonexistent.txt"));
+        expect(result).toBeNull();
+    });
+});
+describe("processInput", () => {
+    it("detects a single file path", () => {
+        const result = handler.processInput(testFile);
+        expect(result.filesDetected).toBe(true);
+        expect(result.text).toContain("[File #1]");
+    });
+    it("detects an image file", () => {
+        const result = handler.processInput(testImage);
+        expect(result.filesDetected).toBe(true);
+        expect(result.text).toContain("[Image #1]");
+    });
+    it("passes through non-file text", () => {
+        const result = handler.processInput("just some regular text");
+        expect(result.filesDetected).toBe(false);
+        expect(result.text).toBe("just some regular text");
+    });
+    it("does not re-add the same file twice", () => {
+        handler.processInput(testFile);
+        handler.processInput(testFile);
+        const all = handler.getAll();
+        expect(all).toHaveLength(1);
+    });
+});
+describe("expandTags", () => {
+    it("expands [File #N] tags to paths", () => {
+        handler.processInput(testFile);
+        const { text, attachments } = handler.expandTags("Please review [File #1]");
+        expect(text).toContain(testFile);
+        expect(text).not.toContain("[File #1]");
+        expect(attachments).toHaveLength(1);
+        expect(attachments[0].path).toBe(testFile);
+    });
+    it("expands [Image #N] tags to paths", () => {
+        handler.processInput(testImage);
+        const { text, attachments } = handler.expandTags("Look at [Image #1]");
+        expect(text).toContain(testImage);
+        expect(text).not.toContain("[Image #1]");
+        expect(attachments).toHaveLength(1);
+        expect(attachments[0].isImage).toBe(true);
+    });
+    it("leaves unknown tags untouched", () => {
+        const { text } = handler.expandTags("Check [File #999]");
+        expect(text).toBe("Check [File #999]");
+    });
+});
+describe("formatTag", () => {
+    it("formats a file attachment as [File #N]", () => {
+        handler.processInput(testFile);
+        const attachment = handler.get(1);
+        expect(handler.formatTag(attachment)).toBe("[File #1]");
+    });
+    it("formats an image attachment as [Image #N]", () => {
+        handler.processInput(testImage);
+        const attachment = handler.get(1);
+        expect(handler.formatTag(attachment)).toBe("[Image #1]");
+    });
+});
+describe("formatSummary", () => {
+    it("produces a human-readable summary for a file", () => {
+        handler.processInput(testFile);
+        const attachment = handler.get(1);
+        const summary = handler.formatSummary(attachment);
+        expect(summary).toContain("File #1");
+        expect(summary).toContain("example.txt");
+        expect(summary).toContain("KB");
+    });
+    it("produces a human-readable summary for an image", () => {
+        handler.processInput(testImage);
+        const attachment = handler.get(1);
+        const summary = handler.formatSummary(attachment);
+        expect(summary).toContain("Image #1");
+        expect(summary).toContain("photo.png");
+        expect(summary).toContain("KB");
+    });
+});
+describe("attachment management", () => {
+    it("get() returns undefined for missing IDs", () => {
+        expect(handler.get(999)).toBeUndefined();
+    });
+    it("remove() deletes an attachment", () => {
+        handler.processInput(testFile);
+        expect(handler.remove(1)).toBe(true);
+        expect(handler.get(1)).toBeUndefined();
+    });
+    it("clear() removes all attachments", () => {
+        handler.processInput(testFile);
+        handler.processInput(testImage);
+        handler.clear();
+        expect(handler.getAll()).toHaveLength(0);
+    });
+});

package/dist/console/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @teammates/console — reusable interactive console components for Node.js CLIs.
+ *
+ * Components:
+ *   - InteractiveReadline: batteries-included REPL with paste handling + autocomplete
+ *   - MutableOutput: writable stream that can be muted/unmuted
+ *   - PasteHandler: detects and manages pasted text
+ *   - Dropdown: renders content below the readline prompt
+ *   - Wordwheel: autocomplete engine with keyboard navigation
+ *   - ANSI helpers: re-exported from @teammates/consolonia + CLI-specific extras
+ */
+export { stripAnsi, truncateAnsi, visibleLength } from "@teammates/consolonia";
+export { cr, cursorDown, cursorHome, cursorToCol, cursorUp, eraseDown, eraseLine, eraseScreen, eraseToEnd, } from "./ansi.js";
+export { Dropdown } from "./dropdown.js";
+export { type FileAttachment, FileDropHandler } from "./file-drop.js";
+export { InteractiveReadline, type InteractiveReadlineOptions, } from "./interactive-readline.js";
+export { renderMarkdownTables } from "./markdown-table.js";
+export { MutableOutput } from "./mutable-output.js";
+export { PasteHandler, type PasteHandlerOptions, type PasteResult, } from "./paste-handler.js";
+export { PromptBox, type PromptBoxOptions } from "./prompt-box.js";
+export { PromptInput, type PromptInputOptions } from "./prompt-input.js";
+export { Wordwheel, type WordwheelItem, type WordwheelOptions, } from "./wordwheel.js";

package/dist/console/index.js

@@ -0,0 +1,23 @@
+/**
+ * @teammates/console — reusable interactive console components for Node.js CLIs.
+ *
+ * Components:
+ *   - InteractiveReadline: batteries-included REPL with paste handling + autocomplete
+ *   - MutableOutput: writable stream that can be muted/unmuted
+ *   - PasteHandler: detects and manages pasted text
+ *   - Dropdown: renders content below the readline prompt
+ *   - Wordwheel: autocomplete engine with keyboard navigation
+ *   - ANSI helpers: re-exported from @teammates/consolonia + CLI-specific extras
+ */
+// ANSI helpers — consolonia re-exports + CLI-specific extras
+export { stripAnsi, truncateAnsi, visibleLength } from "@teammates/consolonia";
+export { cr, cursorDown, cursorHome, cursorToCol, cursorUp, eraseDown, eraseLine, eraseScreen, eraseToEnd, } from "./ansi.js";
+export { Dropdown } from "./dropdown.js";
+export { FileDropHandler } from "./file-drop.js";
+export { InteractiveReadline, } from "./interactive-readline.js";
+export { renderMarkdownTables } from "./markdown-table.js";
+export { MutableOutput } from "./mutable-output.js";
+export { PasteHandler, } from "./paste-handler.js";
+export { PromptBox } from "./prompt-box.js";
+export { PromptInput } from "./prompt-input.js";
+export { Wordwheel, } from "./wordwheel.js";

package/dist/console/interactive-readline.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { type Interface as ReadlineInterface } from "node:readline";
+import { Dropdown } from "./dropdown.js";
+import type { FileAttachment } from "./file-drop.js";
+import { MutableOutput } from "./mutable-output.js";
+import { PasteHandler } from "./paste-handler.js";
+import { Wordwheel, type WordwheelItem } from "./wordwheel.js";
+export interface InteractiveReadlineOptions {
+    /** Prompt string (may include ANSI color codes). */
+    prompt: string;
+    /** Return completion items for the current line/cursor. */
+    getItems?: (line: string, cursor: number) => WordwheelItem[];
+    /** Called when a line is ready to dispatch. */
+    onLine: (input: string, attachments?: FileAttachment[]) => Promise<void> | void;
+    /** Called when readline closes (Ctrl+D). */
+    onClose?: () => void;
+    /** Format a highlighted wordwheel item. */
+    formatHighlighted?: (item: WordwheelItem) => string;
+    /** Format a normal wordwheel item. */
+    formatNormal?: (item: WordwheelItem) => string;
+    /** Paste debounce timeout in ms (default: 30). */
+    pasteDebounceMs?: number;
+    /** Minimum chunk size to consider a single-line paste (default: 100). */
+    longPasteThreshold?: number;
+}
+export declare class InteractiveReadline {
+    readonly rl: ReadlineInterface;
+    readonly output: MutableOutput;
+    readonly dropdown: Dropdown;
+    readonly wordwheel: Wordwheel;
+    readonly pasteHandler: PasteHandler;
+    private dispatching;
+    private prompt;
+    private onLine;
+    constructor(options: InteractiveReadlineOptions);
+    /** Start the REPL — shows the prompt. */
+    start(): void;
+    /** Clear the terminal and re-show the prompt. */
+    clearScreen(): void;
+    /** Reset all state (paste buffers, wordwheel, etc.). */
+    reset(): void;
+    /** Access the current line text. */
+    get line(): string;
+    /** Set the current line text and cursor. */
+    setLine(text: string): void;
+    private installKeyHandler;
+}