alfrusco

A powerful, ergonomic Rust library for building Alfred workflows with ease. Alfrusco handles the complexity of Alfred's JSON protocol, provides rich item building capabilities, and includes advanced features like background jobs, clipboard operations, and comprehensive logging.

Features

Simple & Ergonomic API - Intuitive builder patterns for creating Alfred items
Async Support - Full async/await support for modern Rust applications
Background Jobs - Run long-running tasks without blocking Alfred's UI
Clipboard Integration - Built-in support for rich text and Markdown clipboard operations
Smart Filtering - Automatic fuzzy search and sorting of results
Workflow Management - Easy access to workflow directories and configuration
Comprehensive Logging - Structured logging with file and console output
URL Items - Specialized support for URL-based workflow items
Environment Handling - Robust configuration management for Alfred environments
Testing Support - Built-in testing utilities and mocking capabilities

📦 Installation

Add alfrusco to your Cargo.toml:

[dependencies]
alfrusco = "0.2"

# For async workflows
tokio = { version = "1", features = ["full"] }

# For command-line argument parsing (recommended)
clap = { version = "4", features = ["derive", "env"] }

🚀 Quick Start

Basic Synchronous Workflow

use alfrusco::{execute, Item, Runnable, Workflow};
use alfrusco::config::AlfredEnvProvider;
use clap::Parser;

#[derive(Parser)]
struct MyWorkflow {
    query: Vec<String>,
}

impl Runnable for MyWorkflow {
    type Error = alfrusco::Error;

    fn run(self, workflow: &mut Workflow) -> Result<(), Self::Error> {
        let query = self.query.join(" ");

        workflow.append_item(
            Item::new(format!("Hello, {}!", query))
                .subtitle("This is a basic Alfred workflow")
                .arg(&query)
                .valid(true)
        );

        Ok(())
    }
}

fn main() {
    // Initialize logging (optional but recommended)
    let _ = alfrusco::init_logging(&AlfredEnvProvider);

    // Parse command line arguments and execute workflow
    let command = MyWorkflow::parse();
    execute(&AlfredEnvProvider, command, &mut std::io::stdout());
}

Async Workflow with HTTP Requests

use alfrusco::{execute_async, AsyncRunnable, Item, Workflow, WorkflowError};
use alfrusco::config::AlfredEnvProvider;
use clap::Parser;
use serde::Deserialize;

#[derive(Parser)]
struct ApiWorkflow {
    query: Vec<String>,
}

#[derive(Deserialize)]
struct ApiResponse {
    results: Vec<ApiResult>,
}

#[derive(Deserialize)]
struct ApiResult {
    title: String,
    description: String,
    url: String,
}

#[async_trait::async_trait]
impl AsyncRunnable for ApiWorkflow {
    type Error = Box<dyn WorkflowError>;

    async fn run_async(self, workflow: &mut Workflow) -> Result<(), Self::Error> {
        let query = self.query.join(" ");
        workflow.set_filter_keyword(query.clone());

        let url = format!("https://api.example.com/search?q={}", query);
        let response: ApiResponse = reqwest::get(&url)
            .await?
            .json()
            .await?;

        let items: Vec<Item> = response.results
            .into_iter()
            .map(|result| {
                Item::new(&result.title)
                    .subtitle(&result.description)
                    .arg(&result.url)
                    .quicklook_url(&result.url)
                    .valid(true)
            })
            .collect();

        workflow.append_items(items);
        Ok(())
    }
}

#[tokio::main]
async fn main() {
    let _ = alfrusco::init_logging(&AlfredEnvProvider);
    let command = ApiWorkflow::parse();
    execute_async(&AlfredEnvProvider, command, &mut std::io::stdout()).await;
}

🏗️ Core Concepts

Items

Items are the building blocks of Alfred workflows. Each item represents a choice in the Alfred selection UI:

use alfrusco::Item;

let item = Item::new("My Title")
.subtitle("Additional information")
.arg("argument-passed-to-action")
.uid("unique-identifier")
.valid(true)
.icon_from_image("/path/to/icon.png")
.copy_text("Text copied with ⌘C")
.large_type_text("Text shown in large type with ⌘L")
.quicklook_url("https://example.com")
.var("CUSTOM_VAR", "value")
.autocomplete("text for tab completion");

Workflow Configuration

Alfrusco automatically handles Alfred's environment variables through configuration providers:

use alfrusco::config::{AlfredEnvProvider, TestingProvider};

// For production (reads from Alfred environment variables)
let provider = AlfredEnvProvider;

// For testing (uses temporary directories)
let temp_dir = tempfile::tempdir().unwrap();
let provider = TestingProvider(temp_dir.path().to_path_buf());

Error Handling

Implement custom error types that work seamlessly with Alfred:

use alfrusco::{WorkflowError, Item};
use thiserror::Error;

#[derive(Error, Debug)]
pub enum MyWorkflowError {
    #[error("Network request failed: {0}")]
    Network(#[from] reqwest::Error),
    #[error("Invalid input: {0}")]
    InvalidInput(String),
}

impl WorkflowError for MyWorkflowError {}

// Errors automatically become Alfred items
impl Runnable for MyWorkflow {
    type Error = MyWorkflowError;

    fn run(self, workflow: &mut Workflow) -> Result<(), Self::Error> {
        // If this returns an error, Alfred will show it as an item
        Err(MyWorkflowError::InvalidInput("Missing required field".to_string()))
    }
}

🔧 Advanced Features

Background Jobs

Run long-running tasks without blocking Alfred's UI. This example fetches GitHub release data in the background and caches it to disk, showing cached results immediately while refreshing stale data:

use std::process::Command;
use std::time::Duration;

impl Runnable for MyWorkflow {
    type Error = alfrusco::Error;

    fn run(self, workflow: &mut Workflow) -> Result<(), Self::Error> {
        let cache_file = workflow.cache_dir().join("releases.json");

        // Set up a command to fetch data and save to cache
        let mut cmd = Command::new("sh");
        cmd.arg("-c")
            .arg(format!(
                "curl -s https://api.github.com/repos/rust-lang/rust/releases/latest > {}",
                cache_file.display()
            ));

        // Run the command in the background, refresh every 30 seconds
        workflow.run_in_background(
            "github-releases",
            Duration::from_secs(30),
            cmd
        );

        // Check if we have cached data to display
        if cache_file.exists() {
            if let Ok(data) = std::fs::read_to_string(&cache_file) {
                if let Ok(release) = serde_json::from_str::<serde_json::Value>(&data) {
                    if let Some(tag) = release["tag_name"].as_str() {
                        workflow.append_item(
                            Item::new(format!("Latest Rust: {}", tag))
                                .subtitle("Click to view release notes")
                                .arg(release["html_url"].as_str().unwrap_or(""))
                                .valid(true)
                        );
                    }
                }
            }
        }

        // run_in_background automatically shows a status item when the job is stale

        Ok(())
    }
}

Enhanced Background Job Features:

Smart Status Tracking: Jobs show detailed status messages like "Last succeeded 2 minutes ago (14:32:15), running for 3s" or "Last failed 5 minutes ago (14:29:42), running for 1s"
Automatic Retry Logic: Failed jobs are automatically retried even if they ran recently, ensuring eventual success
Context-Aware Icons: Visual indicators show job status at a glance:
- ✅ Success jobs show completion icon
- ❌ Failed jobs show error icon
- 🔄 Retry attempts show sync icon
- 🕐 First-time runs show clock icon
Secure Shell Escaping: Arguments with spaces and special characters are properly escaped for security
Robust Last-Run Tracking: All job executions are tracked regardless of success/failure for accurate status reporting

Background Job Status Messages:

When a background job is running, Alfred will display informative status items:

Background Job 'github-releases'
Last succeeded 2 minutes ago (14:32:15), running for 3s

This gives users clear visibility into:

When the job last ran successfully or failed
The exact time of the last execution
How long the current execution has been running
Visual context through appropriate icons

URL Items with Rich Clipboard Support

Create URL items with automatic clipboard integration:

use alfrusco::URLItem;

let url_item = URLItem::new("Rust Documentation", "https://doc.rust-lang.org/")
    .subtitle("The Rust Programming Language Documentation")
    .short_title("Rust Docs")  // Used in Cmd+Shift modifier
    .long_title("The Rust Programming Language Official Documentation")  // Used in Cmd+Ctrl modifier
    .icon_for_filetype("public.html")
    .copy_text("doc.rust-lang.org");

// Convert to regular Item (happens automatically when added to workflow)
let item: Item = url_item.into();

URL items automatically include modifiers for copying links:

⌘ (Cmd): Copy as Markdown link [title](url)
⌥ (Alt): Copy as rich text link (HTML)
⌘⇧ (Cmd+Shift): Copy as Markdown with short title
⌥⇧ (Alt+Shift): Copy as rich text with short title
⌘⌃ (Cmd+Ctrl): Copy as Markdown with long title
⌥⌃ (Alt+Ctrl): Copy as rich text with long title

Smart Filtering and Sorting

Enable automatic fuzzy search and sorting of results:

impl Runnable for SearchWorkflow {
    type Error = alfrusco::Error;

    fn run(self, workflow: &mut Workflow) -> Result<(), Self::Error> {
        let query = self.query.join(" ");

        // Enable filtering - results will be automatically filtered and sorted
        workflow.set_filter_keyword(query);

        // Add items - they'll be filtered based on the query
        workflow.append_items(vec![
            Item::new("Apple").subtitle("Fruit"),
            Item::new("Banana").subtitle("Yellow fruit"),
            Item::new("Carrot").subtitle("Orange vegetable"),
        ]);

        Ok(())
    }
}

Workflow Directories

Access workflow-specific data and cache directories:

impl Runnable for MyWorkflow {
    type Error = alfrusco::Error;

    fn run(self, workflow: &mut Workflow) -> Result<(), Self::Error> {
        // Access workflow data directory (persistent storage)
        let data_dir = workflow.data_dir();
        let config_file = data_dir.join("config.json");

        // Access workflow cache directory (temporary storage)
        let cache_dir = workflow.cache_dir();
        let temp_file = cache_dir.join("temp_data.json");

        // Use directories for file operations
        std::fs::write(config_file, "{\"setting\": \"value\"}")?;

        Ok(())
    }
}

Response Caching and Rerun

Control Alfred's caching behavior and automatic refresh:

use std::time::Duration;

impl Runnable for MyWorkflow {
    type Error = alfrusco::Error;

    fn run(self, workflow: &mut Workflow) -> Result<(), Self::Error> {
        // Cache results for 5 minutes, allow loose reload
        workflow.cache(Duration::from_secs(300), true);

        // Automatically rerun every 30 seconds
        workflow.rerun(Duration::from_secs(30));

        // Skip Alfred's knowledge base integration
        workflow.skip_knowledge(true);

        workflow.append_item(Item::new("Cached result"));
        Ok(())
    }
}

🧪 Testing

Alfrusco provides comprehensive testing support with shared utilities and organized test structure:

#[cfg(test)]
mod tests {
    use super::*;
    use alfrusco::config::TestingProvider;
    use tempfile::tempdir;

    #[test]
    fn test_my_workflow() {
        let workflow = MyWorkflow {
            query: vec!["test".to_string()],
        };

        // Use TestingProvider for isolated testing
        let temp_dir = tempdir().unwrap();
        let provider = TestingProvider(temp_dir.path().to_path_buf());

        let mut buffer = Vec::new();
        alfrusco::execute(&provider, workflow, &mut buffer);

        let output = String::from_utf8(buffer).unwrap();
        assert!(output.contains("Hello, test!"));
    }

    #[tokio::test]
    async fn test_async_workflow() {
        let workflow = AsyncWorkflow {
            query: vec!["async".to_string()],
        };

        let temp_dir = tempdir().unwrap();
        let provider = TestingProvider(temp_dir.path().to_path_buf());

        let mut buffer = Vec::new();
        alfrusco::execute_async(&provider, workflow, &mut buffer).await;

        let output = String::from_utf8(buffer).unwrap();
        assert!(output.contains("async"));
    }
}

### Test Organization

Alfrusco maintains a comprehensive test suite with 112 tests across organized test files:

background_job_integration_tests.rs - Complete background job lifecycle testing (6 tests)
clipboard_tests.rs - Clipboard functionality testing (4 tests)
config_tests.rs - Configuration and environment testing (8 tests)
error_injection_tests.rs - Error handling and edge cases (2 tests)
error_tests.rs - Error type behavior (7 tests)
logging_tests.rs - Logging functionality (1 test)
runnable_tests.rs - Trait implementation testing (4 tests)
tests/common/mod.rs - Shared test utilities and helpers

Shared Test Utilities

The tests/common/mod.rs module provides reusable testing utilities that eliminate code duplication and ensure consistent test setup across the entire test suite. This includes helper functions for creating test workflows, managing temporary directories, and common test operations.


## 📚 Examples

The `examples/` directory contains complete, runnable examples. Since these examples use `AlfredEnvProvider`, they require Alfred environment variables to be set. We provide a convenient script to run them with mock environment variables:

### Running Examples

**Option 1: Using the run script (recommended)**
```bash
# Basic static output
./run-example.sh static_output

# Success workflow with custom message  
./run-example.sh success --message "Custom message"

# Async API example
./run-example.sh random_user search_term

# URL items demonstration
./run-example.sh url_items

# Background job example
./run-example.sh sleep --duration-in-seconds 10

# Error handling example
./run-example.sh error --file-path nonexistent.txt

Option 2: Using Make targets

# List all available examples
make examples-help

# Run specific examples
make example-static_output
make example-success
make example-url_items

Option 3: Manual environment setup

# Set required Alfred environment variables
export alfred_workflow_bundleid="com.example.test"
export alfred_workflow_cache="/tmp/cache"
export alfred_workflow_data="/tmp/data"
export alfred_version="5.0"
export alfred_version_build="2058"
export alfred_workflow_name="Test Workflow"

# Then run normally
cargo run --example static_output

Example Descriptions

static_output - Basic workflow that returns static items without user input
success - Simple workflow demonstrating command-line argument parsing
random_user - Async workflow that fetches data from an external API with fuzzy filtering
url_items - Demonstrates URL items with automatic clipboard integration and modifiers
sleep - Shows background job execution with status monitoring
error - Demonstrates custom error types and error item generation
async_success - Basic async workflow example
async_error - Async workflow with error handling examples

📖 API Reference

Core Types

`Item`

The primary building block for Alfred workflow results.

Key Methods:

new(title) - Create a new item with a title
subtitle(text) - Set subtitle text
arg(value) / args(values) - Set arguments passed to actions
valid(bool) - Set whether the item is actionable
uid(id) - Set unique identifier for Alfred's learning
icon_from_image(path) / icon_for_filetype(type) - Set item icons
copy_text(text) / large_type_text(text) - Set text operations
quicklook_url(url) - Enable Quick Look preview
var(key, value) - Set workflow variables
autocomplete(text) - Set tab completion text
modifier(modifier) - Add keyboard modifier actions

`URLItem`

Specialized item type for URLs with automatic clipboard integration.

Key Methods:

new(title, url) - Create a URL item
subtitle(text) - Override default URL subtitle
short_title(text) / long_title(text) - Set alternative titles for modifiers
display_title(text) - Override displayed title while preserving link title
copy_text(text) - Set custom copy text
icon_from_image(path) / icon_for_filetype(type) - Set icons

`Workflow`

Main workflow execution context.

Key Methods:

append_item(item) / append_items(items) - Add items to results
prepend_item(item) / prepend_items(items) - Add items to beginning
set_filter_keyword(query) - Enable fuzzy filtering
data_dir() / cache_dir() - Access workflow directories
run_in_background(name, max_age, command) - Execute background jobs

`Response`

Controls Alfred's response behavior.

Key Methods:

cache(duration, loose_reload) - Set caching behavior
rerun(interval) - Set automatic refresh interval
skip_knowledge(bool) - Control Alfred's knowledge integration

Traits

`Runnable`

For synchronous workflows.

trait Runnable {
    type Error: WorkflowError;
    fn run(self, workflow: &mut Workflow) -> Result<(), Self::Error>;
}

`AsyncRunnable`

For asynchronous workflows.

#[async_trait]
trait AsyncRunnable {
    type Error: WorkflowError;
    async fn run_async(self, workflow: &mut Workflow) -> Result<(), Self::Error>;
}

`WorkflowError`

For custom error types that integrate with Alfred.

trait WorkflowError: std::error::Error {
    fn error_item(&self) -> Item { /* default implementation */ }
}

Configuration

`AlfredEnvProvider`

Production configuration provider that reads from Alfred environment variables.

`TestingProvider`

Testing configuration provider that uses temporary directories.

Execution Functions

execute(provider, runnable, writer) - Execute synchronous workflow
execute_async(provider, runnable, writer) - Execute asynchronous workflow
init_logging(provider) - Initialize structured logging## 🛠️ Development

Building from Source

git clone https://github.com/adlio/alfrusco.git
cd alfrusco
cargo build

Running Tests

# Run all tests
cargo test

# Run tests with nextest (recommended)
cargo nextest run

# Run tests serially (for debugging flaky tests)
make test-serial

# Run with coverage
cargo tarpaulin --out html

Running Examples

Examples require Alfred environment variables. Use the provided script:

# Basic static output
./run-example.sh static_output

# Success workflow with custom message
./run-example.sh success --message "Hello World"

# Async API example
./run-example.sh random_user john

# URL items demonstration
./run-example.sh url_items

# Background job example
./run-example.sh sleep --duration-in-seconds 5

# Error handling example
./run-example.sh error --file-path /nonexistent/file.txt

# Or use Make targets
make example-static_output
make examples-help  # See all available examples

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for your changes
Ensure all tests pass (cargo nextest run)
Run clippy (cargo clippy)
Format your code (cargo fmt)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Follow Rust standard formatting (cargo fmt)
Ensure clippy passes without warnings (cargo clippy)
Add documentation for public APIs
Include tests for new functionality
Update examples if adding new features

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

Made with ❤️ for the Alfred and Rust communities.

alfrusco 0.2.0

alfrusco

Features

📦 Installation

🚀 Quick Start

Basic Synchronous Workflow

Async Workflow with HTTP Requests

🏗️ Core Concepts

Items

Workflow Configuration

Error Handling

🔧 Advanced Features

Background Jobs

URL Items with Rich Clipboard Support

Smart Filtering and Sorting

Workflow Directories

Response Caching and Rerun

🧪 Testing

### Test Organization

Shared Test Utilities

Example Descriptions

📖 API Reference

Core Types

Item

URLItem

Workflow

Response

Traits

Runnable

AsyncRunnable

WorkflowError

Configuration

AlfredEnvProvider

TestingProvider

Execution Functions

Building from Source

Running Tests

Running Examples

🤝 Contributing

Development Setup

Code Style

📄 License

📞 Support

`Item`

`URLItem`

`Workflow`

`Response`

`Runnable`

`AsyncRunnable`

`WorkflowError`

`AlfredEnvProvider`

`TestingProvider`