caroushell 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ubershmekel
+
+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,73 @@
+# Caroushell
+
+Caroushell is an interactive terminal carousel that suggests commands from your
+history, AI prompts, and configuration snippets so you can pick the next shell
+command without leaving the keyboard.
+
+## Features
+
+- Dual-pane carousel that combines history-based and AI-generated command
+  suggestions.
+- Runs the selected command directly in your current terminal session.
+- Logs activity under `~/.caroushell/logs` for easy troubleshooting.
+- Extensible config file (`~/.caroushell/config.json`) so you can point the CLI
+  at different API keys or settings.
+
+## Requirements
+
+- Node.js 18 or newer.
+- A `~/.caroushell/config.json` file that contains the tokens Caroushell needs.
+  Currently the file expects a Gemini API key:
+
+```json
+{
+  "GEMINI_API_KEY": "your-api-key"
+}
+```
+
+## Installation
+
+Install globally (recommended):
+
+```bash
+npm install -g caroushell
+caroushell
+```
+
+Or run it ad-hoc with NPX once it is published:
+
+```bash
+npx caroushell
+```
+
+## Usage
+
+Caroushell opens an interactive prompt:
+
+- Type to update the suggestions immediately and trigger refreshed history/AI
+  results.
+- Use arrow keys to move between suggestions in the carousel.
+- Press `Enter` to run the highlighted command.
+- Press `Ctrl+C` to exit. `Ctrl+D` exits when the current row is empty.
+
+Logs are written to `~/.caroushell/logs/MM-DD.txt`. Inspect these files if you
+need to debug AI suggestions or the terminal renderer. Configuration lives at
+`~/.caroushell/config.json` (override via `CAROUSHELL_CONFIG_PATH`).
+
+## Development
+
+```bash
+npm install
+npm run dev        # tsx watch mode
+npm run build      # emits dist/
+npm run test:generate
+npm publish --dry-run  # verify package contents before publishing
+```
+
+The `prepare` script automatically builds before `npm publish` or when
+installing from git. The package ships only the compiled `dist/` output plus
+this README and the MIT license so `npx caroushell` works immediately.
+
+## License
+
+Released under the [MIT License](./LICENSE).

package/dist/ai-suggester.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AISuggester = void 0;
+exports.generateContent = generateContent;
+const logs_1 = require("./logs");
+const config_1 = require("./config");
+async function generateContent(prompt, options) {
+    const apiKey = options?.apiKey || process.env.GEMINI_API_KEY;
+    const model = options?.model || "gemini-2.5-flash-lite";
+    const temperature = options?.temperature ?? 0.3;
+    const maxOutputTokens = options?.maxOutputTokens ?? 256;
+    if (!apiKey) {
+        (0, logs_1.logLine)("AI generation skipped: missing API key");
+        return "";
+    }
+    if (!prompt.trim()) {
+        (0, logs_1.logLine)("AI generation skipped: empty prompt");
+        return "";
+    }
+    try {
+        const start = Date.now();
+        const fetchImpl = globalThis.fetch;
+        if (!fetchImpl)
+            return "";
+        const res = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${apiKey}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                contents: [
+                    {
+                        role: "user",
+                        parts: [{ text: prompt }],
+                    },
+                ],
+                generationConfig: {
+                    temperature,
+                    maxOutputTokens,
+                },
+            }),
+        });
+        if (!res.ok)
+            return "";
+        const json = (await res.json());
+        const text = json?.candidates?.[0]?.content?.parts?.[0]?.text || "";
+        const out = typeof text === "string" ? text : "";
+        const duration = Date.now() - start;
+        // Log duration and each non-empty line of the AI text
+        try {
+            await (0, logs_1.logLine)(`AI duration: ${duration} ms`);
+            if (out.trim()) {
+                const lines = out
+                    .split(/\r?\n/)
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+                // .map((s) => `AI text: ${s}`);
+                // await logLines(lines);
+            }
+        }
+        catch {
+            // best-effort logging; ignore failures
+        }
+        return out;
+    }
+    catch {
+        return "";
+    }
+}
+class AISuggester {
+    constructor(opts) {
+        this.prefix = "🤖";
+        this.apiKey = opts?.apiKey;
+        this.model = opts?.model || "gemini-2.5-flash-lite";
+    }
+    async init() {
+        this.apiKey =
+            this.apiKey ||
+                (await (0, config_1.getConfig)()).GEMINI_API_KEY ||
+                process.env.GEMINI_API_KEY;
+    }
+    descriptionForAi() {
+        return "";
+    }
+    async suggest(carousel, maxDisplayed) {
+        if (!this.apiKey) {
+            (0, logs_1.logLine)("AI generation skipped: missing API key");
+            return [];
+        }
+        const descriptions = [];
+        for (const suggester of carousel.getSuggesters()) {
+            const desc = suggester.descriptionForAi();
+            if (desc) {
+                descriptions.push(desc);
+            }
+        }
+        const prompt = `You are a shell assistant. Given a partial shell input, suggest ${maxDisplayed}\
+useful, concise shell commands that the user might run next.\
+Return one suggestion per line, no numbering, no extra text.
+
+The current line is: "${carousel.getCurrentRow()}
+
+${descriptions.join("\n\n")}
+`;
+        (0, logs_1.logLine)(prompt);
+        const text = await generateContent(prompt, {
+            apiKey: this.apiKey,
+            model: this.model,
+            temperature: 0.3,
+            maxOutputTokens: 128,
+        });
+        const lines = text
+            .split(/\r?\n/)
+            .map((s) => s.trim())
+            .filter(Boolean)
+            .slice(0, maxDisplayed);
+        (0, logs_1.logLine)(`AI lines: ${lines.length}`);
+        return lines;
+    }
+}
+exports.AISuggester = AISuggester;

package/dist/app.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.App = void 0;
+const terminal_1 = require("./terminal");
+const keyboard_1 = require("./keyboard");
+const carousel_1 = require("./carousel");
+const history_suggester_1 = require("./history-suggester");
+const ai_suggester_1 = require("./ai-suggester");
+const child_process_1 = require("child_process");
+function debounce(fn, ms) {
+    // Debounce function to limit the rate at which a function can fire
+    let t = null;
+    return (...args) => {
+        if (t)
+            clearTimeout(t);
+        t = setTimeout(() => fn(...args), ms);
+    };
+}
+class App {
+    constructor() {
+        this.terminal = new terminal_1.Terminal();
+        this.keyboard = new keyboard_1.Keyboard();
+        this.history = new history_suggester_1.HistorySuggester();
+        this.ai = new ai_suggester_1.AISuggester();
+        this.carousel = new carousel_1.Carousel({
+            top: this.history,
+            bottom: this.ai,
+            topRows: 2,
+            bottomRows: 2,
+            terminal: this.terminal,
+        });
+    }
+    async init() {
+        await this.history.init();
+        await this.ai.init();
+    }
+    async run() {
+        await this.init();
+        this.keyboard.start();
+        const updateSuggestions = debounce(async () => {
+            await this.carousel.updateSuggestions();
+        }, 300);
+        const handlers = {
+            "ctrl-c": () => this.exit(),
+            "ctrl-d": () => {
+                if (this.carousel.getCurrentRow().length === 0)
+                    this.exit();
+            },
+            backspace: () => {
+                this.carousel.deleteBeforeCursor();
+                // Immediate prompt redraw with existing suggestions
+                this.render();
+                // Async fetch of new suggestions
+                updateSuggestions();
+            },
+            enter: async () => {
+                const cmd = this.carousel.getCurrentRow().trim();
+                this.carousel.setInputBuffer("", 0);
+                await this.runCommand(cmd);
+                this.carousel.resetIndex();
+                updateSuggestions();
+            },
+            char: (evt) => {
+                this.carousel.insertAtCursor(evt.sequence);
+                // Immediate prompt redraw with existing suggestions
+                this.render();
+                // Async fetch of new suggestions
+                updateSuggestions();
+            },
+            up: () => {
+                this.carousel.up();
+                this.render();
+            },
+            down: () => {
+                this.carousel.down();
+                this.render();
+            },
+            left: () => {
+                this.carousel.moveCursorLeft();
+                this.render();
+            },
+            right: () => {
+                this.carousel.moveCursorRight();
+                this.render();
+            },
+            home: () => { },
+            end: () => { },
+            delete: () => { },
+            escape: () => { },
+        };
+        this.keyboard.on("key", async (evt) => {
+            const fn = handlers[evt.name];
+            if (fn)
+                await fn(evt);
+        });
+        // Initial draw
+        this.render();
+        await this.carousel.updateSuggestions();
+    }
+    render() {
+        this.carousel.render();
+        // Cursor placement handled inside carousel render.
+    }
+    async runCommand(cmd) {
+        const { yellow, reset } = terminal_1.colors;
+        if (!cmd) {
+            // Log an empty line
+            this.terminal.renderBlock([">"]);
+            this.terminal.write("\n");
+            this.terminal.resetBlockTracking();
+            return;
+        }
+        // Log command in yellow
+        const width = process.stdout.columns || 80;
+        const lines = [`${yellow}$ ${cmd}${reset}`];
+        this.terminal.renderBlock(lines);
+        // Ensure command output starts on the next line
+        this.terminal.write("\n");
+        await this.history.add(cmd);
+        // Spawn shell
+        const isWin = process.platform === "win32";
+        const proc = (0, child_process_1.spawn)(isWin ? "cmd.exe" : "/bin/bash", [isWin ? "/c" : "-lc", cmd], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        await new Promise((resolve) => {
+            proc.stdout.on("data", (d) => process.stdout.write(d));
+            proc.stderr.on("data", (d) => process.stderr.write(d));
+            proc.on("close", () => resolve());
+        });
+        // After arbitrary output, reset render block tracking
+        this.terminal.resetBlockTracking();
+    }
+    exit() {
+        this.keyboard.stop();
+        process.exit(0);
+    }
+}
+exports.App = App;

package/dist/carousel.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Carousel = void 0;
+const logs_1 = require("./logs");
+const terminal_1 = require("./terminal");
+class Carousel {
+    constructor(opts) {
+        this.latestTop = [];
+        this.latestBottom = [];
+        this.index = 0;
+        this.inputBuffer = "";
+        this.inputCursor = 0;
+        this.terminal = opts.terminal;
+        this.top = opts.top;
+        this.bottom = opts.bottom;
+        this.topRowCount = opts.topRows;
+        this.bottomRowCount = opts.bottomRows;
+        const empty = "---";
+        this.latestTop = Array(this.topRowCount).fill(empty);
+        this.latestBottom = Array(this.bottomRowCount).fill(empty);
+    }
+    async updateSuggestions(input) {
+        if (typeof input === "string") {
+            this.setInputBuffer(input);
+        }
+        const topPromise = this.top.suggest(this, this.topRowCount);
+        const bottomPromise = this.bottom.suggest(this, this.bottomRowCount);
+        topPromise.then((r) => {
+            this.latestTop = r;
+            this.render();
+        });
+        bottomPromise.then((r) => {
+            this.latestBottom = r;
+            this.render();
+        });
+    }
+    up() {
+        this.index += 1;
+        if (this.index >= this.latestTop.length) {
+            this.index = this.latestTop.length;
+        }
+    }
+    down() {
+        this.index -= 1;
+        if (-this.index >= this.latestBottom.length) {
+            this.index = -this.latestBottom.length;
+        }
+    }
+    getRow(rowIndex) {
+        if (rowIndex < 0) {
+            const bottomIndex = -rowIndex - 1;
+            return this.latestBottom[bottomIndex] || "";
+        }
+        if (rowIndex === 0) {
+            return this.inputBuffer;
+        }
+        if (rowIndex > 0) {
+            const topIndex = rowIndex - 1;
+            return this.latestTop[topIndex] || "";
+        }
+        return "";
+    }
+    getPrefixByIndex(index) {
+        if (index < 0) {
+            return this.bottom.prefix;
+        }
+        if (index > 0) {
+            return this.top.prefix;
+        }
+        return "$> ";
+    }
+    getFormattedRow(rowIndex) {
+        const rowStr = this.getRow(rowIndex);
+        let prefix = this.getPrefixByIndex(rowIndex);
+        const { brightWhite, reset, dim } = terminal_1.colors;
+        let color = dim;
+        if (this.index === rowIndex) {
+            color = brightWhite;
+            if (rowIndex !== 0) {
+                prefix = "> ";
+            }
+        }
+        return `${color}${prefix}${rowStr}${reset}`;
+    }
+    getCurrentRow() {
+        return this.getRow(this.index);
+    }
+    setInputBuffer(value, cursorPos = value.length) {
+        this.inputBuffer = value;
+        this.inputCursor = Math.max(0, Math.min(cursorPos, this.inputBuffer.length));
+    }
+    resetIndex() {
+        this.index = 0;
+    }
+    adoptSelectionIntoInput() {
+        if (this.index === 0)
+            return;
+        const current = this.getRow(this.index);
+        this.setInputBuffer(current, current.length);
+        this.index = 0;
+    }
+    insertAtCursor(text) {
+        if (!text)
+            return;
+        this.adoptSelectionIntoInput();
+        const before = this.inputBuffer.slice(0, this.inputCursor);
+        const after = this.inputBuffer.slice(this.inputCursor);
+        this.inputBuffer = `${before}${text}${after}`;
+        this.inputCursor += text.length;
+    }
+    deleteBeforeCursor() {
+        this.adoptSelectionIntoInput();
+        if (this.inputCursor === 0)
+            return;
+        const before = this.inputBuffer.slice(0, this.inputCursor - 1);
+        const after = this.inputBuffer.slice(this.inputCursor);
+        this.inputBuffer = `${before}${after}`;
+        this.inputCursor -= 1;
+    }
+    moveCursorLeft() {
+        this.adoptSelectionIntoInput();
+        if (this.inputCursor === 0)
+            return;
+        this.inputCursor -= 1;
+    }
+    moveCursorRight() {
+        this.adoptSelectionIntoInput();
+        if (this.inputCursor >= this.inputBuffer.length)
+            return;
+        this.inputCursor += 1;
+    }
+    getPromptCursorColumn() {
+        const prefix = this.getPrefixByIndex(0);
+        return prefix.length + this.inputCursor;
+    }
+    render() {
+        (0, logs_1.logLine)("Rendering carousel");
+        // Draw all the lines
+        const width = process.stdout.columns || 80;
+        const { brightWhite, reset, dim } = terminal_1.colors;
+        const lines = [];
+        const start = this.index + this.topRowCount;
+        const rowCount = this.topRowCount + this.bottomRowCount + 1;
+        const end = start - rowCount;
+        for (let i = start; i > end; i--) {
+            lines.push({
+                rowIndex: i,
+                text: this.getFormattedRow(i).slice(0, width - 2),
+            });
+        }
+        const promptLineIndex = lines.findIndex((line) => line.rowIndex === 0);
+        const cursorRow = this.topRowCount;
+        const cursorCol = this.getPromptCursorColumn();
+        this.terminal.renderBlock(lines.map((line) => line.text), cursorRow, cursorCol);
+    }
+    getSuggesters() {
+        return [this.top, this.bottom];
+    }
+}
+exports.Carousel = Carousel;

package/dist/config.js

@@ -0,0 +1,51 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configFolder = configFolder;
+exports.getConfig = getConfig;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+function configFolder(subpath) {
+    const home = os.homedir();
+    // Default path: ~/.caroushell/history
+    return path.join(home, ".caroushell", subpath);
+}
+async function getConfig() {
+    // Load config from ~/.caroushell/config.json
+    const configPath = process.env.CAROUSHELL_CONFIG_PATH || configFolder("config.json");
+    const config = JSON.parse(await fs_1.promises.readFile(configPath, "utf8"));
+    return config;
+}

package/dist/history-suggester.js

@@ -0,0 +1,78 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HistorySuggester = void 0;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const config_1 = require("./config");
+class HistorySuggester {
+    constructor(filePath) {
+        this.prefix = "⌛";
+        this.items = [];
+        this.maxItems = 1000;
+        const home = process.env.HOME || process.env.USERPROFILE || process.cwd();
+        // Default path: ~/.caroushell/history
+        this.filePath = filePath || (0, config_1.configFolder)("history");
+    }
+    async init() {
+        try {
+            await fs_1.promises.mkdir(path_1.default.dirname(this.filePath), { recursive: true });
+        }
+        catch { }
+        try {
+            const data = await fs_1.promises.readFile(this.filePath, "utf8");
+            this.items = data.split(/\r?\n/).filter(Boolean);
+        }
+        catch {
+            this.items = [];
+        }
+    }
+    async add(command) {
+        if (!command.trim())
+            return;
+        // Deduplicate recent duplicate
+        if (this.items[this.items.length - 1] !== command) {
+            this.items.push(command);
+            if (this.items.length > this.maxItems)
+                this.items.shift();
+            await fs_1.promises
+                .mkdir(path_1.default.dirname(this.filePath), { recursive: true })
+                .catch(() => { });
+            await fs_1.promises.writeFile(this.filePath, this.items.join("\n"), "utf8");
+        }
+    }
+    async suggest(carousel, maxDisplayed) {
+        const input = carousel.getCurrentRow();
+        if (!input) {
+            return this.items.reverse();
+        }
+        const q = input.toLowerCase();
+        const matched = [];
+        for (let i = this.items.length - 1; i >= 0; i--) {
+            const it = this.items[i];
+            if (it.toLowerCase().includes(q))
+                matched.push(it);
+        }
+        return matched;
+    }
+    descriptionForAi() {
+        const lines = [];
+        const maxHistoryLines = 20;
+        const start = Math.max(0, this.items.length - maxHistoryLines);
+        const end = this.items.length - 1;
+        const reverseSlice = this.items.slice(start, end).reverse();
+        if (reverseSlice.length > 0) {
+            lines.push(`The most recent command is: "${reverseSlice[0]}"`);
+        }
+        if (reverseSlice.length > 1) {
+            lines.push("The most recent commands are (from recent to oldest):");
+            for (let i = 0; i < reverseSlice.length; i++) {
+                lines.push(`  ${i + 1}. ${reverseSlice[i]}`);
+            }
+        }
+        return lines.join("\n");
+    }
+}
+exports.HistorySuggester = HistorySuggester;

package/dist/keyboard.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Keyboard = void 0;
+const events_1 = require("events");
+// Map escape/control sequences to semantic key names
+const KEYMAP = {
+    // Control keys
+    '\u0003': { name: 'ctrl-c', ctrl: true }, // ^C
+    '\u0004': { name: 'ctrl-d', ctrl: true }, // ^D
+    '\r': { name: 'enter' },
+    '\n': { name: 'enter' },
+    '\u007f': { name: 'backspace' }, // DEL
+    '\u0008': { name: 'backspace' }, // BS (Windows)
+    '\u001b': { name: 'escape' },
+    // Arrows (ANSI)
+    '\u001b[A': { name: 'up' },
+    '\u001b[B': { name: 'down' },
+    '\u001b[C': { name: 'right' },
+    '\u001b[D': { name: 'left' },
+    // Home/End/Delete variants
+    '\u001b[H': { name: 'home' },
+    '\u001b[F': { name: 'end' },
+    '\u001b[1~': { name: 'home' },
+    '\u001b[4~': { name: 'end' },
+    '\u001b[3~': { name: 'delete' },
+};
+// For efficient prefix checks
+const KEY_PREFIXES = new Set();
+for (const seq of Object.keys(KEYMAP)) {
+    for (let i = 1; i <= seq.length; i++) {
+        KEY_PREFIXES.add(seq.slice(0, i));
+    }
+}
+class Keyboard extends events_1.EventEmitter {
+    constructor() {
+        super(...arguments);
+        this.active = false;
+        this.buffer = '';
+    }
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        const stdin = process.stdin;
+        stdin.setEncoding('utf8');
+        if (stdin.isTTY)
+            stdin.setRawMode(true);
+        stdin.resume();
+        const onData = (data) => this.handleData(data);
+        stdin.on('data', onData);
+        this.once('stop', () => {
+            stdin.off('data', onData);
+            if (stdin.isTTY)
+                stdin.setRawMode(false);
+        });
+    }
+    stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.emit('stop');
+    }
+    handleData(data) {
+        this.buffer += data;
+        this.processBuffer();
+    }
+    processBuffer() {
+        // Try to consume as many full key sequences as possible
+        while (this.buffer.length > 0) {
+            const evt = this.matchSequence(this.buffer);
+            if (evt === 'need-more')
+                return; // wait for more bytes
+            if (evt) {
+                this.emit('key', evt);
+                this.buffer = this.buffer.slice(evt.sequence.length);
+                continue;
+            }
+            // No mapped sequence at buffer start; emit first char as 'char'
+            const ch = this.buffer[0];
+            const code = ch.charCodeAt(0);
+            if (code < 32 && ch !== '\t') {
+                // ignore other control chars
+                this.buffer = this.buffer.slice(1);
+                continue;
+            }
+            this.emit('key', { name: 'char', sequence: ch });
+            this.buffer = this.buffer.slice(1);
+        }
+    }
+    matchSequence(buf) {
+        // Fast path: exact match
+        const exact = KEYMAP[buf];
+        if (exact)
+            return { ...exact, sequence: buf };
+        // Try the longest possible mapped sequence that matches the buffer prefix
+        // Limit search by checking prefixes set.
+        let maxLen = 0;
+        let matched = null;
+        for (const seq of Object.keys(KEYMAP)) {
+            if (buf.startsWith(seq)) {
+                if (seq.length > maxLen) {
+                    maxLen = seq.length;
+                    matched = { ...KEYMAP[seq], sequence: seq };
+                }
+            }
+        }
+        if (matched)
+            return matched;
+        // If current buffer is a prefix to any known sequence, wait for more
+        if (KEY_PREFIXES.has(buf))
+            return 'need-more';
+        // No sequence match
+        return null;
+    }
+}
+exports.Keyboard = Keyboard;

package/dist/logs.js

@@ -0,0 +1,68 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logLine = logLine;
+exports.ensureLogFolderExists = ensureLogFolderExists;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+function getLogDir() {
+    return (0, config_1.configFolder)("logs");
+}
+function getLogFilePath(d = new Date()) {
+    const mm = String(d.getMonth() + 1).padStart(2, "0");
+    const dd = String(d.getDate()).padStart(2, "0");
+    return path.join(getLogDir(), `${mm}-${dd}.txt`);
+}
+async function ensureDir(dir) {
+    await fs_1.promises.mkdir(dir, { recursive: true });
+}
+function timestamp(date = new Date()) {
+    // local time iso string
+    return date.toISOString();
+}
+async function logLine(message, when = new Date()) {
+    const dir = getLogDir();
+    await ensureDir(dir);
+    const file = getLogFilePath(when);
+    const line = `[${timestamp(when)}] ${message}\n`;
+    await fs_1.promises.appendFile(file, line, "utf8");
+}
+// Ensure the ~/.caroushell/logs folder exists early in app startup
+async function ensureLogFolderExists() {
+    const dir = getLogDir();
+    await ensureDir(dir);
+    return dir;
+}

package/dist/main.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const app_1 = require("./app");
+const logs_1 = require("./logs");
+async function main() {
+    await (0, logs_1.ensureLogFolderExists)();
+    (0, logs_1.logLine)("Caroushell started");
+    const app = new app_1.App();
+    await app.run();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/terminal.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Terminal = exports.colors = void 0;
+const readline_1 = __importDefault(require("readline"));
+// Color helpers
+exports.colors = {
+    reset: "\x1b[0m",
+    white: "\x1b[37m",
+    brightWhite: "\x1b[97m",
+    dim: "\x1b[2m",
+    yellow: "\x1b[33m",
+};
+class Terminal {
+    constructor() {
+        this.out = process.stdout;
+        this.activeRows = 0;
+        this.cursorRow = 0;
+        this.cursorCol = 0;
+    }
+    moveCursorToTopOfBlock() {
+        if (this.activeRows === 0)
+            return;
+        readline_1.default.cursorTo(this.out, 0);
+        if (this.cursorRow > 0) {
+            readline_1.default.moveCursor(this.out, 0, -this.cursorRow);
+        }
+        this.cursorRow = 0;
+        this.cursorCol = 0;
+    }
+    withCork(fn) {
+        // Cork is like "don't flush" and then "uncork" is like flush.
+        // This prevents a flicker on the screen when we move the cursor around to render.
+        // Node's Writable has cork/uncork; guard for environments that may not.
+        const w = this.out;
+        const hasCork = typeof w.cork === "function" &&
+            typeof w.uncork === "function";
+        if (!hasCork) {
+            return fn();
+        }
+        w.cork();
+        try {
+            return fn();
+        }
+        finally {
+            w.uncork();
+        }
+    }
+    write(text) {
+        this.out.write(text);
+    }
+    hideCursor() {
+        this.write("\x1b[?25l");
+    }
+    showCursor() {
+        this.write("\x1b[?25h");
+    }
+    // Render a block of lines by clearing previous block (if any) and writing fresh
+    renderBlock(lines, cursorRow, cursorCol) {
+        this.withCork(() => {
+            this.moveCursorToTopOfBlock();
+            if (this.activeRows > 0) {
+                readline_1.default.cursorTo(this.out, 0);
+                readline_1.default.clearScreenDown(this.out);
+            }
+            for (let i = 0; i < lines.length; i++) {
+                this.out.write(lines[i]);
+                if (i < lines.length - 1)
+                    this.out.write("\n");
+            }
+            this.activeRows = lines.length;
+            this.cursorRow = Math.max(0, this.activeRows - 1);
+            const lastLine = lines[this.cursorRow] || "";
+            this.cursorCol = lastLine.length;
+            const needsPosition = typeof cursorRow === "number" || typeof cursorCol === "number";
+            if (needsPosition) {
+                const targetRow = typeof cursorRow === "number"
+                    ? Math.min(Math.max(cursorRow, 0), Math.max(0, this.activeRows - 1))
+                    : this.cursorRow;
+                const targetCol = Math.max(0, cursorCol ?? this.cursorCol);
+                this.moveCursorTo(targetRow, targetCol);
+            }
+        });
+    }
+    moveCursorTo(lineIndex, column) {
+        if (this.activeRows === 0)
+            return;
+        const safeLine = Math.min(Math.max(lineIndex, 0), Math.max(0, this.activeRows - 1));
+        const safeColumn = Math.max(0, column);
+        const rowDelta = safeLine - this.cursorRow;
+        if (rowDelta !== 0) {
+            readline_1.default.moveCursor(this.out, 0, rowDelta);
+        }
+        readline_1.default.cursorTo(this.out, safeColumn);
+        this.cursorRow = safeLine;
+        this.cursorCol = safeColumn;
+    }
+    // When we have printed arbitrary output that is not managed by renderBlock,
+    // reset internal line tracking so the next render starts fresh.
+    resetBlockTracking() {
+        this.activeRows = 0;
+        this.cursorRow = 0;
+        this.cursorCol = 0;
+    }
+}
+exports.Terminal = Terminal;

package/dist/test-generate.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ai_suggester_1 = require("./ai-suggester");
+async function main() {
+    if (!process.env.GEMINI_API_KEY) {
+        console.warn("Warning: GEMINI_API_KEY is not set. The answer may be empty.");
+    }
+    const question = "What is the capital of France?";
+    const answer = await (0, ai_suggester_1.generateContent)(question);
+    console.log(`Q: ${question}`);
+    console.log(`A: ${answer.trim()}`);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "caroushell",
+  "version": "0.1.0",
+  "description": "Terminal carousel that suggests commands from history, config, and AI.",
+  "type": "commonjs",
+  "main": "dist/main.js",
+  "bin": {
+    "caroushell": "dist/main.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsx src/main.ts",
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "start": "node dist/main.js",
+    "test:generate": "tsx src/test-generate.ts"
+  },
+  "keywords": [
+    "cli",
+    "shell",
+    "history",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubershmekel/caroushell.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ubershmekel/caroushell/issues"
+  },
+  "homepage": "https://github.com/ubershmekel/caroushell#readme",
+  "author": "Ubershmekel",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}