rubber-ducky 1.5.0__tar.gz → 1.5.2__tar.gz

rubber_ducky-1.5.2/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: rubber-ducky
+Version: 1.5.2
+Summary: Quick CLI do-it-all tool. Use natural language to spit out bash commands
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: fastapi>=0.115.11
+Requires-Dist: ollama>=0.6.0
+Requires-Dist: openai>=1.60.2
+Requires-Dist: prompt-toolkit>=3.0.48
+Requires-Dist: rich>=13.9.4
+Requires-Dist: termcolor>=2.5.0
+Dynamic: license-file
+
+# Rubber Ducky
+
+Rubber Ducky is an inline terminal companion that turns natural language prompts into runnable shell commands. Paste multi-line context, get a suggested command, and run it without leaving your terminal.
+
+## Quick Start
+
+| Action | Command |
+| --- | --- |
+| Install globally | `uv tool install rubber-ducky` |
+| Run once | `uvx rubber-ducky -- --help` |
+| Local install | `uv pip install rubber-ducky` |
+
+Requirements:
+- [Ollama](https://ollama.com) running locally or use cloud models
+- Model available via Ollama (default: `glm-4.7:cloud`)
+
+## Usage
+
+```
+ducky                      # interactive inline session
+ducky --directory src      # preload code from a directory
+ducky --model qwen3        # use a different Ollama model
+ducky --local              # use local models with qwen3 default
+```
+
+Both `ducky` and `rubber-ducky` executables map to the same CLI, so `uvx rubber-ducky -- <args>` works as well.
+
+### Inline Session (default)
+
+Launching `ducky` with no arguments opens the inline interface:
+- **Enter** submits; **Ctrl+J** inserts a newline (helpful when crafting multi-line prompts). Hitting **Enter on an empty prompt** reruns the latest suggested command; if none exists yet, it explains the most recent shell output.
+- **Ctrl+R** re-runs the last suggested command.
+- **Ctrl+S** copies the last suggested command to clipboard.
+- Prefix any line with **`!`** (e.g., `!ls -la`) to run a shell command immediately.
+- Arrow keys browse prompt history, backed by `~/.ducky/prompt_history`.
+- Every prompt, assistant response, and executed command is logged to `~/.ducky/conversation.log`.
+- Press **Ctrl+D** on an empty line to exit.
+- Non-interactive runs such as `cat prompt.txt | ducky` print one response (and suggested command) before exiting; if a TTY is available you'll be asked whether to run the suggested command immediately.
+- If `prompt_toolkit` is unavailable in your environment, Rubber Ducky falls back to a basic input loop (no history or shortcuts); install `prompt-toolkit>=3.0.48` to unlock the richer UI.
+
+`ducky --directory <path>` streams the contents of the provided directory to the assistant the next time you submit a prompt (the directory is read once at startup).
+
+### Model Management
+
+Rubber Ducky now supports easy switching between local and cloud models:
+- **`/model`** - Interactive model selection between local and cloud models
+- **`/local`** - List and select from local models (localhost:11434)
+- **`/cloud`** - List and select from cloud models (ollama.com)
+- Last used model is automatically saved and loaded on startup
+- Type **`esc`** during model selection to cancel
+
+### Additional Commands
+
+- **`/help`** - Show all available commands and shortcuts
+- **`/crumbs`** - List all saved crumb shortcuts
+- **`/crumb <name>`** - Save the last AI-suggested command as a named crumb
+- **`/crumb add <name> <command>`** - Manually add a crumb with a specific command
+- **`/crumb del <name>`** - Delete a saved crumb
+- **`<crumb-name>`** - Invoke a saved crumb (displays info and executes the command)
+- **`/clear`** or **`/reset`** - Clear conversation history
+- **`/run`** or **`:run`** - Re-run the last suggested command
+
+## Crumbs
+
+Crumbs are saved command shortcuts that let you quickly reuse AI-generated bash commands without regenerating them each time. Perfect for frequently-used workflows or complex commands.
+
+### Saving Crumbs
+
+When the AI suggests a command that you want to reuse:
+
+1. Get a command suggestion from ducky
+2. Save it immediately: `/crumb <name>`
+3. Example:
+   ```
+   >> How do I list all Ollama processes?
+   ...
+   Suggested command: ps aux | grep -i ollama | grep -v grep
+   >> /crumb ols
+   Saved crumb 'ols'!
+   Generating explanation...
+   Explanation added: Finds and lists all running Ollama processes.
+   ```
+
+The crumb is saved with:
+- The original command
+- An AI-generated one-line explanation
+- A timestamp
+
+### Invoking Crumbs
+
+Simply type the crumb name in the REPL or use it as a CLI argument:
+
+**In REPL:**
+```
+>> ols
+
+Crumb: ols
+Explanation: Finds and lists all running Ollama processes.
+Command: ps aux | grep -i ollama | grep -v grep
+
+$ ps aux | grep -i ollama | grep -v grep
+user123  12345  0.3  1.2  456789  98765 ?  Sl  10:00   0:05 ollama serve
+```
+
+**From CLI:**
+```bash
+ducky ols              # Runs the saved crumb and displays output
+```
+
+When you invoke a crumb:
+1. It displays the crumb name, explanation, and command
+2. Automatically executes the command
+3. Shows the output
+
+### Managing Crumbs
+
+**List all crumbs:**
+```bash
+>> /crumbs
+```
+
+Output:
+```
+Saved Crumbs
+=============
+ols      | Finds and lists all running Ollama processes. | ps aux | grep -i ollama | grep -v grep
+test     | Run tests and build project                  | pytest && python build.py
+deploy   | Deploy to production                         | docker push app:latest
+```
+
+**Manually add a crumb:**
+```bash
+>> /crumb add deploy-prod docker build -t app:latest && docker push app:latest
+```
+
+**Delete a crumb:**
+```bash
+>> /crumb ols
+Deleted crumb 'ols'.
+```
+
+### Storage
+
+Crumbs are stored in `~/.ducky/crumbs.json` as JSON. Each crumb includes:
+- `prompt`: Original user prompt
+- `response`: AI's full response
+- `command`: The suggested bash command
+- `explanation`: AI-generated one-line summary
+- `created_at`: ISO timestamp
+
+**Example:**
+```json
+{
+  "ols": {
+    "prompt": "How do I list all Ollama processes?",
+    "response": "To list all running Ollama processes...",
+    "command": "ps aux | grep -i ollama | grep -v grep",
+    "explanation": "Finds and lists all running Ollama processes.",
+    "created_at": "2024-01-05T10:30:00.000000+00:00"
+  }
+}
+```
+
+Delete `~/.ducky/crumbs.json` to clear all saved crumbs.
+
+## Development (uv)
+
+```
+uv sync
+uv run ducky --help
+```
+
+`uv sync` creates a virtual environment and installs dependencies defined in `pyproject.toml` / `uv.lock`.
+
+## Telemetry & Storage
+
+Rubber Ducky stores:
+- `~/.ducky/prompt_history`: readline-compatible history file.
+- `~/.ducky/conversation.log`: JSON lines with timestamps for prompts, assistant messages, and shell executions.
+- `~/.ducky/config`: User preferences including last selected model.
+
+No other telemetry is collected; delete the directory if you want a fresh slate.

rubber_ducky-1.5.2/README.md

@@ -0,0 +1,182 @@
+# Rubber Ducky
+
+Rubber Ducky is an inline terminal companion that turns natural language prompts into runnable shell commands. Paste multi-line context, get a suggested command, and run it without leaving your terminal.
+
+## Quick Start
+
+| Action | Command |
+| --- | --- |
+| Install globally | `uv tool install rubber-ducky` |
+| Run once | `uvx rubber-ducky -- --help` |
+| Local install | `uv pip install rubber-ducky` |
+
+Requirements:
+- [Ollama](https://ollama.com) running locally or use cloud models
+- Model available via Ollama (default: `glm-4.7:cloud`)
+
+## Usage
+
+```
+ducky                      # interactive inline session
+ducky --directory src      # preload code from a directory
+ducky --model qwen3        # use a different Ollama model
+ducky --local              # use local models with qwen3 default
+```
+
+Both `ducky` and `rubber-ducky` executables map to the same CLI, so `uvx rubber-ducky -- <args>` works as well.
+
+### Inline Session (default)
+
+Launching `ducky` with no arguments opens the inline interface:
+- **Enter** submits; **Ctrl+J** inserts a newline (helpful when crafting multi-line prompts). Hitting **Enter on an empty prompt** reruns the latest suggested command; if none exists yet, it explains the most recent shell output.
+- **Ctrl+R** re-runs the last suggested command.
+- **Ctrl+S** copies the last suggested command to clipboard.
+- Prefix any line with **`!`** (e.g., `!ls -la`) to run a shell command immediately.
+- Arrow keys browse prompt history, backed by `~/.ducky/prompt_history`.
+- Every prompt, assistant response, and executed command is logged to `~/.ducky/conversation.log`.
+- Press **Ctrl+D** on an empty line to exit.
+- Non-interactive runs such as `cat prompt.txt | ducky` print one response (and suggested command) before exiting; if a TTY is available you'll be asked whether to run the suggested command immediately.
+- If `prompt_toolkit` is unavailable in your environment, Rubber Ducky falls back to a basic input loop (no history or shortcuts); install `prompt-toolkit>=3.0.48` to unlock the richer UI.
+
+`ducky --directory <path>` streams the contents of the provided directory to the assistant the next time you submit a prompt (the directory is read once at startup).
+
+### Model Management
+
+Rubber Ducky now supports easy switching between local and cloud models:
+- **`/model`** - Interactive model selection between local and cloud models
+- **`/local`** - List and select from local models (localhost:11434)
+- **`/cloud`** - List and select from cloud models (ollama.com)
+- Last used model is automatically saved and loaded on startup
+- Type **`esc`** during model selection to cancel
+
+### Additional Commands
+
+- **`/help`** - Show all available commands and shortcuts
+- **`/crumbs`** - List all saved crumb shortcuts
+- **`/crumb <name>`** - Save the last AI-suggested command as a named crumb
+- **`/crumb add <name> <command>`** - Manually add a crumb with a specific command
+- **`/crumb del <name>`** - Delete a saved crumb
+- **`<crumb-name>`** - Invoke a saved crumb (displays info and executes the command)
+- **`/clear`** or **`/reset`** - Clear conversation history
+- **`/run`** or **`:run`** - Re-run the last suggested command
+
+## Crumbs
+
+Crumbs are saved command shortcuts that let you quickly reuse AI-generated bash commands without regenerating them each time. Perfect for frequently-used workflows or complex commands.
+
+### Saving Crumbs
+
+When the AI suggests a command that you want to reuse:
+
+1. Get a command suggestion from ducky
+2. Save it immediately: `/crumb <name>`
+3. Example:
+   ```
+   >> How do I list all Ollama processes?
+   ...
+   Suggested command: ps aux | grep -i ollama | grep -v grep
+   >> /crumb ols
+   Saved crumb 'ols'!
+   Generating explanation...
+   Explanation added: Finds and lists all running Ollama processes.
+   ```
+
+The crumb is saved with:
+- The original command
+- An AI-generated one-line explanation
+- A timestamp
+
+### Invoking Crumbs
+
+Simply type the crumb name in the REPL or use it as a CLI argument:
+
+**In REPL:**
+```
+>> ols
+
+Crumb: ols
+Explanation: Finds and lists all running Ollama processes.
+Command: ps aux | grep -i ollama | grep -v grep
+
+$ ps aux | grep -i ollama | grep -v grep
+user123  12345  0.3  1.2  456789  98765 ?  Sl  10:00   0:05 ollama serve
+```
+
+**From CLI:**
+```bash
+ducky ols              # Runs the saved crumb and displays output
+```
+
+When you invoke a crumb:
+1. It displays the crumb name, explanation, and command
+2. Automatically executes the command
+3. Shows the output
+
+### Managing Crumbs
+
+**List all crumbs:**
+```bash
+>> /crumbs
+```
+
+Output:
+```
+Saved Crumbs
+=============
+ols      | Finds and lists all running Ollama processes. | ps aux | grep -i ollama | grep -v grep
+test     | Run tests and build project                  | pytest && python build.py
+deploy   | Deploy to production                         | docker push app:latest
+```
+
+**Manually add a crumb:**
+```bash
+>> /crumb add deploy-prod docker build -t app:latest && docker push app:latest
+```
+
+**Delete a crumb:**
+```bash
+>> /crumb ols
+Deleted crumb 'ols'.
+```
+
+### Storage
+
+Crumbs are stored in `~/.ducky/crumbs.json` as JSON. Each crumb includes:
+- `prompt`: Original user prompt
+- `response`: AI's full response
+- `command`: The suggested bash command
+- `explanation`: AI-generated one-line summary
+- `created_at`: ISO timestamp
+
+**Example:**
+```json
+{
+  "ols": {
+    "prompt": "How do I list all Ollama processes?",
+    "response": "To list all running Ollama processes...",
+    "command": "ps aux | grep -i ollama | grep -v grep",
+    "explanation": "Finds and lists all running Ollama processes.",
+    "created_at": "2024-01-05T10:30:00.000000+00:00"
+  }
+}
+```
+
+Delete `~/.ducky/crumbs.json` to clear all saved crumbs.
+
+## Development (uv)
+
+```
+uv sync
+uv run ducky --help
+```
+
+`uv sync` creates a virtual environment and installs dependencies defined in `pyproject.toml` / `uv.lock`.
+
+## Telemetry & Storage
+
+Rubber Ducky stores:
+- `~/.ducky/prompt_history`: readline-compatible history file.
+- `~/.ducky/conversation.log`: JSON lines with timestamps for prompts, assistant messages, and shell executions.
+- `~/.ducky/config`: User preferences including last selected model.
+
+No other telemetry is collected; delete the directory if you want a fresh slate.

rubber_ducky-1.5.2/ducky/crumb.py

@@ -0,0 +1,84 @@
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+
+class CrumbManager:
+    """Manages crumb storage for command shortcuts."""
+
+    def __init__(self, config_dir: Optional[Path] = None):
+        if config_dir is None:
+            config_dir = Path.home() / ".ducky"
+        self.config_dir = config_dir
+        self.crumbs_file = self.config_dir / "crumbs.json"
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+    def load_crumbs(self) -> Dict[str, Any]:
+        """Load crumbs from JSON file, returning empty dict if not found."""
+        if not self.crumbs_file.exists():
+            return {}
+
+        try:
+            with open(self.crumbs_file, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {}
+
+    def save_crumbs(self, crumbs: Dict[str, Any]) -> None:
+        """Save crumbs to JSON file."""
+        try:
+            with open(self.crumbs_file, "w") as f:
+                json.dump(crumbs, f, indent=2)
+        except IOError as e:
+            print(f"Warning: Could not save crumbs: {e}")
+
+    def save_crumb(
+        self,
+        name: str,
+        prompt: str,
+        response: str,
+        command: str,
+    ) -> None:
+        """Add or update a crumb."""
+        crumbs = self.load_crumbs()
+        crumbs[name] = {
+            "prompt": prompt,
+            "response": response,
+            "command": command,
+            "explanation": "",
+            "created_at": datetime.now(UTC).isoformat(),
+        }
+        self.save_crumbs(crumbs)
+
+    def get_crumb(self, name: str) -> Optional[Dict[str, Any]]:
+        """Retrieve a crumb by name."""
+        crumbs = self.load_crumbs()
+        return crumbs.get(name)
+
+    def list_crumbs(self) -> Dict[str, Any]:
+        """Return all crumbs."""
+        return self.load_crumbs()
+
+    def delete_crumb(self, name: str) -> bool:
+        """Remove a crumb. Returns True if deleted, False if not found."""
+        crumbs = self.load_crumbs()
+        if name in crumbs:
+            del crumbs[name]
+            self.save_crumbs(crumbs)
+            return True
+        return False
+
+    def update_explanation(self, name: str, explanation: str) -> bool:
+        """Update explanation for a crumb. Returns True if updated, False if not found."""
+        crumbs = self.load_crumbs()
+        if name in crumbs:
+            crumbs[name]["explanation"] = explanation
+            self.save_crumbs(crumbs)
+            return True
+        return False
+
+    def has_crumb(self, name: str) -> bool:
+        """Check if a crumb exists."""
+        crumbs = self.load_crumbs()
+        return name in crumbs