Improve error messages with paths and actionable hints

Reworks cli_abort/cli_warn calls so users see the offending value and a
specific fix: config validator names the bad field and file to edit,
cache_remove shows an example invocation, multi-app field errors include
an example apps: list, platform detection and backend resolver list valid
values, run.R electron-script errors show the full path and a snippet,
brand.yml parse error names the file, install.R lists supported archive
formats, nodejs checksum warning names the file.

Author: coatless

R/backend-resolve.R

@@ -11,7 +11,11 @@ resolve_backend_module <- function(app_type, runtime_strategy) {
       if (grepl("^r-", app_type)) "native-r.js" else "native-py.js"
     },
     "container" = "container.js",
-    cli::cli_abort("Unknown runtime strategy: {.val {runtime_strategy}}")
+    cli::cli_abort(c(
+      "Unknown runtime strategy: {.val {runtime_strategy}}",
+      "i" = "Valid strategies: {.val {c('system', 'bundled', 'auto-download', 'container', 'shinylive')}}",
+      "i" = "Set in {.arg runtime_strategy} or {.field build.runtime_strategy} in {.file _shinyelectron.yml}"
+    ))
   )
 }
 

R/cache.R

@@ -266,7 +266,11 @@ cache_remove <- function(runtime, version, platform = NULL, arch = NULL) {
     target <- fs::path(dir, "nodejs", version)
   } else {
     if (is.null(platform) || is.null(arch)) {
-      cli::cli_abort("Both {.arg platform} and {.arg arch} are required for {.val {runtime}}")
+      cli::cli_abort(c(
+        "Both {.arg platform} and {.arg arch} are required to remove {.val {runtime}}",
+        "i" = "Example: {.code cache_remove(\"{runtime}\", \"{version}\", \"mac\", \"arm64\")}",
+        "i" = "Run {.code cache_info()} to list available versions"
+      ))
     }
     target <- fs::path(dir, runtime, platform, arch, version)
   }

R/config.R

@@ -189,27 +189,42 @@ validate_config <- function(config) {
   default_height <- SHINYELECTRON_DEFAULTS$window_height
 
   if (!is.null(config$window$width) && (!is.numeric(config$window$width) || config$window$width < 100)) {
-    cli::cli_warn("Invalid window width in config, using default: {default_width}")
+    cli::cli_warn(c(
+      "Invalid {.field window.width} in config: {.val {config$window$width}}",
+      "i" = "Must be a number >= 100; using default: {.val {default_width}}",
+      "i" = "Edit {.field window.width} in {.file _shinyelectron.yml}"
+    ))
     config$window$width <- default_width
   }
   if (!is.null(config$window$height) && (!is.numeric(config$window$height) || config$window$height < 100)) {
-    cli::cli_warn("Invalid window height in config, using default: {default_height}")
+    cli::cli_warn(c(
+      "Invalid {.field window.height} in config: {.val {config$window$height}}",
+      "i" = "Must be a number >= 100; using default: {.val {default_height}}",
+      "i" = "Edit {.field window.height} in {.file _shinyelectron.yml}"
+    ))
     config$window$height <- default_height
   }
 
   # Validate port using centralized default
   default_port <- SHINYELECTRON_DEFAULTS$server_port
   if (!is.null(config$server$port)) {
     if (!is.numeric(config$server$port) || config$server$port < 1 || config$server$port > 65535) {
-      cli::cli_warn("Invalid port in config, using default: {default_port}")
+      cli::cli_warn(c(
+        "Invalid {.field server.port} in config: {.val {config$server$port}}",
+        "i" = "Must be an integer between 1 and 65535; using default: {.val {default_port}}",
+        "i" = "Edit {.field server.port} in {.file _shinyelectron.yml}"
+      ))
       config$server$port <- default_port
     }
   }
 
   # Validate splash settings
   if (!is.null(config$splash)) {
     if (!is.null(config$splash$duration) && (!is.numeric(config$splash$duration) || config$splash$duration < 0)) {
-      cli::cli_warn("Invalid splash duration, using default: 3000")
+      cli::cli_warn(c(
+        "Invalid {.field splash.duration} in config: {.val {config$splash$duration}}",
+        "i" = "Must be a non-negative number (milliseconds); using default: {.val {SHINYELECTRON_DEFAULTS$splash$duration}}"
+      ))
       config$splash$duration <- SHINYELECTRON_DEFAULTS$splash$duration
     }
   }
@@ -614,7 +629,12 @@ read_brand_yml <- function(appdir) {
   tryCatch(
     yaml::read_yaml(brand_file),
     error = function(e) {
-      cli::cli_warn(c("Failed to parse {.file _brand.yml}", "x" = "Error: {e$message}", "i" = "Using default branding"))
+      cli::cli_warn(c(
+        "Failed to parse {.file {brand_file}}",
+        "x" = "{e$message}",
+        "i" = "Check YAML syntax and indentation",
+        "i" = "Using default branding"
+      ))
       NULL
     }
   )

R/install-nodejs.R

@@ -123,7 +123,11 @@ nodejs_verify_checksum <- function(file_path, expected_checksum) {
   actual_checksum <- compute_sha256(file_path)
 
   if (is.null(actual_checksum)) {
-    cli::cli_warn("Could not verify checksum")
+    cli::cli_warn(c(
+      "Could not compute SHA-256 for {.file {basename(file_path)}}",
+      "i" = "Integrity check skipped; install continuing",
+      "i" = "If the install behaves oddly, remove {.path {dirname(file_path)}} and retry"
+    ))
     return(TRUE)  # Don't fail if verification unavailable
   }
 

R/install.R

@@ -61,7 +61,10 @@ download_and_extract_portable_tool <- function(label, version, install_path,
     } else if (ext == "zip") {
       utils::unzip(temp_file, exdir = install_path)
     } else {
-      cli::cli_abort("Unsupported archive extension: {.val {ext}}")
+      cli::cli_abort(c(
+        "Unsupported archive extension: {.val {ext}}",
+        "i" = "Supported formats: {.val {c('gz', 'zip')}}"
+      ))
     }
   }, error = function(e) {
     unlink(install_path, recursive = TRUE)

R/run.R

@@ -54,12 +54,19 @@ run_electron_app <- function(app_dir, port = 3000, open_devtools = TRUE, verbose
   # Check if package.json exists and has necessary scripts
   package_json_path <- fs::path(app_dir, "package.json")
   if (!fs::file_exists(package_json_path)) {
-    cli::cli_abort("No package.json found in: {.path {app_dir}}")
+    cli::cli_abort(c(
+      "No {.file package.json} found in {.path {app_dir}}",
+      "i" = "Run {.code export()} first to build the Electron project"
+    ))
   }
 
   package_json <- jsonlite::fromJSON(package_json_path, simplifyVector = FALSE)
   if (is.null(package_json$scripts$electron)) {
-    cli::cli_abort("No 'electron' script found in package.json")
+    cli::cli_abort(c(
+      "No {.val electron} script in {.file {package_json_path}}",
+      "i" = "Add one under {.field scripts}: {.code \"electron\": \"electron .\"}",
+      "i" = "Or re-run {.code export()} to regenerate {.file package.json}"
+    ))
   }
 
   # Set environment variables

R/utils.R

@@ -8,7 +8,11 @@ detect_current_platform <- function() {
          "Windows" = "win",
          "Darwin" = "mac",
          "Linux" = "linux",
-         cli::cli_abort("Unsupported platform: {sysname}")
+         cli::cli_abort(c(
+           "Unsupported platform: {.val {sysname}}",
+           "i" = "shinyelectron supports Windows, macOS, and Linux",
+           "i" = "Report this at {.url https://github.com/coatless-rpkg/shinyelectron/issues}"
+         ))
   )
 }
 

R/validate-app-type.R

@@ -88,16 +88,27 @@ validate_multi_app_config <- function(config, basedir) {
   apps <- config$apps
 
   # Check for required fields
+  example_hint <- "Example: {.code apps: [{ id: 'dashboard', name: 'Dashboard', path: './src/dashboard' }]}"
   for (i in seq_along(apps)) {
     app <- apps[[i]]
     if (is.null(app$id) || !nzchar(app$id)) {
-      cli::cli_abort("App entry {i} is missing required {.field id}")
+      cli::cli_abort(c(
+        "Multi-app config entry {i} is missing required {.field id}",
+        "i" = "Each app must have: {.field id}, {.field name}, {.field path}",
+        "i" = example_hint
+      ))
     }
     if (is.null(app$name) || !nzchar(app$name)) {
-      cli::cli_abort("App entry {i} ({app$id}) is missing required {.field name}")
+      cli::cli_abort(c(
+        "Multi-app config entry {i} ({.val {app$id}}) is missing required {.field name}",
+        "i" = example_hint
+      ))
     }
     if (is.null(app$path) || !nzchar(app$path)) {
-      cli::cli_abort("App entry {i} ({app$id}) is missing required {.field path}")
+      cli::cli_abort(c(
+        "Multi-app config entry {i} ({.val {app$id}}) is missing required {.field path}",
+        "i" = example_hint
+      ))
     }
   }