Skip to content

armgit / iris

Public Imported from GitHub
0

Screenshots of live websites. Minimal interface, powerful engine.

12.9 KB
Raw Blame
mod capture;
mod mcp;

use std::collections::HashMap;
use std::io::Read;
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Duration;

use anyhow::{Context, Result, bail};
use capture::{CaptureMode, Format, Opts, Session, normalize_url, parse_viewport, success_report};
use clap::{Args, Parser, Subcommand};
use futures::StreamExt;
use url::Url;

/// Screenshot live websites. Minimal interface, powerful engine:
/// smart waiting, lazy-load handling, retina output, concurrent capture.
#[derive(Parser)]
#[command(
    name = "iris",
    version,
    arg_required_else_help = true,
    subcommand_negates_reqs = true,
    args_conflicts_with_subcommands = true,
    after_help = "\
Examples:
  iris example.com                      1440\u{d7}900 @2x \u{2192} example.com.png
  iris --full --dark tailwindcss.com    full page, dark color scheme
  iris --selector '#hero' --padding 24 app.dev
  iris mcp                              serve the capture tool over stdio
  cat urls.txt | iris - -o shots/       concurrent batch from stdin"
)]
struct Cli {
    #[command(subcommand)]
    command: Option<Command>,

    #[command(flatten)]
    capture: CaptureArgs,
}

#[derive(Subcommand)]
enum Command {
    /// Serve Iris as a local Model Context Protocol camera
    Mcp(mcp::McpArgs),
}

#[derive(Args)]
struct CaptureArgs {
    /// URLs to capture; `-` reads newline-separated URLs from stdin
    #[arg(required = true, value_name = "URL")]
    urls: Vec<String>,

    /// Output file (single URL) or directory (batch) [default: ./<host>-<path>.png]
    #[arg(short, long, value_name = "PATH")]
    out: Option<PathBuf>,

    /// Viewport: WxH, or a preset: desktop (1440x900@2x), iphone (390x844@3x), ipad (1024x1366@2x)
    #[arg(short, long, default_value = "desktop", value_name = "SIZE")]
    size: String,

    /// Capture the full page height
    #[arg(long)]
    full: bool,

    /// Capture the first element matching this CSS selector
    #[arg(long, value_name = "CSS", conflicts_with = "full")]
    selector: Option<String>,

    /// Uniform CSS-pixel padding around a selected element
    #[arg(long, value_name = "PX", requires = "selector")]
    padding: Option<u32>,

    /// Emulate prefers-color-scheme: dark
    #[arg(long)]
    dark: bool,

    /// Image format (a recognized --out file extension wins) [default: png]
    #[arg(long, value_parser = ["png", "jpg", "jpeg", "webp"], value_name = "FMT")]
    format: Option<String>,

    /// Extra settle delay in ms after smart waiting
    #[arg(long, default_value_t = 0, value_name = "MS")]
    wait: u64,

    /// Wait until this CSS selector exists before capturing
    #[arg(long, value_name = "CSS")]
    wait_for: Option<String>,

    /// Device scale factor (overrides the preset's)
    #[arg(long, value_name = "N")]
    scale: Option<f64>,

    /// Concurrent captures [default: min(4, number of URLs)]
    #[arg(long, value_name = "N")]
    jobs: Option<usize>,

    /// Per-page timeout in seconds
    #[arg(long, default_value_t = 30, value_name = "SECS")]
    timeout: u64,

    /// Chrome/Chromium binary [auto-detected]
    #[arg(long, env = "CHROME", value_name = "PATH")]
    chrome: Option<PathBuf>,

    /// Emit one JSON object per completed capture
    #[arg(long)]
    json: bool,
}

#[tokio::main]
async fn main() -> Result<()> {
    let cli = Cli::parse();
    if let Some(Command::Mcp(args)) = cli.command {
        return mcp::run(args).await;
    }
    run_capture(cli.capture).await
}

async fn run_capture(cli: CaptureArgs) -> Result<()> {
    let urls = collect_urls(&cli.urls)?;
    let viewport = parse_viewport(&cli.size, cli.scale)?;
    let mode = capture_mode(&cli);
    let flag_format = cli.format.as_deref().and_then(Format::from_ext);
    let (targets, format) = resolve_outputs(&urls, cli.out.as_deref(), flag_format).await?;
    let jobs = cli.jobs.unwrap_or_else(|| urls.len().min(4)).max(1);

    let opts = Arc::new(Opts {
        viewport,
        mode: mode.clone(),
        dark: cli.dark,
        wait_ms: cli.wait,
        wait_for: cli.wait_for,
        timeout: Duration::from_secs(cli.timeout.max(1)),
        format,
    });

    let session = Arc::new(Session::launch(cli.chrome, viewport).await?);

    let mut failed = 0usize;
    let mut stream = futures::stream::iter(targets)
        .map({
            let session = Arc::clone(&session);
            let opts = Arc::clone(&opts);
            move |(url, path): (Url, PathBuf)| {
                let session = Arc::clone(&session);
                let opts = Arc::clone(&opts);
                async move {
                    let result = match session.capture(url.as_str(), &opts).await {
                        Ok(image) => image.write_to(&path).await.map(|()| image.shot),
                        Err(error) => Err(error),
                    };
                    (url, path, result)
                }
            }
        })
        .buffer_unordered(jobs);

    while let Some((url, path, result)) = stream.next().await {
        match result {
            Ok(shot) => {
                if cli.json {
                    println!(
                        "{}",
                        serde_json::to_string(&success_report(
                            url.as_str(),
                            Some(&path),
                            &mode,
                            format,
                            &shot,
                        ))?
                    );
                } else {
                    println!(
                        "\u{2713} {} \u{2014} {}\u{d7}{} @{}x, {}",
                        path.display(),
                        shot.width,
                        shot.height,
                        shot.scale,
                        human_size(shot.bytes),
                    );
                }
            }
            Err(err) => {
                failed += 1;
                if cli.json {
                    println!(
                        "{}",
                        serde_json::to_string(&capture::error_report(
                            url.as_str(),
                            Some(&path),
                            &mode,
                            format!("{err:#}"),
                        ))?
                    );
                } else {
                    eprintln!("\u{2717} {url} \u{2014} {err:#}");
                }
            }
        }
    }

    drop(stream);
    if let Ok(session) = Arc::try_unwrap(session) {
        session.close().await;
    }

    if failed > 0 {
        std::process::exit(1);
    }
    Ok(())
}

fn capture_mode(cli: &CaptureArgs) -> CaptureMode {
    if let Some(selector) = &cli.selector {
        CaptureMode::Element {
            selector: selector.clone(),
            padding: cli.padding.unwrap_or(0),
        }
    } else if cli.full {
        CaptureMode::FullPage
    } else {
        CaptureMode::Viewport
    }
}

fn collect_urls(args: &[String]) -> Result<Vec<Url>> {
    let mut raw = Vec::new();
    for arg in args {
        if arg == "-" {
            let mut input = String::new();
            std::io::stdin()
                .read_to_string(&mut input)
                .context("failed to read URLs from stdin")?;
            raw.extend(
                input
                    .lines()
                    .map(str::trim)
                    .filter(|l| !l.is_empty() && !l.starts_with('#'))
                    .map(String::from),
            );
        } else {
            raw.push(arg.clone());
        }
    }
    if raw.is_empty() {
        bail!("no URLs given");
    }
    raw.iter().map(|value| normalize_url(value)).collect()
}

/// Pair each URL with its output path and settle the image format. Single URL +
/// `--out file.ext` writes that exact file (its extension beats --format); anything
/// else treats --out (default `.`) as a directory of derived names in the chosen format.
async fn resolve_outputs(
    urls: &[Url],
    out: Option<&std::path::Path>,
    flag_format: Option<Format>,
) -> Result<(Vec<(Url, PathBuf)>, Format)> {
    if let (1, Some(path)) = (urls.len(), out)
        && let Some(ext) = path.extension()
        && let Some(format) = Format::from_ext(&ext.to_string_lossy())
    {
        if let Some(dir) = path.parent().filter(|d| !d.as_os_str().is_empty()) {
            tokio::fs::create_dir_all(dir).await?;
        }
        return Ok((vec![(urls[0].clone(), path.to_path_buf())], format));
    }

    let format = flag_format.unwrap_or(Format::Png);
    let dir = out.unwrap_or_else(|| std::path::Path::new("."));
    tokio::fs::create_dir_all(dir).await?;
    let mut seen: HashMap<String, u32> = HashMap::new();
    let targets = urls
        .iter()
        .map(|url| {
            let mut name = derived_name(url);
            let n = seen.entry(name.clone()).or_insert(0);
            *n += 1;
            if *n > 1 {
                name = format!("{name}-{n}");
            }
            (url.clone(), dir.join(format!("{name}.{}", format.ext())))
        })
        .collect();
    Ok((targets, format))
}

/// `https://example.com/pricing/` -> `example.com-pricing`
fn derived_name(url: &Url) -> String {
    let host = url.host_str().unwrap_or("page");
    let path = url.path().trim_matches('/').replace('/', "-");
    let name = if path.is_empty() {
        host.to_string()
    } else {
        format!("{host}-{path}")
    };
    name.chars()
        .map(|c| {
            if c.is_ascii_alphanumeric() || matches!(c, '.' | '-' | '_') {
                c
            } else {
                '-'
            }
        })
        .collect()
}

fn human_size(bytes: u64) -> String {
    if bytes >= 1024 * 1024 {
        format!("{:.1} MB", bytes as f64 / (1024.0 * 1024.0))
    } else {
        format!("{} KB", bytes.div_ceil(1024))
    }
}

#[cfg(test)]
mod tests {
    use clap::error::ErrorKind;

    use super::*;
    use crate::capture::Shot;

    #[test]
    fn selector_conflicts_with_full_page() {
        let error = Cli::try_parse_from(["iris", "example.com", "--selector", "h1", "--full"])
            .err()
            .unwrap();
        assert_eq!(error.kind(), ErrorKind::ArgumentConflict);
    }

    #[test]
    fn padding_requires_a_selector_and_rejects_negative_values() {
        let missing_selector = Cli::try_parse_from(["iris", "example.com", "--padding", "12"])
            .err()
            .unwrap();
        assert_eq!(missing_selector.kind(), ErrorKind::MissingRequiredArgument);

        let negative =
            Cli::try_parse_from(["iris", "example.com", "--selector", "h1", "--padding=-1"])
                .err()
                .unwrap();
        assert_eq!(negative.kind(), ErrorKind::ValueValidation);
    }

    #[test]
    fn capture_mode_is_constructed_once_from_validated_cli() {
        let element = Cli::try_parse_from([
            "iris",
            "example.com",
            "--selector",
            "main > h1",
            "--padding",
            "24",
        ])
        .unwrap();
        assert_eq!(
            capture_mode(&element.capture),
            CaptureMode::Element {
                selector: "main > h1".into(),
                padding: 24,
            }
        );

        let full = Cli::try_parse_from(["iris", "example.com", "--full"]).unwrap();
        assert_eq!(capture_mode(&full.capture), CaptureMode::FullPage);

        let viewport = Cli::try_parse_from(["iris", "example.com"]).unwrap();
        assert_eq!(capture_mode(&viewport.capture), CaptureMode::Viewport);
    }

    #[test]
    fn mcp_subcommand_does_not_require_a_url() {
        let cli = Cli::try_parse_from(["iris", "mcp"]).unwrap();
        assert!(matches!(cli.command, Some(Command::Mcp(_))));

        let conflict = Cli::try_parse_from(["iris", "mcp", "--dark"])
            .err()
            .unwrap();
        assert_eq!(conflict.kind(), ErrorKind::UnknownArgument);
    }

    #[test]
    fn json_reports_have_stable_typed_fields() {
        let mode = CaptureMode::Element {
            selector: "h1".into(),
            padding: 24,
        };
        let shot = Shot {
            width: 180,
            height: 72,
            scale: 2.0,
            bytes: 14_231,
        };
        let success = serde_json::to_string(&success_report(
            "https://example.com/",
            Some(std::path::Path::new("/tmp/example.png")),
            &mode,
            Format::Png,
            &shot,
        ))
        .unwrap();
        assert_eq!(
            success,
            r#"{"status":"ok","url":"https://example.com/","output":"/tmp/example.png","mode":"element","selector":"h1","padding":24,"css_width":180,"css_height":72,"scale":2.0,"format":"png","bytes":14231}"#
        );

        let failure = serde_json::to_string(&capture::error_report(
            "https://example.com/",
            Some(std::path::Path::new("/tmp/example.png")),
            &mode,
            "selector never appeared: h1".into(),
        ))
        .unwrap();
        assert_eq!(
            failure,
            r#"{"status":"error","url":"https://example.com/","output":"/tmp/example.png","mode":"element","selector":"h1","padding":24,"error":"selector never appeared: h1"}"#
        );
    }
}