///|
/// Returns the shared unsupported-platform error message.
fn unsupported_error_message() -> String {
  "shell package currently supports Windows native builds only"
}

///|
/// Returns `true` when the current native target has a shell backend that
/// this package knows how to call.
pub fn is_supported() -> Bool {
  is_supported_ffi()
}

///|
/// Verifies that the current native platform is supported by this package.
///
/// Returns `Ok(())` on supported platforms and an explanatory `Err(String)` on
/// unsupported targets.
pub fn ensure_supported() -> Result[Unit, String] {
  if is_supported() {
    Ok(())
  } else {
    Err(unsupported_error_message())
  }
}

///|
/// Opens `target` through the native shell.
///
/// On Windows this calls `ShellExecuteW` with the `"open"` verb. Returns
/// `Ok(())` on success or `Err(String)` on unsupported platforms or launch
/// failures.
pub fn open(target : String) -> Result[Unit, String] {
  if !is_supported() {
    return Err(unsupported_error_message())
  }
  if open_ffi(@ffi.to_wstr(target)) {
    Ok(())
  } else {
    Err("shell.open failed")
  }
}

///|
/// Reveals `path` in the native file manager.
///
/// On Windows this opens Explorer with `/select,""`. Returns `Ok(())`
/// on success or `Err(String)` on unsupported platforms or launch failures.
pub fn reveal_item(path : String) -> Result[Unit, String] {
  if !is_supported() {
    return Err(unsupported_error_message())
  }
  if reveal_item_ffi(@ffi.to_wstr(path)) {
    Ok(())
  } else {
    Err("shell.revealItem failed")
  }
}