GitCorner

Code

ossartcraftphotocraft🌐
856f865cf98d
//! The command line, as clap types. Values are parsed into their types here, so a bad one is a
//! usage error naming its flag (exit 2) and the handlers never see it (#7071). A flag a
//! subcommand doesn't take is a usage error too, so a typo such as `--fromat` can't be silently
//! ignored (#423), and so is a repeated one: `--quality 80 --quality 60` is more likely a mistake
//! than a choice. A value starting with `-` is written `--out=-image.png` (or `./-image.png`), so a
//! value flag never takes the next flag as its value; negative numbers are kept where they mean
//! something.

use std::ffi::OsString;
use std::fmt;
use std::net::{Ipv4Addr, SocketAddr};
use std::path::PathBuf;

pub(crate) use crate::gpu::GpuArgs;
use clap::error::ErrorKind;
use clap::parser::ValueSource;
use clap::{ArgAction, ArgGroup, ArgMatches, Args, CommandFactory, FromArgMatches, Parser, Subcommand};
use photocraft_automation::args::{AutomationArgs, ControlArgs, blank_env_is_unset, conflict, control_port, name_env_vars};
use photocraft_codecs::{JpegFormat, TiffCompression};
use photocraft_io::{DdsCompression, DpxBits, TgaBits, XmpEmbed};
use serde_json::Value;

/// photocraft-cli: headless PhotoCraft
#[derive(Parser)]
#[command(name = "photocraft-cli", version = photocraft_engine::build_info::long_version_static(), arg_required_else_help = true)]
pub(crate) struct Cli {
    #[command(subcommand)]
    pub(crate) command: Command,
}

#[derive(Subcommand)]
pub(crate) enum Command {
    Convert(ConvertArgs),
    Info(InfoArgs),
    Run(RunArgs),
    Batch(BatchArgs),
    Droplet(DropletArgs),
    Commands(CommandsArgs),
    Mcp(McpArgs),
    Serve(ServeArgs),
}

// How an image is written: shared by `convert`, `run` and `batch`.
#[derive(Args)]
pub(crate) struct ExportArgs {
    /// Output format, overriding the output's extension (png, jpg, tif, webp, …)
    #[arg(long, value_name = "EXT")]
    pub(crate) format: Option<String>,
    /// JPEG or WebP quality, 1-100. A WebP written with a quality is lossy, without one lossless
    // allow_negative_numbers makes `--quality -1` an out-of-range value rather than an unexpected argument.
    #[arg(long, value_name = "1-100", value_parser = clap::value_parser!(u8).range(1..=100), allow_negative_numbers = true)]
    pub(crate) quality: Option<u8>,
    /// Keep the layers in TIFF output (Photoshop layer data); TIFF output is flat without it
    #[arg(long)]
    pub(crate) tiff_layers: bool,
    /// Compress TIFF output: none (the default), lzw or zip
    #[arg(long, value_name = "none|lzw|zip", value_parser = tiff_compression)]
    pub(crate) tiff_compression: Option<TiffCompression>,
    /// TIFF Save Transparency: on keeps the transparency (ahead of any alpha or spot channels),
    /// off composites the image over white. Without it: kept unless the document has alpha or
    /// spot channels
    #[arg(long, value_name = "on|off", value_parser = on_off)]
    pub(crate) tiff_transparency: Option<bool>,
    /// Also write a TIFF image pyramid: half-size copies after the full image
    #[arg(long)]
    pub(crate) tiff_pyramid: bool,
    /// A TGA's bits per pixel: 32 writes the alpha channel (or else the transparency) as its
    /// alpha, 24 none. Without it: 32 with an alpha channel or transparency, else 24
    #[arg(long, value_name = "24|32", value_parser = tga_bits)]
    pub(crate) tga_bits: Option<TgaBits>,
    /// A DPX's bits per sample. Without it: 8 for an 8-bit document, else 16
    #[arg(long, value_name = "8|10|12|16", value_parser = dpx_bits)]
    pub(crate) dpx_bits: Option<DpxBits>,
    /// A DDS texture's compression: none (uncompressed, the default), bc1 (DXT1: alpha on or
    /// off), bc2 (DXT3) or bc3 (DXT5)
    #[arg(long, value_name = "none|bc1|bc2|bc3", value_parser = dds_compression)]
    pub(crate) dds_compression: Option<DdsCompression>,
    /// Also write a DDS texture's full mip chain
    #[arg(long)]
    pub(crate) dds_mipmaps: bool,
    /// A JPEG's scans, as JPEG Options picks them: baseline (the default), optimized (Huffman
    /// tables fitted to the image; RGB is written 4:2:0 and keeps the standard tables, so only Gray
    /// and CMYK shrink) or progressive
    #[arg(long, value_name = "baseline|optimized|progressive", value_parser = jpeg_format)]
    pub(crate) jpeg_format: Option<JpegFormat>,
    /// Request the flattened document at its canvas size in .pcraft output as
    /// composite/full.png; it may be omitted. Check the manifest's full_composite member.
    #[arg(long)]
    pub(crate) pcraft_full_composite: bool,
    /// A layered PSD/PSB stores Photoshop's white placeholder instead of the merged image
    /// (Maximize Compatibility off): a smaller file and a faster save, but readers that show only
    /// the merged image see white. Bitmap, Indexed Color and Duotone documents still write the
    /// real image
    #[arg(long)]
    pub(crate) no_maximize_compatibility: bool,
    /// The document metadata a flat export embeds: all (the default) keeps the document's XMP
    /// packet and free-form text where the format holds them, as Save As does; none leaves them
    /// out, as Export As's Metadata: None. Nothing else changes: the ICC profile, EXIF and
    /// resolution are written as they are without it. PSD, PSB and .pcraft always keep the XMP
    #[arg(long, value_name = "none|all", value_parser = metadata)]
    pub(crate) metadata: Option<XmpEmbed>,
}

/// Convert between formats (.pcraft, .psd, .png, .jpg, .tif, .webp, .exr, …)
///
/// An <OUT> that is the <IN> file is refused, as the result would replace the original;
/// --in-place allows it.
#[derive(Args)]
pub(crate) struct ConvertArgs {
    /// The file to read
    #[arg(value_name = "IN")]
    pub(crate) input: PathBuf,
    /// The file to write; its extension picks the format unless --format is given
    #[arg(value_name = "OUT")]
    pub(crate) output: PathBuf,
    /// Allow an <OUT> that is the <IN> file, replacing the original
    #[arg(long)]
    pub(crate) in_place: bool,
    /// Explicitly approve high-memory PSD/PSB imports within the hard memory budget
    #[arg(long)]
    pub(crate) approve_high_memory: bool,
    /// PDF import resolution in DPI (default 300)
    #[arg(long, value_name = "DPI", value_parser = pdf_dpi)]
    pub(crate) pdf_dpi: Option<f32>,
    /// PDF pages to import, 1-based: "3" or "2-7" (default all)
    #[arg(long)]
    pub(crate) pdf_pages: Option<String>,
    /// Import PDF paths and embedded-font text as editable layers (experimental; unsupported
    /// pages fall back to raster, and embedded fonts may change when edited or reopened)
    #[arg(long)]
    pub(crate) pdf_editable: bool,
    #[command(flatten)]
    pub(crate) gpu: GpuArgs,
    #[command(flatten)]
    pub(crate) export: ExportArgs,
}

/// Print the document as JSON (size, mode, depth, layer tree)
#[derive(Args)]
pub(crate) struct InfoArgs {
    pub(crate) file: PathBuf,
    /// One line of JSON instead of pretty-printed
    #[arg(long)]
    pub(crate) compact: bool,
    /// Explicitly approve high-memory PSD/PSB imports within the hard memory budget
    #[arg(long)]
    pub(crate) approve_high_memory: bool,
    /// Also list every text run and paragraph run, anti-aliasing and full layer-effect settings
    #[arg(long)]
    pub(crate) detail: bool,
}

/// Open a file (or start a new document), run engine commands in order, save the result
///
/// Prints each command's JSON result. Give exactly one of <FILE> or --new, and at least one --cmd
/// or --out. An --out that is the <FILE> is refused, as the result would replace the original;
/// --in-place allows it.
#[derive(Args)]
#[command(group(ArgGroup::new("source").args(["file", "new"]).required(true)))]
#[command(group(ArgGroup::new("work").args(["cmd", "out"]).required(true).multiple(true)))]
pub(crate) struct RunArgs {
    /// The document to open
    pub(crate) file: Option<PathBuf>,
    /// Start from a new document with these JSON parameters instead of opening a file
    #[arg(long, value_name = "JSON", value_parser = json)]
    pub(crate) new: Option<Value>,
    /// An engine command to run; repeat for several, run in order
    #[arg(long, value_name = "ID", action = ArgAction::Append)]
    pub(crate) cmd: Vec<String>,
    /// JSON parameters for the --cmd before it (default {})
    #[arg(long, value_name = "JSON", action = ArgAction::Append, value_parser = json)]
    pub(crate) params: Vec<Value>,
    /// Save the result to this file
    #[arg(long, value_name = "FILE")]
    pub(crate) out: Option<PathBuf>,
    /// Allow an --out that is the <FILE>, replacing the original
    #[arg(long)]
    pub(crate) in_place: bool,
    /// Explicitly approve high-memory PSD/PSB imports within the hard memory budget
    #[arg(long)]
    pub(crate) approve_high_memory: bool,
    #[command(flatten)]
    pub(crate) gpu: GpuArgs,
    #[command(flatten)]
    pub(crate) export: ExportArgs,
    /// `--cmd` and `--params` values in command-line order, set by [`parse`].
    #[arg(skip)]
    pub(crate) steps: Vec<Step>,
}

/// One `--cmd` or `--params` of `run`, in command-line order.
pub(crate) enum Step {
    Cmd(String),
    Params(Value),
}

/// Apply an action list to every image in a directory
///
/// A Photoshop Actions file (.atn) is a set: its action --action names plays, as below. JSON steps
/// are [id, params] pairs, {"command": id, "params": {…}} objects or bare ids, as a recorded
/// action or droplet stores them (a list, or wrapped in {"actions": …}, {"steps": …} or a
/// droplet). An Actions set (the Actions panel's actions.json, {"actions": [{"name", "steps"}…]})
/// plays the action --action names (needed when the set holds more than one) with the whole set
/// loaded, so its steps can play other actions of the set.
#[derive(Args)]
pub(crate) struct BatchArgs {
    /// The action list: actions.json, a droplet, or a Photoshop Actions file (.atn)
    #[arg(long, value_name = "FILE")]
    pub(crate) actions: PathBuf,
    /// Which action of an Actions set to play
    #[arg(long, value_name = "NAME")]
    pub(crate) action: Option<String>,
    /// The folder of images to process
    #[arg(long = "in", value_name = "DIR")]
    pub(crate) in_dir: PathBuf,
    /// The folder to write the results to, as <stem>.<ext>
    #[arg(long, value_name = "DIR")]
    pub(crate) out: PathBuf,
    /// An --out folder that is the --in folder is refused, as the results would replace the
    /// originals; --in-place allows it
    #[arg(long)]
    pub(crate) in_place: bool,
    /// Include images in subfolders; every result goes straight into --out, so a later file of
    /// the same name replaces an earlier one
    #[arg(long)]
    pub(crate) recursive: bool,
    /// Name each result with Batch tokens such as {name}, {serial}, {date}, and {ext}
    #[arg(long, value_name = "TEMPLATE")]
    pub(crate) naming: Option<String>,
    /// First serial number used by --naming
    #[arg(long, value_name = "1-4294967295", value_parser = clap::value_parser!(u32).range(1..))]
    pub(crate) start_serial: Option<u32>,
    /// Stop after the first failed input
    #[arg(long)]
    pub(crate) stop_on_error: bool,
    /// Write failed inputs and reasons to this text file
    #[arg(long, value_name = "FILE")]
    pub(crate) error_log: Option<PathBuf>,
    /// Explicitly approve high-memory PSD/PSB imports within the hard memory budget
    #[arg(long)]
    pub(crate) approve_high_memory: bool,
    #[command(flatten)]
    pub(crate) gpu: GpuArgs,
    #[command(flatten)]
    pub(crate) export: ExportArgs,
}

/// Run a droplet (File › Automate › Create Droplet) on images and folders
#[derive(Args)]
pub(crate) struct DropletArgs {
    /// The droplet to run
    #[arg(value_name = "FILE.pcdroplet")]
    pub(crate) file: String,
    /// Images and folders to run it on
    #[arg(value_name = "FILE-OR-DIR", required = true)]
    pub(crate) inputs: Vec<String>,
    /// The folder to write the results to
    #[arg(long, value_name = "DIR")]
    pub(crate) out: Option<String>,
}

/// List the engine command registry
#[derive(Args)]
pub(crate) struct CommandsArgs {
    /// Print the entries as JSON
    #[arg(long)]
    pub(crate) json: bool,
    /// Only the commands matching this text
    #[arg(long, value_name = "TEXT", allow_negative_numbers = true)]
    pub(crate) filter: Option<String>,
}

/// Run the MCP server on stdio: in the open PhotoCraft window when the person lets agents use it
/// (ArtCraft Launcher › Settings › AI agents), otherwise headless
///
/// The open window is found again on every call, with no port or token to configure. Without
/// the person's consent, or with --headless, it runs headless: each automation root grants that
/// direction of file access; an omitted root denies it. Prefer absolute root paths in MCP client
/// configurations. Bridge (--bridge or PHOTOCRAFT_CONTROL_PORT): a running `photocraft --control
/// <port>`; set the roots on the desktop app, root flags are refused, and the token flags require
/// it.
#[derive(Args)]
pub(crate) struct McpArgs {
    /// Always work headless, without the open window
    #[arg(long, conflicts_with = "when_closed")]
    pub(crate) headless: bool,
    /// While agents may use PhotoCraft but it is closed: start it, serve a headless session, or
    /// fail (default: the app's When PhotoCraft Is Closed setting)
    #[arg(long, value_name = "launch|headless|error", value_parser = when_closed)]
    pub(crate) when_closed: Option<photocraft_engine::prefs::WhenAppClosed>,
    /// Bridge to the PhotoCraft app listening here instead of a headless engine; a bare port means
    /// 127.0.0.1:<PORT>
    #[arg(long, value_name = "127.0.0.1:PORT", env = "PHOTOCRAFT_CONTROL_PORT", value_parser = bridge)]
    pub(crate) bridge: Option<Bridge>,
    /// `--bridge` came from PHOTOCRAFT_CONTROL_PORT, set by [`parse`].
    #[arg(skip)]
    pub(crate) bridge_from_env: bool,
    #[command(flatten)]
    pub(crate) gpu: GpuArgs,
    #[command(flatten)]
    pub(crate) control: ControlArgs,
    #[command(flatten)]
    pub(crate) automation: AutomationArgs,
}

/// Keep one headless session open and answer JSON lines on stdio, or on 127.0.0.1:<PORT>
///
/// Each request is a JSON line {"id", "method", "params"}. Methods: engine.execute,
/// jobs.list/cancel, engine.commands,
/// doc.open/new/place/save/exportLayers/exportDataSets/importDataSets/inspect/render/select/close,
/// session.list, batch, methods (docs/control-protocol.md#headless-server). The token flags require
/// --port (or PHOTOCRAFT_CONTROL_PORT); stdio needs no control token.
#[derive(Args)]
pub(crate) struct ServeArgs {
    /// Listen on 127.0.0.1:<PORT> instead of stdio
    #[arg(long, value_name = "PORT", env = "PHOTOCRAFT_CONTROL_PORT", value_parser = control_port)]
    pub(crate) port: Option<u16>,
    /// `--port` came from PHOTOCRAFT_CONTROL_PORT, set by [`parse`].
    #[arg(skip)]
    pub(crate) port_from_env: bool,
    #[command(flatten)]
    pub(crate) gpu: GpuArgs,
    #[command(flatten)]
    pub(crate) control: ControlArgs,
    #[command(flatten)]
    pub(crate) automation: AutomationArgs,
}

/// Why a value was refused: clap prints it after the flag and its value (exit 2).
#[derive(Debug, thiserror::Error)]
enum ValueError {
    #[error("expected 24 or 32")]
    TgaBits,
    #[error("expected 8, 10, 12 or 16")]
    DpxBits,
    #[error("expected none, bc1, bc2 or bc3")]
    DdsCompression,
    #[error("expected none, lzw or zip")]
    TiffCompression,
    #[error("expected baseline, optimized or progressive")]
    JpegFormat,
    #[error("expected none or all")]
    Metadata,
    #[error("expected on or off")]
    OnOff,
    #[error("expected a positive number")]
    PdfDpi,
    /// Why a `--bridge` value, or a PHOTOCRAFT_CONTROL_PORT value for `mcp`, is refused.
    #[error("expected a port, 0-65535 (--bridge also takes 127.0.0.1:<PORT>)")]
    Bridge,
    #[error("expected launch, headless or error")]
    WhenClosed,
}

/// Why `parse` refuses `mcp` or `serve` options clap accepted: clap prints it as a usage error
/// (exit 2).
#[derive(Debug, thiserror::Error)]
enum ServerOptionError {
    /// PHOTOCRAFT_CONTROL_PORT holds a port, as for the desktop app's --control: only the flag
    /// takes host:port.
    #[error("invalid value '{0}' for 'PHOTOCRAFT_CONTROL_PORT': {bridge}", bridge = ValueError::Bridge)]
    BridgeVar(String),
    /// With --bridge the roots are the desktop process's to set: accepting them here promises
    /// authority the bridge can't give (#8035).
    #[error("configure automation roots on the desktop app; --automation-read-root and --automation-write-root require headless MCP mode")]
    BridgeRoots,
    /// Invalid value for PHOTOCRAFT_GPU.
    #[error("invalid value '{0}' for 'PHOTOCRAFT_GPU': expected '1' or '0'")]
    GpuVar(String),
    /// Explicit GPU flags require headless MCP mode, not bridge mode.
    #[error("configure rendering on the desktop app; --gpu and --no-gpu require headless MCP mode")]
    BridgeGpu,
    /// A token flag without the bridge or port that reads it would be ignored (#8035).
    #[error("{flag} requires {transport}")]
    NeedsTransport { flag: &'static str, transport: &'static str },
    /// `--headless` never reaches an app.
    #[error("--headless works without the app; {0} is for --bridge")]
    HeadlessBridge(&'static str),
    /// `--when-closed` is about the open app, which a bridge names itself.
    #[error("--when-closed is for the open window; --bridge names the app itself")]
    BridgeWhenClosed,
}

impl ServerOptionError {
    fn into_clap(self, cmd: &mut clap::Command) -> clap::Error {
        let kind = match self {
            Self::BridgeVar(_) | Self::GpuVar(_) => ErrorKind::ValueValidation,
            Self::BridgeRoots | Self::BridgeGpu | Self::HeadlessBridge(_) | Self::BridgeWhenClosed => ErrorKind::ArgumentConflict,
            Self::NeedsTransport { .. } => ErrorKind::MissingRequiredArgument,
        };
        cmd.error(kind, self)
    }
}

fn tga_bits(s: &str) -> Result<TgaBits, ValueError> {
    s.parse().ok().and_then(TgaBits::from_bits).ok_or(ValueError::TgaBits)
}

fn dpx_bits(s: &str) -> Result<DpxBits, ValueError> {
    s.parse().ok().and_then(DpxBits::from_bits).ok_or(ValueError::DpxBits)
}

fn dds_compression(s: &str) -> Result<DdsCompression, ValueError> {
    DdsCompression::from_name(s).ok_or(ValueError::DdsCompression)
}

fn tiff_compression(s: &str) -> Result<TiffCompression, ValueError> {
    match s {
        "none" => Ok(TiffCompression::None),
        "lzw" => Ok(TiffCompression::Lzw),
        "zip" => Ok(TiffCompression::Deflate),
        _ => Err(ValueError::TiffCompression),
    }
}

fn when_closed(s: &str) -> Result<photocraft_engine::prefs::WhenAppClosed, ValueError> {
    photocraft_engine::prefs::WhenAppClosed::parse(s).ok_or(ValueError::WhenClosed)
}

fn on_off(s: &str) -> Result<bool, ValueError> {
    match s {
        "on" => Ok(true),
        "off" => Ok(false),
        _ => Err(ValueError::OnOff),
    }
}

/// A PDF import DPI: a finite number greater than zero. The importer's fallback to 300 DPI is
/// for absent preferences, not for a mistyped flag.
fn pdf_dpi(s: &str) -> Result<f32, ValueError> {
    s.parse::<f32>().ok().filter(|dpi| dpi.is_finite() && *dpi > 0.0).ok_or(ValueError::PdfDpi)
}

fn jpeg_format(s: &str) -> Result<JpegFormat, ValueError> {
    JpegFormat::parse(s).ok_or(ValueError::JpegFormat)
}

fn metadata(s: &str) -> Result<XmpEmbed, ValueError> {
    match s {
        "none" => Ok(XmpEmbed::None),
        "all" => Ok(XmpEmbed::All),
        _ => Err(ValueError::Metadata),
    }
}

/// Where `mcp --bridge` connects. Shown as the address: `127.0.0.1:<PORT>` for a port.
#[derive(Clone)]
pub(crate) enum Bridge {
    /// A bare port: the app on 127.0.0.1.
    Port(u16),
    /// `host:port`, as given. Whether the host is loopback is the bridge's to say.
    Addr(String),
}

impl fmt::Display for Bridge {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Bridge::Port(port) => SocketAddr::from((Ipv4Addr::LOCALHOST, *port)).fmt(f),
            Bridge::Addr(addr) => f.write_str(addr),
        }
    }
}

/// `mcp --bridge`, or PHOTOCRAFT_CONTROL_PORT, which holds a port.
fn bridge(s: &str) -> Result<Bridge, ValueError> {
    match control_port(s) {
        Ok(port) => Ok(Bridge::Port(port)),
        Err(_) if s.contains(':') => Ok(Bridge::Addr(s.to_owned())),
        Err(_) => Err(ValueError::Bridge),
    }
}

/// `--new` and `--params`: bad JSON is a usage error, before any work. Whether the value is an
/// object is the command's to say.
fn json(s: &str) -> Result<Value, serde_json::Error> {
    serde_json::from_str(s)
}

/// `--cmd` and `--params` values back in command-line order: clap keeps each flag's values apart,
/// their indices say how they interleave.
fn steps(m: &ArgMatches) -> Vec<Step> {
    let mut steps: Vec<(usize, Step)> = Vec::new();
    if let (Some(at), Ok(Some(ids))) = (m.indices_of("cmd"), m.try_get_many::<String>("cmd")) {
        steps.extend(at.zip(ids).map(|(i, id)| (i, Step::Cmd(id.clone()))));
    }
    if let (Some(at), Ok(Some(params))) = (m.indices_of("params"), m.try_get_many::<Value>("params")) {
        steps.extend(at.zip(params).map(|(i, p)| (i, Step::Params(p.clone()))));
    }
    steps.sort_by_key(|s| s.0);
    steps.into_iter().map(|(_, s)| s).collect()
}

/// Parse the arguments (without the binary name). clap reads them as `OsString`s: a path need not
/// be valid Unicode (#1108), text must. A flag left out falls back to its environment variable,
/// unless that is empty, and a bad value from one is a usage error naming the variable (#2491). A
/// bare `--help` or `-h` is help even after a mistake on the same line (`--out --help`, `mcp
/// stray.psd --help`): clap reports the mistake first.
pub(crate) fn parse(args: &[OsString]) -> Result<Cli, clap::Error> {
    let mut cmd = Cli::command().mut_subcommands(|sub| sub.mut_args(blank_env_is_unset));
    // `mcp --headless` reaches no app: a PHOTOCRAFT_CONTROL_PORT exported for another tool is not
    // read, so a value it couldn't use anyway doesn't stop it.
    if args.first().is_some_and(|a| a == "mcp") && args.iter().take_while(|a| *a != "--").any(|a| a == "--headless") {
        cmd = cmd.mut_subcommand("mcp", |sub| sub.mut_arg("bridge", |arg| arg.env(None::<&str>)));
    }
    let argv = std::iter::once(OsString::from("photocraft-cli")).chain(args.iter().cloned());
    let matches = match cmd.try_get_matches_from_mut(argv) {
        Err(e) if args.iter().take_while(|a| *a != "--").any(|a| *a == "--help" || *a == "-h") => {
            let help = [OsString::from("photocraft-cli"), args.first().cloned().unwrap_or_default(), OsString::from("--help")];
            return Err(cmd.try_get_matches_from_mut(help).err().unwrap_or(e));
        }
        matches => matches.map_err(|e| name_env_vars(e, &cmd, args))?,
    };
    let mut cli = Cli::from_arg_matches(&matches)?;
    let from_env = |m: &ArgMatches, id: &str| m.value_source(id) == Some(ValueSource::EnvVariable);
    match (&mut cli.command, matches.subcommand()) {
        (Command::Run(r), Some((_, m))) => {
            r.steps = steps(m);
            check_gpu_env(&mut cmd, m)?;
        }
        (Command::Mcp(a), Some((name, m))) => {
            if a.headless {
                // `--headless` reaches no app. Given on the command line, the bridge's flags
                // conflict; exported for another tool, they are left alone.
                for (id, flag) in [("bridge", "--bridge"), ("control_token", "--control-token"), ("control_token_file", "--control-token-file")] {
                    if m.value_source(id) == Some(ValueSource::CommandLine) {
                        if let Some(sub) = cmd.find_subcommand_mut(name) {
                            return Err(ServerOptionError::HeadlessBridge(flag).into_clap(sub));
                        }
                        return Err(ServerOptionError::HeadlessBridge(flag).into_clap(&mut cmd));
                    }
                }
                a.bridge = None;
                check_gpu_env(&mut cmd, m)?;
                return Ok(cli);
            }
            a.bridge_from_env = from_env(m, "bridge");
            if a.bridge_from_env
                && let Some(Bridge::Addr(v)) = &a.bridge
            {
                return Err(ServerOptionError::BridgeVar(v.clone()).into_clap(&mut cmd));
            }
            if let Some(sub) = cmd.find_subcommand_mut(name) {
                // Only the bridge reads a token, so a stale exported pair doesn't stop a headless
                // run.
                if a.bridge.is_some() {
                    conflict(sub, m, "control_token", "control_token_file")?;
                }
                // The roots are the headless engine's: the variable switching to the bridge would
                // drop them, and the error names it.
                if a.bridge_from_env {
                    conflict(sub, m, "automation_read_root", "bridge")?;
                    conflict(sub, m, "automation_write_root", "bridge")?;
                }
                if a.bridge.is_some() && (!a.automation.automation_read_root.is_empty() || a.automation.automation_write_root.is_some()) {
                    return Err(ServerOptionError::BridgeRoots.into_clap(sub));
                }
                if a.bridge.is_some() && (m.value_source("gpu") == Some(ValueSource::CommandLine) || m.value_source("no_gpu") == Some(ValueSource::CommandLine))
                {
                    return Err(ServerOptionError::BridgeGpu.into_clap(sub));
                }
                check_server(sub, m, a.bridge.is_some(), "--bridge")?;
                if a.bridge.is_some() && a.when_closed.is_some() {
                    return Err(ServerOptionError::BridgeWhenClosed.into_clap(sub));
                }
            }
            if a.bridge.is_none() {
                check_gpu_env(&mut cmd, m)?;
            }
        }
        (Command::Serve(a), Some((name, m))) => {
            a.port_from_env = from_env(m, "port");
            if let Some(sub) = cmd.find_subcommand_mut(name) {
                // Only the TCP server reads a token, so a stale exported pair doesn't stop stdio.
                if a.port.is_some() {
                    conflict(sub, m, "control_token", "control_token_file")?;
                }
                check_server(sub, m, a.port.is_some(), "--port")?;
            }
            check_gpu_env(&mut cmd, m)?;
        }
        (Command::Convert(_), Some((_, m))) | (Command::Batch(_), Some((_, m))) => {
            check_gpu_env(&mut cmd, m)?;
        }
        _ => {}
    }
    Ok(cli)
}

fn check_gpu_env(cmd: &mut clap::Command, m: &ArgMatches) -> Result<(), clap::Error> {
    if m.value_source("gpu") == Some(ValueSource::CommandLine) || m.value_source("no_gpu") == Some(ValueSource::CommandLine) {
        return Ok(());
    }
    if let Some(v) = std::env::var_os("PHOTOCRAFT_GPU") {
        // A non-UTF-8 value is still a value other than empty, "0" or "1": reject it rather
        // than silently treating it as unset and running on the CPU.
        let v = v.to_string_lossy();
        let trimmed = v.trim();
        if !trimmed.is_empty() && trimmed != "1" && trimmed != "0" {
            return Err(ServerOptionError::GpuVar(trimmed.to_string()).into_clap(cmd));
        }
    }
    Ok(())
}

/// Refuse a token flag without the bridge or port that reads it (as a flag or its variable). A
/// token variable alone may be a stale export, so it isn't refused.
fn check_server(sub: &mut clap::Command, m: &ArgMatches, has_transport: bool, transport: &'static str) -> Result<(), clap::Error> {
    for (id, flag) in [("control_token", "--control-token"), ("control_token_file", "--control-token-file")] {
        if m.value_source(id) == Some(ValueSource::CommandLine) && !has_transport {
            return Err(ServerOptionError::NeedsTransport { flag, transport }.into_clap(sub));
        }
    }
    Ok(())
}

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

    /// `--pdf-dpi` only takes a positive finite number: a mistyped value is refused at parse time
    /// instead of silently becoming the importer's 300 DPI fallback.
    #[test]
    fn pdf_dpi_rejects_non_positive_and_non_finite_values() {
        assert!(pdf_dpi("300").is_ok());
        assert!(pdf_dpi("0.5").is_ok());
        for bad in ["0", "-1", "nan", "inf", "-inf", "abc"] {
            assert!(pdf_dpi(bad).is_err(), "{bad} should be refused");
        }
    }
}