@damurka/jovian 0.1.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@damurka/jovian",
+  "version": "0.1.0",
+  "license": "MIT",
+  "author": "David Kariuki",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/damurka/jovian.git"
+  },
+  "homepage": "https://github.com/damurka/jovian#readme",
+  "bugs": {
+    "url": "https://github.com/damurka/jovian/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "description": "Supervised R and Python Jupyter kernels for Node.js and Electron, backed by native C++ processes",
+  "keywords": [
+    "r",
+    "python",
+    "jupyter",
+    "kernel",
+    "repl",
+    "data-science",
+    "electron"
+  ],
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/index.d.ts",
+      "import": "./lib/types/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.4.0"
+  },
+  "files": [
+    "lib",
+    "packages/hera",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "optionalDependencies": {
+    "@damurka/jovian-win32-x64": "0.1.0",
+    "@damurka/jovian-linux-x64": "0.1.0",
+    "@damurka/jovian-darwin-arm64": "0.1.0"
+  }
+}

package/packages/hera/DESCRIPTION

@@ -0,0 +1,29 @@
+Package: hera
+Title: Companion to the 'Elara' 'jupyter' Kernel
+Version: 0.6.0.9001
+Authors@R: c(
+    person("Romain", "François", email = "romain@tada.science", role = c("aut", "cre")), 
+    person("QuantStack", role = c("cph"))
+  )
+Description: Set of R functions to be coupled with the 'Elara' 'jupyter' kernel
+    in order to drive execution of code in notebook input cells, how R objects
+    are to be displayed in output cells, and handle two way communication
+    with the front end through comms.
+License: MIT + file LICENSE
+Encoding: UTF-8
+Roxygen: list(markdown = TRUE)
+Imports: 
+    cli,
+    evaluate,
+    glue,
+    IRdisplay,
+    jsonlite,
+    R6,
+    repr,
+    rlang,
+    tools,
+    utils
+URL: https://github.com/damurka/jovian
+BugReports: https://github.com/damurka/jovian/issues
+Config/roxygen2/version: 8.0.0
+Config/jovian/release: 0.1.0

package/packages/hera/LICENSE

@@ -0,0 +1,2 @@
+YEAR: 2025
+COPYRIGHT HOLDER: Quantstack

package/packages/hera/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2025 Quantstack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/hera/NAMESPACE

@@ -0,0 +1,32 @@
+# Generated by roxygen2: do not edit by hand
+
+S3method(mime_bundle,default)
+S3method(mime_types,default)
+S3method(mime_types,help_files_with_topic)
+S3method(mime_types,htmlwidget)
+S3method(mime_types,shiny.tag)
+S3method(mime_types,shiny.tag.list)
+export(Comm)
+export(CommManager)
+export(View)
+export(cell_options)
+export(clear_output)
+export(complete)
+export(display)
+export(display_data)
+export(is_elara)
+export(mime_bundle)
+export(mime_types)
+import(glue)
+importFrom(IRdisplay,display)
+importFrom(IRdisplay,prepare_mimebundle)
+importFrom(R6,R6Class)
+importFrom(grDevices,pdf)
+importFrom(grDevices,png)
+importFrom(jsonlite,fromJSON)
+importFrom(jsonlite,toJSON)
+importFrom(jsonlite,unbox)
+importFrom(rlang,caller_env)
+importFrom(utils,capture.output)
+importFrom(utils,head)
+importFrom(utils,tail)

package/packages/hera/NEWS.md

@@ -0,0 +1,7 @@
+# hera (development version)
+
+* Output from a single long-running expression (a loop of print() calls) now streams as it is produced instead of arriving when the expression finishes.
+
+# hera 0.1.1
+
+* Initial CRAN submission.

package/packages/hera/R/cell_options.R

@@ -0,0 +1,13 @@
+#' Options for current jupyter cell
+#'
+#' @param ... options to set locally to the notebook cell. Forwarded to [rlang::local_options()].
+#'
+#' @examples
+#' \dontrun{
+#'   cell_options(repr.plot.bg = "gray")
+#' }
+#'
+#' @export
+cell_options <- function(...) {
+    rlang::local_options(..., .frame = the$frame_cell_execute)
+}

package/packages/hera/R/comm.R

@@ -0,0 +1,228 @@
+.CommManager__register_target_callback <- function(comm, request) {
+    callback <- CommManager$target_callback(request$content$target_name)
+    callback(comm, request)
+}
+
+#' Comm Manager class
+#'
+#' @rdname CommManager
+CommManagerClass <- R6::R6Class("CommManagerClass",
+  public = list(
+
+    #' @param ... currently unused
+    #' @param error_call see [rlang::args_error_context()]
+    initialize = function(..., error_call = caller_env()) {
+      rlang::check_dots_empty(call = error_call)
+
+      private$env_targets <- new.env()
+      private$env_comms <- new.env()
+    },
+
+    #' @param target_name name of the comm target, e.g. "jupyter.widgets"
+    #' @param callback callback function taking two arguments 'comm' and 'message'.
+    register_comm_target = function(target_name, callback = function(comm, message){}) {
+        private$env_targets[[target_name]] <- callback
+        invisible(hera_dot_call("CommManager__register_target", target_name))
+    },
+
+    #' @param target_name name of the comm target
+    unregister_comm_target = function(target_name) {
+        rm(list = target_name, private$env_targets)
+        invisible(hera_dot_call("CommManager__unregister_target", target_name))
+    },
+
+    #' @param target_name name of the target
+    #' @param description description of the comm
+    new_comm = function(target_name, description = "") {
+        hera_dot_call("CommManager__new_comm", target_name, description)
+    },
+
+    #' @return the list of currently open comms
+    comms = function() {
+        as.list(private$env_comms)
+    },
+
+    #' @param target_name name of the comm target
+    #'
+    #' @return the callback for that target name
+    target_callback = function(target_name) {
+        private$env_targets[[target_name]]
+    },
+
+    #' @param comm [Comm] instance to preserve
+    preserve = function(comm) {
+        assign(comm$id, comm, envir = private$env_comms)
+    },
+
+    #' @param comm [Comm] instance to release
+    release = function(comm) {
+        rm(list = comm$id, envir = private$env_comms)
+    },
+
+    #' @param target_name name of the target to get info about all comm opens. If NULL, info for comms for all targets are returned.
+    get_comm_info = function(target_name = NULL) {
+        hera_dot_call("CommManager__get_comm_info", target_name)
+    }
+  ),
+
+  private = list(
+    env_targets = NULL,
+    env_comms = NULL
+  )
+)
+
+# set later in zzz.R
+
+#' Comm manager
+#'
+#' Instance of the [CommManagerClass] class.
+#'
+#' @export
+CommManager <- NULL
+
+#' Comm class
+#'
+#' @export
+Comm <- R6::R6Class("Comm",
+  public = list(
+
+    #' @param xp external pointer to an instance of the C++ class 'adrastea::Comm'
+    #' @param description description of this comm
+    initialize = function(xp, description = "") {
+        private$xp <- xp
+        private$description <- description
+        CommManager$preserve(self)
+    },
+
+    #' @param data data
+    #' @param metadata metadata
+    #' @param buffers list of raw vectors to send as binary buffers
+    open = function(data = NULL, metadata = NULL, buffers = list()) {
+        stopifnot(is.list(buffers), all(vapply(buffers, is.raw, logical(1))))
+        js_metadata <- enc2utf8(jsonlite::toJSON(metadata, auto_unbox = TRUE, null = if (is.null(metadata)) "list" else "null"))
+        js_data <- enc2utf8(jsonlite::toJSON(data, auto_unbox = TRUE, null = "null"))
+
+        invisible(hera_dot_call("Comm__open", private$xp, js_metadata, js_data, buffers))
+    },
+
+    #' @param data data
+    #' @param metadata metadata
+    #' @param buffers list of raw vectors to send as binary buffers
+    close = function(data = NULL, metadata = NULL, buffers = list()) {
+        stopifnot(is.list(buffers), all(vapply(buffers, is.raw, logical(1))))
+        js_metadata <- enc2utf8(jsonlite::toJSON(metadata, auto_unbox = TRUE, null = if (is.null(metadata)) "list" else "null"))
+        js_data <- enc2utf8(jsonlite::toJSON(data, auto_unbox = TRUE, null = "null"))
+
+        invisible(hera_dot_call("Comm__close", private$xp, js_metadata, js_data, buffers))
+    },
+
+    #' @param data data
+    #' @param metadata metadata
+    #' @param buffers list of raw vectors to send as binary buffers
+    send = function(data = NULL, metadata = NULL, buffers = list()) {
+        stopifnot(is.list(buffers), all(vapply(buffers, is.raw, logical(1))))
+        js_metadata <- enc2utf8(jsonlite::toJSON(metadata, auto_unbox = TRUE, null = if (is.null(metadata)) "list" else "null"))
+        js_data <- enc2utf8(jsonlite::toJSON(data, auto_unbox = TRUE, null = "null"))
+
+        invisible(hera_dot_call("Comm__send", private$xp, js_metadata, js_data, buffers))
+    },
+
+    #' @param handler function to call when the comm is closed
+    on_close = function(handler) {
+        private$close_handler <- function(request) {
+            handler(request)
+            self$finalize()
+        }
+        invisible(hera_dot_call("Comm__on_close", private$xp, private$close_handler))
+    },
+
+    #' @param handler function to call when receiving a message
+    on_message = function(handler) {
+        private$message_handler <- handler
+        invisible(hera_dot_call("Comm__on_message", private$xp, private$message_handler))
+    },
+
+    #' @return information about the comm
+    print = function() {
+      if (identical(private$description, "")) {
+        writeLines(glue("<Comm id={self$id} target_name='{self$target_name}'>"))
+      } else {
+        writeLines(glue("<Comm id={self$id} target_name='{self$target_name}' description='{private$description}' >"))
+      }
+    }
+  ),
+
+  active = list(
+
+    #' @field id
+    #' id of the comm. read only.
+    id = function() {
+        hera_dot_call("Comm__id", private$xp)
+    },
+
+    #' @field target_name
+    #' name of the target for this comm
+    target_name = function() {
+        hera_dot_call("Comm__target_name", private$xp)
+    }
+  ),
+
+  private = list(
+    xp = NULL,
+    description = "",
+    close_handler = NULL,
+    message_handler = NULL,
+
+    finalize = function() {
+      CommManager$release(self)
+    }
+  )
+)
+
+Message <- R6::R6Class("Message",
+  public = list(
+    initialize = function(xp) {
+      private$xp <- xp
+    },
+
+    print = function() {
+      print(cli::rule("$content"))
+      str(self$content)
+
+      print(cli::rule("$header"))
+      str(self$header)
+
+      print(cli::rule("$parent_header"))
+      str(self$parent_header)
+
+      print(cli::rule("$metadata"))
+      str(self$metadata)
+    }
+  ),
+
+  active = list(
+    content = function() {
+      jsonlite::fromJSON(hera_dot_call("Message__get_content", private$xp))
+    },
+
+    header = function() {
+      jsonlite::fromJSON(hera_dot_call("Message__get_header", private$xp))
+    },
+
+    parent_header = function() {
+      jsonlite::fromJSON(hera_dot_call("Message__get_parent_header", private$xp))
+    },
+
+    metadata = function() {
+      jsonlite::fromJSON(hera_dot_call("Message__get_metadata", private$xp))
+    },
+
+    buffers = function() {
+      hera_dot_call("Message__get_buffers", private$xp)
+    }
+  ),
+
+  private = list(
+    xp = NULL
+  )
+)

package/packages/hera/R/completion.R

@@ -0,0 +1,54 @@
+triple_colon <- function(pkg, fun) {
+  eval(rlang::call2(":::", as.symbol(pkg), as.symbol(fun)))
+}
+
+utils___assignLineBuffer    <- triple_colon("utils", ".assignLinebuffer")
+utils___assignEnd           <- triple_colon("utils", ".assignEnd")
+utils___guessTokenFromLine  <- triple_colon("utils", ".guessTokenFromLine")
+utils___completeToken       <- triple_colon("utils", ".completeToken")
+utils___retrieveCompletions <- triple_colon("utils", ".retrieveCompletions")
+
+#' Code completion
+#'
+#' @param code R code to complete
+#' @param cursor_pos position of the cursor
+#'
+#' @examples
+#' complete("rnorm(")
+#'
+#' @return a list that contains potential completions as the first item
+#'
+#' @export
+complete <- function(code, cursor_pos = nchar(code)) {
+    # Find which line we're on and position within that line
+    lines <- strsplit(code, '\n', fixed = TRUE)[[1]]
+    chars_before_line <- 0L
+    for (line in lines) {
+        new_cursor_pos <- cursor_pos - nchar(line) - 1L # -1 for the newline
+        if (new_cursor_pos < 0L) {
+            break
+        }
+        cursor_pos <- new_cursor_pos
+        chars_before_line <- chars_before_line + nchar(line) + 1L
+    }
+
+    # guard from errors when completion is invoked in empty cells
+    if (is.null(line)) {
+        line <- ''
+    }
+
+    utils___assignLineBuffer(line)
+    utils___assignEnd(cursor_pos)
+
+    info <- utils___guessTokenFromLine(update = FALSE)
+    utils___guessTokenFromLine()
+    utils___completeToken()
+
+    start_position <- chars_before_line + info$start
+    comps <- utils___retrieveCompletions()
+
+    list(
+      comps,
+      c(start_position, start_position + nchar(info$token))
+    )
+}

package/packages/hera/R/execute.R

@@ -0,0 +1,199 @@
+# evaluate captures stdout into a temporary file and only hands it over when a
+# top-level expression finishes (or a message/warning/plot happens), so one
+# long expression -- for (i in 1:1e6) print(i), purrr::walk(x, print) -- shows
+# nothing until it is over. Making evaluate's sink a *split* sink
+# (sink(con, split = TRUE)) tees the same output to R's console too, and the
+# console (Elara's WriteConsoleEx hook) publishes it to the client at once.
+# evaluate only does that through its debug flag, which also echoes every
+# expression's source, so the one internal function that creates the sink is
+# wrapped instead. try()'s output is redirected to the same place (evaluate
+# points it at the sink's file, which the tee does not cover).
+#
+# Returns whether the wrapper is in place; when it is not (a different
+# evaluate), output simply keeps arriving per expression, as before.
+patch_evaluate_sink <- function() {
+  ns <- asNamespace("evaluate")
+  name <- "local_persistent_sink_connection"
+  original <- get0(name, envir = ns, inherits = FALSE)
+  if (!is.function(original) || !identical(names(formals(original)), c("debug", "frame"))) {
+    return(FALSE)
+  }
+
+  patched <- function(debug = FALSE, frame = parent.frame()) {
+    tee <- isTRUE(the$tee_stdout)
+    reader <- original(debug = debug || tee, frame = frame)
+    if (tee) {
+      # evaluate saved the previous value and restores it when it finishes.
+      options(try.outFile = stdout())
+    }
+    reader
+  }
+
+  tryCatch({
+    unlockBinding(name, ns)
+    assign(name, patched, envir = ns)
+    lockBinding(name, ns)
+    TRUE
+  }, error = function(e) FALSE)
+}
+
+handle_message <- function(msg) {
+  publish_stream("stderr", conditionMessage(msg))
+}
+
+handle_warning <- function(w) {
+  call <- conditionCall(w)
+  call <- if (is.null(call)) '' else sprintf(' in %s', deparse(call)[[1]])
+  msg <- sprintf('Warning message%s:\n%s\n', call, dQuote(conditionMessage(w)))
+
+  publish_stream("stderr", msg)
+}
+
+handle_error <- function(e) {
+  if (inherits(e, "rlang_error") && isNamespaceLoaded("rlang")) {
+    assign("last_error", e, triple_colon("rlang", "the"))
+
+    the$last_error <- structure(
+      list(ename = "ERROR", evalue = "", format(e, backtrace = TRUE)),
+      class = "error_reply"
+    )
+  } else {
+    sys_calls <- sys.calls()
+    sys_calls <- head(tail(sys_calls, -16), -3)
+    stack <- capture.output(traceback(sys_calls, max.lines = 1L))
+
+    evalue <- paste(conditionMessage(e), collapse = "\n")
+    trace_back <- c(
+      cli::col_red("--- Error"),
+      evalue,
+      "",
+      cli::col_red("--- Traceback (most recent call last)"),
+      stack
+    )
+    the$last_error <- structure(list(ename = "ERROR", evalue = evalue, trace_back), class = "error_reply")
+  }
+}
+
+handle_value <- function(obj, visible) {
+  set_last_value(obj, visible)
+
+  if (visible && inherits(obj, "ggplot")) {
+    print(obj)
+    the$last_visible <- FALSE
+  }
+
+}
+
+handle_graphics <- function(plot) {
+  attr(plot, ".irkernel_width")  <- getOption('repr.plot.width' , repr::repr_option_defaults$repr.plot.width)
+  attr(plot, ".irkernel_height") <- getOption('repr.plot.height', repr::repr_option_defaults$repr.plot.height)
+  attr(plot, ".irkernel_res")    <- getOption('repr.plot.res', repr::repr_option_defaults$repr.plot.res)
+  attr(plot, ".irkernel_ppi")    <- attr(plot, ".irkernel_res") / getOption('jupyter.plot_scale', 2)
+
+  if (!plot_builds_upon(the$last_plot, plot)) {
+    send_plot(the$last_plot)
+  }
+
+  the$last_plot <- plot
+}
+
+send_plot <- function(plot) {
+  w <- attr(plot, '.irkernel_width')
+  h <- attr(plot, '.irkernel_height')
+  res <- attr(plot, ".irkernel_res")
+  ppi <- attr(plot, ".irkernel_ppi")
+
+  data <- namedlist()
+  metadata <- namedlist()
+
+  for (mime in getOption('jupyter.plot_mimetypes')) {
+    data[[mime]] <- repr::mime2repr[[mime]](plot, width = w, height = h, res = res)
+
+    if (!identical(mime, 'text/plain')) {
+      metadata[[mime]] <- list(
+          width  = w * ppi,
+          height = h * ppi
+      )
+    }
+
+    # Isolating SVGs (putting them in an iframe) avoids strange
+    # interactions with CSS on the page.
+    if (identical(mime, 'image/svg+xml')) {
+      metadata[[mime]]$isolated <- TRUE
+    }
+
+  }
+  display_data(data, metadata)
+}
+
+# currently not exported, because it is only meant to be called
+# from xeus-r / interpreter::execute_request_impl
+execute <- function(code, execution_counter, silent = FALSE, eval_env = rlang::global_env()) {
+  the$last_error <- NULL
+
+  parsed <- tryCatch(
+    parse(text = code),
+    error = function(e) {
+      msg <- paste(conditionMessage(e), collapse = "\n")
+      the$last_error <- structure(list(ename = "PARSE ERROR", evalue = msg), class = "error_reply")
+    }
+  )
+  if (!is.null(the$last_error)) return(the$last_error)
+
+  if (is.null(the$evaluate_sink_patched)) {
+    the$evaluate_sink_patched <- patch_evaluate_sink()
+  }
+  # A silent execution must not show anything, so it is not tee'd.
+  the$tee_stdout <- !silent && isTRUE(the$evaluate_sink_patched)
+
+  output_handler <- if (silent) {
+    evaluate::new_output_handler()
+  } else {
+    evaluate::new_output_handler(
+      # With the tee on, stdout was already published live from the console.
+      text = if (the$tee_stdout) function(txt) NULL else function(txt) publish_stream("stdout", txt),
+      graphics = handle_graphics,
+      message = handle_message,
+      warning = handle_warning,
+      error = handle_error,
+      value = handle_value
+    )
+  }
+
+  the$last_plot <- NULL
+  the$last_visible <- FALSE
+
+  filename <- glue("[{execution_counter}]")
+
+  the$frame_cell_execute <- environment()
+  evaluate::evaluate(
+    code,
+    envir = eval_env,
+    output_handler = output_handler,
+    stop_on_error = 1L,
+    filename = filename
+  )
+  if (!is.null(the$last_error)) return(the$last_error)
+
+  if (!silent && !is.null(the$last_plot)) {
+    tryCatch(send_plot(the$last_plot), error = handle_error)
+  }
+  if (!is.null(the$last_error)) return(the$last_error)
+
+  if (isTRUE(the$last_visible)) {
+    obj <- .Last.value
+
+    bundle <- mime_bundle(obj)
+
+    structure(class = "execution_result",
+      list(
+        # data     = toJSON(bundle$data, auto_unbox = TRUE),
+        # metadata = toJSON(bundle$metadata, auto_unbox = TRUE)
+        # Before toJSON, ensure data is UTF-8
+        data = enc2utf8(toJSON(sanitize_raw_for_json(bundle$data), auto_unbox = TRUE)),
+        metadata = enc2utf8(toJSON(bundle$metadata, auto_unbox = TRUE))
+      )
+    )
+  }
+
+}