caroushell 0.1.13 → 0.1.15

package/README.md

@@ -1,11 +1,14 @@
 # Caroushell
 
+[![npm version](https://img.shields.io/npm/v/caroushell.svg)](https://www.npmjs.com/package/caroushell)
+[![npm downloads](https://img.shields.io/npm/dm/caroushell.svg)](https://www.npmjs.com/package/caroushell)
+
 Caroushell is an interactive terminal carousel that suggests commands from your
 history, and AI suggestions as you type.
 
 ## Features
 
-- The top panel of the carousel shows history
+- The top panel of the carousel shows history.
 - The bottom panel of the carousel shows AI-generated command suggestions.
 - Go up and down the carousel with arrow keys.
 - Press `Enter` to run the highlighted command.
@@ -13,6 +16,32 @@ history, and AI suggestions as you type.
 - Extensible config file (`~/.caroushell/config.toml`) so you can point the CLI
   at different AI providers.
 
+## UI
+
+The UI layout looks like this:
+
+```
+⌛history2
+⌛history1
+$> YOU TYPE YOUR SHELL COMMANDS HERE
+🤖ai suggestion1
+🤖ai suggestion2
+```
+
+Here's an example using a comment to get AI autocompletion for ffmpeg:
+
+```
+⌛echo 123
+⌛cd
+$> ffmpeg -i myvideo.mp4 # slowmo 50%
+🤖ffmpeg -i myvideo.mp4 -filter:v "setpts=2.0*PTS" output_slow.mp4
+🤖ffmpeg -i myvideo.mp4 -vf "setpts=0.5*PTS" output_fast.mp4
+```
+
+It would look like this:
+
+![Caroushell ai suggestion for ffmpeg slowmo](docs/assets/demo.gif)
+
 ## Requirements
 
 - Node.js 18 or newer.
@@ -46,7 +75,7 @@ npm install -g caroushell
 caroushell
 ```
 
-Or run it ad-hoc with NPX once it is published:
+Or run it with NPX:
 
 ```bash
 npx caroushell
@@ -61,6 +90,8 @@ Caroushell opens an interactive prompt:
 - 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.
+- Press `Tab` to autocomplete a file suggestion or browse files and folders with
+  the arrow keys.
 
 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
@@ -69,9 +100,8 @@ need to debug AI suggestions or the terminal renderer. Configuration lives at
 ## Development
 
 ```bash
-npm install
-npm run dev
-npm run build
+npm install            # install dependencies
+npm run dev            # run the shell
 npm run test:generate  # tests ai text generation
 npm publish --dry-run  # verify package contents before publishing
 ```

package/dist/ai-suggester.js

@@ -5,6 +5,27 @@ exports.generateContent = generateContent;
 exports.listModels = listModels;
 const logs_1 = require("./logs");
 const config_1 = require("./config");
+function debounceAsync(fn, delayMs) {
+    let tim = null;
+    let rejectLast = null;
+    return (...args) => {
+        if (tim)
+            clearTimeout(tim);
+        return new Promise((resolve, reject) => {
+            if (rejectLast) {
+                rejectLast(new Error("debounced"));
+            }
+            rejectLast = reject;
+            tim = setTimeout(() => {
+                tim = null;
+                rejectLast = null;
+                fn(...args)
+                    .then(resolve)
+                    .catch(reject);
+            }, delayMs);
+        });
+    };
+}
 async function generateContent(prompt, options) {
     const apiKey = options?.apiKey ||
         process.env.CAROUSHELL_API_KEY ||
@@ -100,6 +121,8 @@ async function extractText(json) {
 class AISuggester {
     constructor(opts) {
         this.prefix = "🤖";
+        this.latestSuggestions = [];
+        this.debouncedSuggest = debounceAsync(this.runSuggestNow.bind(this), 350);
         this.apiKey = opts?.apiKey;
         this.apiUrl = opts?.apiUrl;
         this.model = opts?.model;
@@ -118,11 +141,29 @@ class AISuggester {
     descriptionForAi() {
         return "";
     }
-    async suggest(carousel, maxDisplayed) {
+    latest() {
+        return this.latestSuggestions;
+    }
+    async refreshSuggestions(carousel, maxDisplayed) {
         if (!this.apiKey || !this.apiUrl || !this.model) {
             (0, logs_1.logLine)("AI generation skipped: missing API configuration");
-            return [];
+            this.latestSuggestions = [];
+            carousel.render();
+            return;
         }
+        try {
+            const suggestions = await this.debouncedSuggest(carousel, maxDisplayed);
+            this.latestSuggestions = suggestions.slice(0, maxDisplayed);
+        }
+        catch (err) {
+            if (err?.message !== "debounced") {
+                (0, logs_1.logLine)("ai suggest error: " + err?.message);
+            }
+            this.latestSuggestions = [];
+        }
+        carousel.render();
+    }
+    async runSuggestNow(carousel, maxDisplayed) {
         const descriptions = [];
         for (const suggester of carousel.getSuggesters()) {
             const desc = suggester.descriptionForAi();

package/dist/app.js

@@ -8,15 +8,6 @@ const history_suggester_1 = require("./history-suggester");
 const ai_suggester_1 = require("./ai-suggester");
 const file_suggester_1 = require("./file-suggester");
 const spawner_1 = require("./spawner");
-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.usingFileSuggestions = false;
@@ -32,9 +23,9 @@ class App {
             bottomRows: 2,
             terminal: this.terminal,
         });
-        this.queueUpdateSuggestions = debounce(async () => {
-            await this.carousel.updateSuggestions();
-        }, 300);
+        this.queueUpdateSuggestions = () => {
+            void this.carousel.updateSuggestions();
+        };
         this.handlers = {
             "ctrl-c": () => {
                 if (this.carousel.isPromptRowSelected() && !this.carousel.hasInput()) {

package/dist/carousel.js

@@ -5,61 +5,49 @@ 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.emptyRow = "---";
         this.terminal = opts.terminal;
         this.top = opts.top;
         this.bottom = opts.bottom;
         this.topRowCount = opts.topRows;
         this.bottomRowCount = opts.bottomRows;
-        this.latestTop = this.createEmptyRows(this.topRowCount);
-        this.latestBottom = this.createEmptyRows(this.bottomRowCount);
-    }
-    createEmptyRows(count) {
-        return Array(count).fill(this.emptyRow);
     }
     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);
-        void topPromise.then((r) => {
-            this.latestTop = r;
-            this.render();
-        });
-        void bottomPromise.then((r) => {
-            this.latestBottom = r;
-            this.render();
-        });
+        void this.top.refreshSuggestions(this, this.topRowCount);
+        void this.bottom.refreshSuggestions(this, this.bottomRowCount);
     }
     up() {
         this.index += 1;
-        if (this.index >= this.latestTop.length) {
-            this.index = this.latestTop.length;
+        const topLength = this.top.latest().length;
+        if (this.index >= topLength) {
+            this.index = topLength;
         }
     }
     down() {
         this.index -= 1;
-        if (-this.index >= this.latestBottom.length) {
-            this.index = -this.latestBottom.length;
+        const bottomLength = this.bottom.latest().length;
+        if (-this.index >= bottomLength) {
+            this.index = -bottomLength;
         }
     }
     getRow(rowIndex) {
+        const latestTop = this.top.latest();
+        const latestBottom = this.bottom.latest();
         if (rowIndex < 0) {
             const bottomIndex = -rowIndex - 1;
-            return this.latestBottom[bottomIndex] || "";
+            return latestBottom[bottomIndex] || "";
         }
         if (rowIndex === 0) {
             return this.inputBuffer;
         }
         if (rowIndex > 0) {
             const topIndex = rowIndex - 1;
-            return this.latestTop[topIndex] || "";
+            return latestTop[topIndex] || "";
         }
         return "";
     }
@@ -259,7 +247,10 @@ class Carousel {
         if (this.top === suggester)
             return;
         this.top = suggester;
-        this.latestTop = this.createEmptyRows(this.topRowCount);
+        if (this.index > 0) {
+            const topLength = this.top.latest().length;
+            this.index = Math.min(this.index, topLength);
+        }
     }
     getSuggesters() {
         return [this.top, this.bottom];

package/dist/file-suggester.js

@@ -12,6 +12,7 @@ class FileSuggester {
     constructor() {
         this.prefix = "📂";
         this.files = [];
+        this.latestSuggestions = [];
     }
     async init() {
         await this.refreshFiles();
@@ -75,10 +76,13 @@ class FileSuggester {
         const converted = dirDisplay.replace(/\//g, path_1.default.sep);
         return path_1.default.resolve(process.cwd(), converted);
     }
-    async suggest(carousel, maxDisplayed) {
+    latest() {
+        return this.latestSuggestions;
+    }
+    async refreshSuggestions(carousel, maxDisplayed) {
         const { prefix } = carousel.getWordInfoAtCursor();
-        const matches = await this.getMatchingFiles(prefix);
-        return matches;
+        this.latestSuggestions = await this.getMatchingFiles(prefix);
+        carousel.render();
     }
     async findUniqueMatch(prefix) {
         const normalized = prefix.trim();

package/dist/hello-new-user.js

@@ -41,6 +41,7 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const readline_1 = __importDefault(require("readline"));
 const ai_suggester_1 = require("./ai-suggester");
+const preferredModels = ["gemini-2.5-flash-lite", "gpt-4o-mini"];
 function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
@@ -49,6 +50,17 @@ async function prompt(question, rl) {
         rl.question(question, (answer) => resolve(answer));
     });
 }
+function findShortestMatches(models, preferredList) {
+    const matches = [];
+    for (const pref of preferredList) {
+        const hits = models.filter((modelId) => modelId.includes(pref));
+        if (hits.length) {
+            const shortest = hits.reduce((best, candidate) => candidate.length < best.length ? candidate : best);
+            matches.push(shortest);
+        }
+    }
+    return [...new Set(matches)];
+}
 async function runHelloNewUserFlow(configPath) {
     if (!isInteractive()) {
         throw new Error(`Missing config at ${configPath} and no interactive terminal is available.\n` +
@@ -92,10 +104,17 @@ async function runHelloNewUserFlow(configPath) {
     }
     const models = await (0, ai_suggester_1.listModels)(apiUrl, apiKey);
     if (models.length > 0) {
+        const preferred = findShortestMatches(models, preferredModels);
         console.log("Here are a few example model ids from your api service. Choose a fast and cheap model because AI suggestions happen as you type.");
         for (const model of models.slice(0, 5)) {
             console.log(`  - ${model}`);
         }
+        if (preferred.length) {
+            console.log("Recommended models from your provider:");
+            for (const model of preferred) {
+                console.log(`  - ${model}`);
+            }
+        }
     }
     let model = "";
     while (!model) {

package/dist/history-suggester.js

@@ -44,24 +44,31 @@ class HistorySuggester {
             .catch(() => { });
         await fs_1.promises.appendFile(this.filePath, this.serializeHistoryEntry(command), "utf8");
     }
-    async suggest(carousel, maxDisplayed) {
+    latest() {
+        return this.items;
+    }
+    async refreshSuggestions(carousel, maxDisplayed) {
         const input = carousel.getCurrentRow();
+        let results;
         if (!input) {
             // this.items 0 index is newest
-            return this.items;
+            results = this.items;
         }
-        const q = input.toLowerCase();
-        const matched = [];
-        // iterate from newest to oldest so we skip older duplicates
-        const seen = new Set();
-        for (let i = 0; i < this.items.length; i++) {
-            const it = this.items[i];
-            if (it.toLowerCase().includes(q) && !seen.has(it)) {
-                seen.add(it);
-                matched.push(it);
+        else {
+            const q = input.toLowerCase();
+            const matched = [];
+            // iterate from newest to oldest so we skip older duplicates
+            const seen = new Set();
+            for (let i = 0; i < this.items.length; i++) {
+                const it = this.items[i];
+                if (it.toLowerCase().includes(q) && !seen.has(it)) {
+                    seen.add(it);
+                    matched.push(it);
+                }
             }
+            results = matched;
         }
-        return matched;
+        carousel.render();
     }
     descriptionForAi() {
         const lines = [];

package/dist/spawner.js

@@ -54,8 +54,11 @@ async function runUserCommand(command) {
     if (typeof args[0] === "string" && builtInCommands[args[0]]) {
         return await builtInCommands[args[0]](args);
     }
+    // "shell: true" to prevent the bug of `echo "asdf"` outputting
+    // \"Asdf\" instead of "Asdf"
     const proc = (0, child_process_1.spawn)(shellBinary, [...shellArgs, command], {
         stdio: "inherit",
+        shell: true,
     });
     await new Promise((resolve, reject) => {
         proc.on("error", reject);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caroushell",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Terminal carousel that suggests commands from history, config, and AI.",
   "type": "commonjs",
   "main": "dist/main.js",