rubber-ducky 1.3.0__tar.gz → 1.4.0__tar.gz

rubber_ducky-1.4.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include crumbs *
+recursive-include examples *

rubber_ducky-1.4.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: rubber-ducky
+Version: 1.4.0
+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
+- Model available via Ollama (default: `qwen3-coder:480b-cloud`, install with `ollama pull qwen3-coder:480b-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 gemma2:9b default
+ducky --poll log-crumb     # start polling mode for a crumb
+```
+
+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 available crumbs (default and user-created)
+- **`/clear`** or **`/reset`** - Clear conversation history
+- **`/poll <crumb>`** - Start polling session for a crumb
+- **`/poll <crumb> -i <interval>`** - Start polling with custom interval
+- **`/poll <crumb> -p <prompt>`** - Start polling with custom prompt
+- **`/stop-poll`** - Stop current polling session
+- **`/run`** or **`:run`** - Re-run the last suggested command
+
+## Crumbs
+
+Crumbs are simple scripts that can be executed within Rubber Ducky. They are stored in `~/.ducky/crumbs/` (for user crumbs) and shipped with the package (default crumbs).
+
+Rubber Ducky ships with the following default crumbs:
+
+| Crumb | Description |
+|-------|-------------|
+| `git-status` | Show current git status and provide suggestions |
+| `git-log` | Show recent commit history with detailed information |
+| `recent-files` | Show recently modified files in current directory |
+| `disk-usage` | Show disk usage with highlights |
+| `system-health` | Show CPU, memory, and system load metrics |
+| `process-list` | Show running processes with analysis |
+
+**Tip:** Run `/crumbs` in interactive mode to see all available crumbs with descriptions and polling status.
+
+To use a crumb, simply mention it in your prompt:
+```
+Can you use the git-status crumb to see what needs to be committed?
+```
+
+**Note:** User-defined crumbs (in `~/.ducky/crumbs/`) override default crumbs with the same name.
+
+### Creating Crumbs
+
+To create a new crumb:
+
+1. Create a new directory in `~/.ducky/crumbs/` with your crumb name
+2. Add an `info.txt` file with metadata:
+   ```
+   name: your-crumb-name
+   type: shell
+   description: Brief description of what this crumb does
+   ```
+3. Add your executable script file (e.g., `your-crumb-name.sh`)
+4. Create a symbolic link in `~/.local/bin` to make it available as a command:
+   ```bash
+   ln -s ~/.ducky/crumbs/your-crumb-name/your-crumb-name.sh ~/.local/bin/your-crumb-name
+   ```
+
+### Polling Mode
+
+Crumbs can be configured for background polling, where the crumb script runs at intervals and the AI analyzes the output.
+
+**Enabling Polling in a Crumb:**
+
+Add polling configuration to your crumb's `info.txt`:
+```
+name: log-crumb
+type: shell
+description: Fetch and analyze server logs
+poll: true
+poll_type: interval          # "interval" (run repeatedly) or "continuous" (run once, tail output)
+poll_interval: 5             # seconds between polls
+poll_prompt: Analyze these logs for errors, warnings, or anomalies. Be concise.
+```
+
+**Polling via CLI:**
+
+```bash
+# Start polling with crumb's default configuration
+ducky --poll log-crumb
+
+# Override interval
+ducky --poll log-crumb --interval 10
+
+# Override prompt
+ducky --poll log-crumb --prompt "Extract only error messages"
+```
+
+**Polling via Interactive Mode:**
+
+```bash
+ducky
+>> /poll log-crumb                    # Use crumb defaults
+>> /poll log-crumb -i 10              # Override interval
+>> /poll log-crumb -p "Summarize"     # Override prompt
+>> /stop-poll                         # Stop polling
+```
+
+**Example Crumb with Polling:**
+
+Directory: `~/.ducky/crumbs/server-logs/`
+
+```
+info.txt:
+  name: server-logs
+  type: shell
+  description: Fetch and analyze server logs
+  poll: true
+  poll_type: interval
+  poll_interval: 5
+  poll_prompt: Analyze these logs for errors, warnings, or anomalies. Be concise.
+
+server-logs.sh:
+  #!/bin/bash
+  curl -s http://localhost:8080/logs | tail -50
+```
+
+**Polling Types:**
+
+- **interval**: Run the crumb script at regular intervals (default)
+- **continuous**: Run the crumb once in the background and stream its output, analyzing periodically
+
+**Stopping Polling:**
+
+Press `Ctrl+C` at any time to stop polling. In interactive mode, you can also use `/stop-poll`.
+
+## Documentation
+
+- **Polling Feature Guide**: See [examples/POLLING_USER_GUIDE.md](examples/POLLING_USER_GUIDE.md) for detailed instructions on creating and using polling crumbs
+- **Mock Log Crumb**: See [examples/mock-logs/](examples/mock-logs/) for an example polling crumb
+
+## 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.4.0/README.md

@@ -0,0 +1,194 @@
+# 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
+- Model available via Ollama (default: `qwen3-coder:480b-cloud`, install with `ollama pull qwen3-coder:480b-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 gemma2:9b default
+ducky --poll log-crumb     # start polling mode for a crumb
+```
+
+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 available crumbs (default and user-created)
+- **`/clear`** or **`/reset`** - Clear conversation history
+- **`/poll <crumb>`** - Start polling session for a crumb
+- **`/poll <crumb> -i <interval>`** - Start polling with custom interval
+- **`/poll <crumb> -p <prompt>`** - Start polling with custom prompt
+- **`/stop-poll`** - Stop current polling session
+- **`/run`** or **`:run`** - Re-run the last suggested command
+
+## Crumbs
+
+Crumbs are simple scripts that can be executed within Rubber Ducky. They are stored in `~/.ducky/crumbs/` (for user crumbs) and shipped with the package (default crumbs).
+
+Rubber Ducky ships with the following default crumbs:
+
+| Crumb | Description |
+|-------|-------------|
+| `git-status` | Show current git status and provide suggestions |
+| `git-log` | Show recent commit history with detailed information |
+| `recent-files` | Show recently modified files in current directory |
+| `disk-usage` | Show disk usage with highlights |
+| `system-health` | Show CPU, memory, and system load metrics |
+| `process-list` | Show running processes with analysis |
+
+**Tip:** Run `/crumbs` in interactive mode to see all available crumbs with descriptions and polling status.
+
+To use a crumb, simply mention it in your prompt:
+```
+Can you use the git-status crumb to see what needs to be committed?
+```
+
+**Note:** User-defined crumbs (in `~/.ducky/crumbs/`) override default crumbs with the same name.
+
+### Creating Crumbs
+
+To create a new crumb:
+
+1. Create a new directory in `~/.ducky/crumbs/` with your crumb name
+2. Add an `info.txt` file with metadata:
+   ```
+   name: your-crumb-name
+   type: shell
+   description: Brief description of what this crumb does
+   ```
+3. Add your executable script file (e.g., `your-crumb-name.sh`)
+4. Create a symbolic link in `~/.local/bin` to make it available as a command:
+   ```bash
+   ln -s ~/.ducky/crumbs/your-crumb-name/your-crumb-name.sh ~/.local/bin/your-crumb-name
+   ```
+
+### Polling Mode
+
+Crumbs can be configured for background polling, where the crumb script runs at intervals and the AI analyzes the output.
+
+**Enabling Polling in a Crumb:**
+
+Add polling configuration to your crumb's `info.txt`:
+```
+name: log-crumb
+type: shell
+description: Fetch and analyze server logs
+poll: true
+poll_type: interval          # "interval" (run repeatedly) or "continuous" (run once, tail output)
+poll_interval: 5             # seconds between polls
+poll_prompt: Analyze these logs for errors, warnings, or anomalies. Be concise.
+```
+
+**Polling via CLI:**
+
+```bash
+# Start polling with crumb's default configuration
+ducky --poll log-crumb
+
+# Override interval
+ducky --poll log-crumb --interval 10
+
+# Override prompt
+ducky --poll log-crumb --prompt "Extract only error messages"
+```
+
+**Polling via Interactive Mode:**
+
+```bash
+ducky
+>> /poll log-crumb                    # Use crumb defaults
+>> /poll log-crumb -i 10              # Override interval
+>> /poll log-crumb -p "Summarize"     # Override prompt
+>> /stop-poll                         # Stop polling
+```
+
+**Example Crumb with Polling:**
+
+Directory: `~/.ducky/crumbs/server-logs/`
+
+```
+info.txt:
+  name: server-logs
+  type: shell
+  description: Fetch and analyze server logs
+  poll: true
+  poll_type: interval
+  poll_interval: 5
+  poll_prompt: Analyze these logs for errors, warnings, or anomalies. Be concise.
+
+server-logs.sh:
+  #!/bin/bash
+  curl -s http://localhost:8080/logs | tail -50
+```
+
+**Polling Types:**
+
+- **interval**: Run the crumb script at regular intervals (default)
+- **continuous**: Run the crumb once in the background and stream its output, analyzing periodically
+
+**Stopping Polling:**
+
+Press `Ctrl+C` at any time to stop polling. In interactive mode, you can also use `/stop-poll`.
+
+## Documentation
+
+- **Polling Feature Guide**: See [examples/POLLING_USER_GUIDE.md](examples/POLLING_USER_GUIDE.md) for detailed instructions on creating and using polling crumbs
+- **Mock Log Crumb**: See [examples/mock-logs/](examples/mock-logs/) for an example polling crumb
+
+## 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.4.0/crumbs/disk-usage/disk-usage.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# Show disk usage with highlights
+
+echo "=== Disk Usage Overview ==="
+df -h 2>/dev/null | grep -E "(/|Filesystem)"
+
+echo -e "\n=== Detailed Disk Usage ==="
+du -h -d 2 . 2>/dev/null | sort -hr | head -20
+
+echo -e "\n=== Largest Files in Current Directory ==="
+find . -type f -not -path '*/\.git/*' -not -path '*/node_modules/*' -not -path '*/venv/*' -not -path '*/\__pycache__/*' -exec du -h {} + 2>/dev/null | sort -rh | head -10

rubber_ducky-1.4.0/crumbs/disk-usage/info.txt

@@ -0,0 +1,3 @@
+name: disk-usage
+type: shell
+description: Show disk usage with highlights on full drives

rubber_ducky-1.4.0/crumbs/git-log/git-log.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+# Show recent commit history with details
+
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    echo "Not a git repository."
+    exit 1
+fi
+
+# Default to showing last 10 commits
+COMMIT_COUNT=10
+
+if [ -n "$1" ] && [[ "$1" =~ ^[0-9]+$ ]]; then
+    COMMIT_COUNT=$1
+fi
+
+echo "=== Recent ${COMMIT_COUNT} Commits ==="
+git log --oneline -$COMMIT_COUNT
+
+echo -e "\n=== Detailed View of Last ${COMMIT_COUNT} Commits ==="
+git log -${COMMIT_COUNT} --pretty=format:"%h - %an, %ar : %s" --stat
+
+echo -e "\n=== Author Statistics ==="
+git shortlog -sn --all -${COMMIT_COUNT} 2>/dev/null

rubber_ducky-1.4.0/crumbs/git-log/info.txt

@@ -0,0 +1,3 @@
+name: git-log
+type: shell
+description: Show recent commit history with detailed information

rubber_ducky-1.4.0/crumbs/git-status/git-status.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+# Show comprehensive git status and recent activity
+
+echo "=== Git Status ==="
+git status --short 2>/dev/null || echo "Not a git repository."
+
+echo -e "\n=== Current Branch ==="
+git branch --show-current 2>/dev/null || echo "Not a git repository."
+
+echo -e "\n=== Last 3 Commits ==="
+git log --oneline -3 2>/dev/null || echo "No commits found."
+
+echo -e "\n=== Staged Changes (if any) ==="
+git diff --cached --stat 2>/dev/null
+
+echo -e "\n=== Unstaged Changes (if any) ==="
+git diff --stat 2>/dev/null
+
+echo -e "\n=== Untracked Files (if any) ==="
+git ls-files --others --exclude-standard 2>/dev/null | head -20

rubber_ducky-1.4.0/crumbs/git-status/info.txt

@@ -0,0 +1,3 @@
+name: git-status
+type: shell
+description: Show current git branch, uncommitted changes, and provide suggestions for next steps

rubber_ducky-1.4.0/crumbs/process-list/info.txt

@@ -0,0 +1,3 @@
+name: process-list
+type: shell
+description: Show running processes with key information

rubber_ducky-1.4.0/crumbs/process-list/process-list.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+# Show running processes with useful information
+
+echo "=== Running Processes (Top 20 by CPU) ==="
+ps aux | sort -rk 3,3 | head -21 | awk '{printf "%-8s %-6s %-8s %s\n", $1, $2, $3, $11}' | column -t
+
+echo -e "\n=== Running Processes (Top 20 by Memory) ==="
+ps aux | sort -rk 4,4 | head -21 | awk '{printf "%-8s %-6s %-8s %s\n", $1, $2, $4, $11}' | column -t
+
+echo -e "\n=== Process Counts by User ==="
+ps aux | awk '{print $1}' | sort | uniq -c | sort -rn | head -10
+
+echo -e "\n=== Check for Specific Processes ==="
+for proc in "node" "python" "java" "docker" "npm" "uv"; do
+    count=$(pgrep -c "$proc" 2>/dev/null || echo "0")
+    if [ "$count" -gt 0 ]; then
+        echo "$proc: $count process(es)"
+    fi
+done | sort

rubber_ducky-1.4.0/crumbs/recent-files/info.txt

@@ -0,0 +1,3 @@
+name: recent-files
+type: shell
+description: Show recently modified files in the current directory

rubber_ducky-1.4.0/crumbs/recent-files/recent-files.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# Show recently modified files in current directory
+# Takes optional argument for number of files to show (default 20)
+
+FILE_COUNT=20
+
+if [ -n "$1" ] && [[ "$1" =~ ^[0-9]+$ ]]; then
+    FILE_COUNT=$1
+fi
+
+echo "=== ${FILE_COUNT} Most Recently Modified Files ==="
+find . -type f -not -path '*/\.*' -not -path '*/node_modules/*' -not -path '*/\.git/*' -not -path '*/venv/*' -not -path '*/\__pycache__/*' -printf '%T@ %p\n' 2>/dev/null | sort -rn | head -${FILE_COUNT} | awk '{print strftime("%Y-%m-%d %H:%M:%S", $1), $2}'

rubber_ducky-1.4.0/crumbs/system-health/info.txt

@@ -0,0 +1,3 @@
+name: system-health
+type: shell
+description: Show system health metrics including CPU, memory, and load

rubber_ducky-1.4.0/crumbs/system-health/system-health.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+
+# Show system health metrics
+# Works on macOS and Linux
+
+detect_os() {
+    if [[ "$OSTYPE" == "darwin"* ]]; then
+        echo "macos"
+    elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
+        echo "linux"
+    else
+        echo "unknown"
+    fi
+}
+
+OS=$(detect_os)
+
+echo "=== System Health ==="
+echo "Platform: $OS"
+echo "Uptime: $(uptime)" | awk '{print $3, $4}'
+echo "Users logged in: $(who | wc -l | tr -d ' ')"
+
+echo -e "\n=== CPU Usage ==="
+
+if [ "$OS" == "macos" ]; then
+    echo "Load averages (1m, 5m, 15m): $(sysctl -n vm.loadavg)"
+    top -l 1 | grep "CPU usage"
+elif [ "$OS" == "linux" ]; then
+    echo "Load averages (1m, 5m, 15m): $(uptime | awk -F'load average:' '{print $2}')"
+    top -bn1 | grep "Cpu(s)"
+fi
+
+echo -e "\n=== Memory Usage ==="
+
+if [ "$OS" == "macos" ]; then
+    # macOS memory
+    echo "Memory Stats:"
+    vm_stat | perl -ne '/page size of (\d+)/ and $ps=$1; /Pages\s+([^:]+)[^\d]+(\d+)/ and printf("%-16s % 16.2f MB\n", "$1:", $2 * $ps / 1048576);'
+elif [ "$OS" == "linux" ]; then
+    free -h
+fi
+
+echo -e "\n=== Disk Space ==="
+df -h | grep -vE '^Filesystem|tmpfs|cdrom|devtmpfs'
+
+echo -e "\n=== Network Connections ==="
+
+if [ "$OS" == "macos" ]; then
+    netstat -an | grep ESTABLISHED | wc -l | xargs echo "Active network connections:"
+elif [ "$OS" == "linux" ]; then
+    ss -tun | grep ESTAB | wc -l | xargs echo "Active network connections:"
+fi
+
+echo -e "\n=== Top 5 Processes by CPU ==="
+ps aux | sort -rk 3,3 | head -11 | tail -10 | awk '{printf "%-10s %6s %s\n", $1, $3, $11}'
+
+echo -e "\n=== Top 5 Processes by Memory ==="
+ps aux | sort -rk 4,4 | head -11 | tail -10 | awk '{printf "%-10s %6s %s\n", $1, $4, $11}'