GitCorner

Code

ossartcraftlightcraft๐ŸŒ
5a24289898fd
//! An in-process [`Session`] that answers the control-channel methods the MCP tools use, so the
//! MCP server (and the CLI) work without a window.

use std::path::Path;

use lightcraft_engine::Session;
use lightcraft_engine::catalog::PhotoId;
use lightcraft_raster::Rgba8;
use serde_json::{Value, json};

use crate::backend::{Backend, ProgressHook};

/// Headless backend: a [`Session`] with filesystem hooks.
pub struct Headless {
    pub session: Session,
    progress: Option<ProgressHook>,
}

impl Drop for Headless {
    /// Snapshot a persistent library on exit (a no-op for in-memory sessions), after any Apple
    /// Photos import still running (`export.addToPhotos {wait: false}`) has ended: the process
    /// must not end in the middle of one, abandoning osascript and the import's result.
    fn drop(&mut self) {
        #[cfg(not(target_arch = "wasm32"))]
        self.session.wait_for_photos_imports();
        let _ = self.session.close_library();
    }
}

impl Default for Headless {
    fn default() -> Self {
        // the lens database the desktop app downloaded, when it is there (a headless session never fetches it)
        let session =
            Session::new().with_fs().with_default_denoise_models().with_system_clock().with_default_face_models().with_default_lens_database();
        Self::new(session.with_default_sam3_model().with_default_slide_templates())
    }
}

impl Headless {
    pub fn new(session: Session) -> Self {
        Self { session, progress: None }
    }

    /// A headless session with the procedurally generated demo library.
    pub fn demo() -> Self {
        let session = Session::with_demo().with_fs().with_default_denoise_models().with_system_clock().with_default_face_models();
        Self::new(session.with_default_sam3_model().with_default_slide_templates())
    }

    fn photo_or_active(&self, p: &Value) -> Result<PhotoId, String> {
        p.get("id").and_then(Value::as_u64).map(PhotoId).or(self.session.active()).ok_or_else(|| "no photo (import one or pass `id`)".to_string())
    }

    /// Render `id` (or the active photo) so its long edge is at most `size` pixels.
    pub fn render(&mut self, p: &Value, default_size: u64) -> Result<Rgba8, String> {
        let id = self.photo_or_active(p)?;
        let size = p.get("size").or(p.get("longEdge")).and_then(Value::as_u64).unwrap_or(default_size).clamp(16, 16384) as usize;
        Ok(self.session.render_now(id, size, size)?.image)
    }

    /// The UI command `app.export`, emulated with the same parameters as the desktop app
    /// (see `lightcraft_engine::export::ExportOptions::from_json`, plus `ids`, `dir`, `path`).
    /// With `path` and no `format`, the format follows the path's extension.
    fn export(&mut self, p: &Value) -> Result<Value, String> {
        use lightcraft_engine::export::{Destination, ExportFormat, ExportOptions, Resize, prepare_batch, run_batch};
        let p = &self.session.export_params_or(p, ExportFormat::Png)?;
        // PNG for a `path` that names no format; `bitDepth` is checked against the format written
        let mut opts = ExportOptions::from_params_or(p, ExportFormat::Png).map_err(|e| e.to_string())?;
        if !ExportOptions::has_size_param(p) {
            opts.resize = Some(Resize::long_edge(3000));
        }
        let exact = p.get("path").and_then(Value::as_str);
        let ids: Vec<_> = match p.get("ids").and_then(Value::as_array) {
            Some(a) => a.iter().filter_map(|v| serde_json::from_value(v.clone()).ok()).collect(),
            // like the desktop app: the selection (in grid order), else the given / active photo
            None if p.get("id").is_none() && self.session.selection.ids.len() > 1 => {
                let sel: std::collections::HashSet<_> = self.session.selection.ids.iter().copied().collect();
                self.session.visible_cloned().into_iter().filter(|id| sel.contains(id)).collect()
            }
            None => vec![self.photo_or_active(p)?],
        };
        let dir = p.get("dir").and_then(Value::as_str).unwrap_or("");
        let write = &mut lightcraft_engine::export::write_file;
        // Add to Apple Photos: refused before anything is written when it can't be done
        let after = self.session.after_export(&opts)?;
        let items = prepare_batch(&mut self.session, &ids, &opts)?;
        let total = items.len();
        let mut hook = self.progress.take();
        let mut cancelled = false;
        let files = run_batch(
            items,
            &opts,
            &Destination { dir: dir.to_string(), exact: exact.map(str::to_string) },
            write,
            &|path| Path::new(path).exists(),
            true,
            &mut |done, name| {
                cancelled = hook.as_mut().is_some_and(|h| !h(done, total, name));
                !cancelled
            },
        )?;
        if !cancelled && let Some(hook) = hook.as_mut() {
            cancelled = !hook(total, total, "");
        }
        if cancelled {
            return Err("cancelled".into());
        }
        // Single-photo exports also report path/width/height at the top level (back-compat).
        let mut out = files.first().cloned().unwrap_or_else(|| json!({}));
        if let Some(photos) = after.run(&files, false) {
            out["applePhotos"] = photos;
        }
        out["files"] = json!(files);
        Ok(out)
    }
}

impl Backend for Headless {
    fn set_progress(&mut self, hook: Option<ProgressHook>) {
        self.progress = hook;
    }

    fn call(&mut self, method: &str, params: Value) -> Result<Value, String> {
        let p = if params.is_null() { json!({}) } else { params };
        match method {
            "engine.execute" | "ui.menu.invoke" | "command" => {
                let id = p.get("command").or(p.get("id")).and_then(Value::as_str).ok_or("missing `command`")?;
                let params = p.get("params").cloned().filter(|v| !v.is_null()).unwrap_or(json!({}));
                if id == "app.export" {
                    return self.export(&params);
                }
                self.session.execute(id, &params).map_err(|e| e.to_string())
            }
            "engine.commands" => {
                let mut v: Vec<Value> = self.session.commands().into_iter().map(|c| serde_json::to_value(c).unwrap_or_default()).collect();
                v.push(json!({"id": "app.export", "label": "Export Now", "menu": [], "shortcut": null,
                    "params": "{path?: output file (.jpg/.png/.tif/.webp/.avif/.jxl/.psd/.dng) | dir?, ids?, preset?, format?: jpeg|png|tiff|webp|avif|jxl|psd|dng|original, longEdge?|shortEdge?|width?|height?|megapixels?|percent? (default longEdge 3000; longEdge 0 = full size), fit?: dimensions|widthHeight (with width + height: dimensions fits either orientation, widthHeight limits the width to `width` and the height to `height`), dontEnlarge?, ppi?, quality?: 1..100, jxlLossless?, jxlEffort?: fast|normal, jxlProgressive?, limitKb?, colorSpace?: srgb|displayP3|adobeRgb|proPhoto|rec2020, bitDepth?: 8|10|16|32, hdr? (HDR output for HDR edits: gain map JPEG, PQ AVIF / PNG / JPEG XL, float TIFF), sharpen?: none|screen|matte|glossy, sharpenAmount?: low|standard|high, metadata?: all|allExceptCamera|copyright|none, removeLocation?, naming?, startNumber?, destinationMode?: specificFolder|sameAsOriginal (sameAsOriginal = each photo into its original's folder; `dir` unused), subfolder?, conflict?: unique|overwrite|skip, tiffCompression?: none|lzw|zip (default zip; lzw is usually larger and slower than zip, at 16 bit often larger than none: only for software that needs LZW), dngCompression?: lossless|deflate|uncompressed, addToPhotos?: bool (macOS: then add the files written to Apple Photos; outcome in `applePhotos`), photosAlbum?: top-level album name (made when missing), watermark?: text | {text?, vertical? (upright columns, right to left), size? (text height, 0.005..0.5 of the short edge; default 0.035), opacity? (0..1; 0.7), anchor?: topLeft|top|topRight|left|center|right|bottomLeft|bottom|bottomRight, insetX? (margin from the left/right edge, 0..0.4 of the short edge; 0.025), insetY? (from the top/bottom edge; 0.025), inset? (sets both), rotation?: 0|90|180|270 (degrees clockwise; 0), color? [r,g,b] sRGB, shadow?, image? (graphic drawn instead of the text), imageWidth? (0.01..1 of the photo's width; 0.2)}} โ€” an unknown parameter, an out-of-range watermark size or a value of the wrong kind is an error, not a default",
                    "enabled": self.session.active().is_some()}));
                Ok(Value::Array(v))
            }
            "ui.render" => {
                let img = self.render(&p, 1600)?;
                match p.get("path").and_then(Value::as_str) {
                    Some(path) => {
                        self.session.check_write_target(path)?;
                        write_image(Path::new(path), &img, 92)?;
                        Ok(json!({"path": path, "width": img.width, "height": img.height}))
                    }
                    None => Ok(json!({"width": img.width, "height": img.height})),
                }
            }
            "app.export" => self.export(&p),
            m if m.starts_with("ui.") || m == "app.quit" => {
                Err(format!("`{m}` needs the desktop app: start `lightcraft --control 7980` and run the MCP server with `--connect`"))
            }
            other => Err(format!("unknown method `{other}`")),
        }
    }

    fn has_ui(&self) -> bool {
        false
    }

    fn describe(&self) -> String {
        "headless".into()
    }
}

/// Expand folders (recursively, sorted; bounded, see `lightcraft_engine::walk`) into photo files
/// and make paths absolute. Folders take the extensions `library.import` takes
/// (`lightcraft_engine::import::EXTENSIONS`), so the two can't drift apart (issue #1080).
pub fn expand_paths(paths: &[String]) -> Vec<String> {
    let absolute = |p: &Path| std::path::absolute(p).unwrap_or_else(|_| p.to_path_buf()).to_string_lossy().to_string();
    let mut out = Vec::new();
    for p in paths {
        let path = Path::new(p);
        if path.is_dir() {
            let w =
                lightcraft_engine::walk::files_in(path, None, lightcraft_engine::walk::Limits::default(), lightcraft_engine::import::is_supported);
            out.extend(w.files.iter().map(|f| absolute(f)));
        } else {
            // Explicit files are kept even with unknown extensions (the probe decides).
            out.push(absolute(path));
        }
    }
    out
}

/// Encode by extension: `.png` (default), `.jpg`/`.jpeg` (quality), `.tif`/`.tiff`, `.webp` (lossless),
/// `.avif`, `.jxl` โ€” via the shared export encoder (embeds an sRGB profile).
pub fn encode_image(ext: &str, img: &Rgba8, quality: u8) -> Result<Vec<u8>, String> {
    use lightcraft_engine::export::{ExportFormat, ExportOptions};
    let format = ExportFormat::parse(ext).unwrap_or(ExportFormat::Png);
    lightcraft_engine::export::encode_image(img, &ExportOptions { format, quality: quality.clamp(1, 100), ..Default::default() })
}

/// Encode by the path's extension and write the file.
pub fn write_image(path: &Path, img: &Rgba8, quality: u8) -> Result<(), String> {
    let ext = path.extension().map(|e| e.to_string_lossy().to_string()).unwrap_or_default();
    let bytes = encode_image(&ext, img, quality)?;
    lightcraft_engine::export::write_file(&path.to_string_lossy(), &bytes)
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A headless session reads the lens database the desktop app downloaded, as the desktop does (the same raw gets
    /// the same profile everywhere), but never fetches it by itself.
    #[test]
    fn a_headless_session_reads_the_downloaded_lens_database() {
        let h = Headless::default();
        assert_eq!(lightcraft_engine::lens_profiles::host_dir(), lightcraft_engine::lensfun_download::default_dir());
        assert!(!h.session.lens_auto_download, "selecting it is not permission to download it");
    }

    #[test]
    fn folder_discovery_matches_engine_extensions() {
        let dir = std::env::temp_dir().join(format!("lc-mcp-discovery-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let nested = dir.join("trip").join("day2"); // not "trip/day2": discovery yields the platform's separator
        std::fs::create_dir_all(&nested).unwrap();
        let mut expected = Vec::new();
        for ext in lightcraft_engine::import::EXTENSIONS {
            for (folder, name) in [(&dir, format!("lower.{ext}")), (&nested, format!("upper.{}", ext.to_ascii_uppercase()))] {
                let path = folder.join(name);
                std::fs::write(&path, b"discovery only, not a decoded photo").unwrap();
                expected.push(path.to_string_lossy().into_owned());
            }
        }
        std::fs::write(nested.join("notes.txt"), b"not a photo").unwrap();
        let mut found = expand_paths(&[dir.to_string_lossy().into_owned()]);
        expected.sort();
        found.sort();
        assert_eq!(found, expected);
        std::fs::remove_dir_all(dir).unwrap();
    }

    /// Headless sessions look for the SAM 3 model where the desktop app does, and `segment.model.status` reports it (issue #619).
    #[test]
    fn headless_sessions_get_the_sam3_model_folder() {
        let dir = lightcraft_engine::config::default_sam3_dir();
        assert_eq!(Headless::default().session.segmenter.dir, dir);
        assert_eq!(Headless::demo().session.segmenter.dir, dir);
        let dir = std::env::temp_dir().join("lc-mcp-sam3-dir");
        let mut session = Session::new();
        session.segmenter.dir = Some(dir.clone());
        let mut h = Headless::new(session);
        let r = h.call("engine.execute", json!({"command": "segment.model.status", "params": {}})).unwrap();
        assert_eq!(r["dir"], json!(dir.display().to_string()), "{r}");
    }

    /// `--import <folder>` picks up every extension `library.import` takes, HEIC included (issue #1080).
    #[test]
    fn expand_paths_takes_the_engine_extensions() {
        let dir = std::env::temp_dir().join(format!("lc-mcp-expand-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        for e in lightcraft_engine::import::EXTENSIONS {
            std::fs::write(dir.join(format!("a.{e}")), b"x").unwrap();
        }
        std::fs::write(dir.join("B.HEIC"), b"x").unwrap();
        std::fs::write(dir.join("notes.txt"), b"x").unwrap();
        let found = expand_paths(&[dir.to_string_lossy().to_string()]);
        let _ = std::fs::remove_dir_all(&dir);
        let ext = |f: &String| Path::new(f).extension().map(|e| e.to_string_lossy().to_string()).unwrap_or_default();
        let mut got: Vec<String> = found.iter().map(ext).collect();
        got.sort();
        let mut want: Vec<String> = lightcraft_engine::import::EXTENSIONS.iter().map(|e| e.to_string()).chain(["HEIC".to_string()]).collect();
        want.sort();
        assert_eq!(got, want);
    }

    /// A headless session stamps imports and edits with the system clock, not the engine's fixed test clock.
    #[test]
    fn headless_uses_the_system_clock() {
        const FIXED: &str = "2026-09-30T12:00:00";
        assert_ne!((Headless::default().session.clock)(), FIXED);
        assert_ne!((Headless::demo().session.clock)(), FIXED);
    }

    /// `app.export` without `ids` exports the selection (as the desktop app does), else the active photo.
    #[test]
    fn export_follows_the_selection() {
        let dir = std::env::temp_dir().join(format!("lc-mcp-export-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut h = Headless::demo();
        let ids: Vec<u64> = h.session.visible_cloned().iter().take(3).map(|p| p.0).collect();
        h.call("engine.execute", json!({"command": "library.select", "params": {"ids": ids}})).unwrap();
        let r = h
            .call("engine.execute", json!({"command": "app.export", "params": {"dir": dir.to_string_lossy(), "longEdge": 64, "format": "png"}}))
            .unwrap();
        assert_eq!(r["files"].as_array().map(Vec::len), Some(3), "{r}");
        // one photo selected: that one
        h.call("engine.execute", json!({"command": "library.select", "params": {"ids": [ids[0]]}})).unwrap();
        let r = h
            .call("engine.execute", json!({"command": "app.export", "params": {"dir": dir.to_string_lossy(), "longEdge": 64, "format": "png"}}))
            .unwrap();
        assert_eq!(r["files"].as_array().map(Vec::len), Some(1));
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The export file-name template takes the Rename Photos tokens.
    #[test]
    fn export_naming_tokens() {
        let dir = std::env::temp_dir().join(format!("lc-mcp-export-naming-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let mut h = Headless::demo();
        let ids: Vec<u64> = h.session.visible_cloned().iter().take(2).map(|p| p.0).collect();
        for (id, title) in ids.iter().zip(["Harbour", "Hills"]) {
            h.call("engine.execute", json!({"command": "photo.setMeta", "params": {"ids": [id], "title": title}})).unwrap();
            h.call("engine.execute", json!({"command": "photo.rate", "params": {"ids": [id], "rating": 4}})).unwrap();
        }
        let params = json!({"dir": dir.to_string_lossy(), "ids": ids, "longEdge": 32, "format": "png", "naming": "{title}_{rating}star_{seq:2}", "startNumber": 5});
        let r = h.call("engine.execute", json!({"command": "app.export", "params": params})).unwrap();
        let mut names: Vec<String> = std::fs::read_dir(&dir).unwrap().flatten().map(|e| e.file_name().to_string_lossy().to_string()).collect();
        names.sort();
        assert_eq!(names, ["Harbour_4star_05.png", "Hills_4star_06.png"], "{r}");
        let _ = std::fs::remove_dir_all(&dir);
    }
}