rclnodejs 1.8.3 → 1.9.0

package/scripts/run_asan_test.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# Run tests with AddressSanitizer (ASan/LSan) to detect memory leaks and errors
+# in the native N-API addon.
+#
+# Requires: ROS2 sourced, g++ with libasan
+#
+# Usage:
+#   bash scripts/run_asan_test.sh                        # rebuild + run all tests
+#   bash scripts/run_asan_test.sh test/test-node.js      # rebuild + run specific test(s)
+#   bash scripts/run_asan_test.sh --no-build test/test-node.js  # skip rebuild
+#   bash scripts/run_asan_test.sh --exclude test/test-serialization.js  # exclude specific test(s)
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$PROJECT_DIR"
+
+# Parse flags
+DO_BUILD=1
+ARGS=()
+EXCLUDES=()
+NEXT_IS_EXCLUDE=0
+for arg in "$@"; do
+  if [[ $NEXT_IS_EXCLUDE -eq 1 ]]; then
+    EXCLUDES+=("$arg")
+    NEXT_IS_EXCLUDE=0
+  elif [[ "$arg" == "--no-build" ]]; then
+    DO_BUILD=0
+  elif [[ "$arg" == "--exclude" ]]; then
+    NEXT_IS_EXCLUDE=1
+  else
+    ARGS+=("$arg")
+  fi
+done
+
+if [[ $NEXT_IS_EXCLUDE -eq 1 ]]; then
+  echo "Error: --exclude requires a test file argument"
+  echo "Usage: bash scripts/run_asan_test.sh --exclude test/test-foo.js"
+  exit 1
+fi
+
+# Step 1: Build with ASan
+if [[ $DO_BUILD -eq 1 ]]; then
+  echo "=== Building with AddressSanitizer ==="
+  CXXFLAGS="-fsanitize=address" npx node-gyp -j 16 rebuild --debug
+fi
+
+# Step 2: Locate libasan
+LIBASAN=$(g++ -print-file-name=libasan.so)
+if [[ "$LIBASAN" == "libasan.so" ]]; then
+  # g++ returned just the name, try to find the full path
+  LIBASAN=$(find /usr/lib* -name "libasan.so*" -type f 2>/dev/null | head -1)
+fi
+
+if [[ -z "$LIBASAN" || ! -f "$LIBASAN" ]]; then
+  echo "Warning: Could not find libasan.so, proceeding without LD_PRELOAD"
+  echo "If you see 'ASan not the first DSO' errors, install libasan: sudo apt install libasan6"
+  LIBASAN=""
+fi
+
+# Step 3: Set up environment
+export LSAN_OPTIONS="suppressions=$PROJECT_DIR/suppr.txt"
+if [[ -n "$LIBASAN" ]]; then
+  export LD_PRELOAD="$LIBASAN"
+fi
+
+# Step 3.5: Temporarily hide prebuilds so the debug build is loaded
+PREBUILDS_DIR="$PROJECT_DIR/prebuilds"
+PREBUILDS_BAK="$PROJECT_DIR/.prebuilds_asan_bak"
+MOVED_PREBUILDS=0
+if [[ -d "$PREBUILDS_DIR" ]]; then
+  if [[ -d "$PREBUILDS_BAK" ]]; then
+    echo "Error: $PREBUILDS_BAK already exists (previous interrupted run?)."
+    echo "Please remove it manually and retry: rm -rf $PREBUILDS_BAK"
+    exit 1
+  fi
+  mv "$PREBUILDS_DIR" "$PREBUILDS_BAK"
+  MOVED_PREBUILDS=1
+fi
+
+# Restore prebuilds on exit (even on failure)
+cleanup() {
+  if [[ $MOVED_PREBUILDS -eq 1 && -d "$PREBUILDS_BAK" ]]; then
+    mv "$PREBUILDS_BAK" "$PREBUILDS_DIR"
+  fi
+}
+trap cleanup EXIT
+
+# Step 4: Build mocha exclude args from --exclude flags, blocklist.json, and asan_blocklist.json
+MOCHA_EXCLUDES=()
+for exc in "${EXCLUDES[@]}"; do
+  MOCHA_EXCLUDES+=(--ignore "$exc")
+done
+
+# Auto-exclude tests from blocklist.json (Linux entries) and asan_blocklist.json
+for blocklist in "$PROJECT_DIR/test/blocklist.json" "$PROJECT_DIR/test/asan_blocklist.json"; do
+  if [[ -f "$blocklist" ]]; then
+    while IFS= read -r test_file; do
+      MOCHA_EXCLUDES+=(--ignore "test/$test_file")
+    done < <(node -e "
+      const bl = require('$blocklist');
+      const entries = bl.Linux || bl;
+      if (Array.isArray(entries)) entries.forEach(t => console.log(t));
+    " 2>/dev/null)
+  fi
+done
+
+# Step 5: Run tests
+if [[ ${#ARGS[@]} -gt 0 ]]; then
+  echo "=== Running ASan test: ${ARGS[*]} ==="
+  node --expose-gc node_modules/.bin/mocha -r test/gc-on-exit.js "${MOCHA_EXCLUDES[@]}" "${ARGS[@]}"
+else
+  echo "=== Running all ASan tests ==="
+  node --expose-gc node_modules/.bin/mocha -r test/gc-on-exit.js "${MOCHA_EXCLUDES[@]}" 'test/test-*.js'
+fi
+
+echo "=== ASan test complete ==="

package/src/executor.cpp

@@ -48,7 +48,8 @@ Executor::Executor(Napi::Env env, HandleManager* handle_manager,
       handle_manager_(handle_manager),
       delegate_(delegate),
       context_(nullptr),
-      env_(env) {
+      env_(env),
+      work_pending_(false) {
   running_.store(false);
 }
 
@@ -105,6 +106,8 @@ void Executor::Stop() {
     // Stop thread first, and then uv_close
     // Make sure async_ is not used anymore
     running_.store(false);
+    // Wake the background thread in case it is waiting on the condvar.
+    work_done_cv_.notify_all();
     handle_manager_->StopWaitingHandles();
     uv_thread_join(&background_thread_);
 
@@ -116,7 +119,7 @@ void Executor::Stop() {
                  // Important Notice:
                  //  This might be called after Executor::~Executor()
                  //  Don't free Executor::async_ in Executor's dtor
-                 delete async;
+                 delete reinterpret_cast<uv_async_t*>(async);
                  handle_closed = true;
                });
       while (!handle_closed) uv_run(uv_default_loop(), UV_RUN_ONCE);
@@ -133,6 +136,21 @@ bool Executor::IsMainThread() {
 
 void Executor::DoWork(uv_async_t* handle) {
   Executor* executor = reinterpret_cast<Executor*>(handle->data);
+
+  // RAII guard: always clear work_pending_ and notify the background thread,
+  // even if ExecuteReadyHandles() throws (e.g. from N-API callbacks).
+  // Without this, the background thread would block forever on work_done_cv_.
+  struct WorkDoneGuard {
+    Executor* exec;
+    ~WorkDoneGuard() {
+      {
+        std::lock_guard<std::mutex> lock(exec->work_done_mutex_);
+        exec->work_pending_ = false;
+      }
+      exec->work_done_cv_.notify_one();
+    }
+  } guard{executor};
+
   executor->ExecuteReadyHandles();
 }
 
@@ -159,7 +177,23 @@ void Executor::Run(void* arg) {
 
       if (!uv_is_closing(reinterpret_cast<uv_handle_t*>(executor->async_)) &&
           handle_manager->ready_handles_count() > 0) {
+        // Tell the main thread there is work to do, then wait for it to
+        // finish before re-entering rcl_wait.  This prevents a data race
+        // where the background thread holds subscriptions in the wait set
+        // while the main thread modifies their state (e.g. content filter).
+        {
+          std::lock_guard<std::mutex> lock(executor->work_done_mutex_);
+          executor->work_pending_ = true;
+        }
         uv_async_send(executor->async_);
+
+        // Wait until DoWork() signals completion.
+        {
+          std::unique_lock<std::mutex> lock(executor->work_done_mutex_);
+          executor->work_done_cv_.wait(lock, [executor] {
+            return !executor->work_pending_ || !executor->running_.load();
+          });
+        }
       }
     }
 

package/src/executor.h

@@ -20,7 +20,9 @@
 #include <uv.h>
 
 #include <atomic>
+#include <condition_variable>
 #include <exception>
+#include <mutex>
 #include <vector>
 
 #include "rcl_handle.h"
@@ -72,6 +74,15 @@ class Executor {
   Napi::Env env_;
 
   std::atomic_bool running_;
+
+  // Synchronization: the background thread waits after uv_async_send until
+  // the main thread finishes ExecuteReadyHandles.  This prevents the
+  // background thread from re-entering rcl_wait (which holds a reference to
+  // subscriptions) while the main thread modifies subscription state (e.g.
+  // content filter changes).
+  std::mutex work_done_mutex_;
+  std::condition_variable work_done_cv_;
+  bool work_pending_;  // true while the main thread is processing handles
 };
 
 }  // namespace rclnodejs

package/src/rcl_action_client_bindings.cpp

@@ -250,6 +250,67 @@ Napi::Value ActionSendCancelRequest(const Napi::CallbackInfo& info) {
   return Napi::Number::New(env, static_cast<double>(sequence_number));
 }
 
+#if ROS_VERSION >= 5000  // ROS2 Rolling
+Napi::Value ActionConfigureFeedbackSubFilterAddGoalId(
+    const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  RclHandle* action_client_handle =
+      RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_action_client_t* action_client =
+      reinterpret_cast<rcl_action_client_t*>(action_client_handle->ptr());
+
+  auto goal_id_buffer = info[1].As<Napi::Buffer<uint8_t>>();
+  const uint8_t* goal_id_array = goal_id_buffer.Data();
+  size_t goal_id_size = goal_id_buffer.Length();
+
+  rcl_ret_t ret =
+      rcl_action_client_configure_feedback_subscription_filter_add_goal_id(
+          action_client, goal_id_array, goal_id_size);
+
+  if (RCL_RET_OK != ret) {
+    std::string error_text{
+        "Failed to add goal id to feedback subscription content filter: "};
+    error_text += rcl_get_error_string().str;
+    rcl_reset_error();
+    Napi::Error::New(env, error_text).ThrowAsJavaScriptException();
+    return Napi::Boolean::New(env, false);
+  }
+
+  return Napi::Boolean::New(env, true);
+}
+
+Napi::Value ActionConfigureFeedbackSubFilterRemoveGoalId(
+    const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  RclHandle* action_client_handle =
+      RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_action_client_t* action_client =
+      reinterpret_cast<rcl_action_client_t*>(action_client_handle->ptr());
+
+  auto goal_id_buffer = info[1].As<Napi::Buffer<uint8_t>>();
+  const uint8_t* goal_id_array = goal_id_buffer.Data();
+  size_t goal_id_size = goal_id_buffer.Length();
+
+  rcl_ret_t ret =
+      rcl_action_client_configure_feedback_subscription_filter_remove_goal_id(
+          action_client, goal_id_array, goal_id_size);
+
+  if (RCL_RET_OK != ret) {
+    std::string error_text{
+        "Failed to remove goal id from feedback subscription content "
+        "filter: "};
+    error_text += rcl_get_error_string().str;
+    rcl_reset_error();
+    Napi::Error::New(env, error_text).ThrowAsJavaScriptException();
+    return Napi::Boolean::New(env, false);
+  }
+
+  return Napi::Boolean::New(env, true);
+}
+#endif  // ROS_VERSION >= 5000
+
 #if ROS_VERSION >= 2505  // ROS2 >= Kilted
 Napi::Value ConfigureActionClientIntrospection(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
@@ -307,7 +368,15 @@ Napi::Object InitActionClientBindings(Napi::Env env, Napi::Object exports) {
 #if ROS_VERSION >= 2505  // ROS2 >= Kilted
   exports.Set("configureActionClientIntrospection",
               Napi::Function::New(env, ConfigureActionClientIntrospection));
-#endif  // ROS_VERSION >= 2505
+#endif                   // ROS_VERSION >= 2505
+#if ROS_VERSION >= 5000  // ROS2 Rolling
+  exports.Set(
+      "actionConfigureFeedbackSubFilterAddGoalId",
+      Napi::Function::New(env, ActionConfigureFeedbackSubFilterAddGoalId));
+  exports.Set(
+      "actionConfigureFeedbackSubFilterRemoveGoalId",
+      Napi::Function::New(env, ActionConfigureFeedbackSubFilterRemoveGoalId));
+#endif  // ROS_VERSION >= 5000
   return exports;
 }
 

package/src/rcl_context_bindings.cpp

@@ -17,10 +17,10 @@
 #include <rcl/logging.h>
 #include <rcl/rcl.h>
 
-#include <rcpputils/scope_exit.hpp>
-// NOLINTNEXTLINE
 #include <string>
 
+#include <rcpputils/scope_exit.hpp>
+
 #include "macros.h"
 #include "rcl_handle.h"
 #include "rcl_utilities.h"
@@ -54,6 +54,7 @@ Napi::Value Init(const Napi::CallbackInfo& info) {
   Napi::Array jsArgv = info[1].As<Napi::Array>();
   size_t argc = jsArgv.Length();
   char** argv = AbstractArgsFromNapiArray(jsArgv);
+  RCPPUTILS_SCOPE_EXIT({ FreeArgs(argv, argc); });
 
   // Set up the domain id.
   size_t domain_id = RCL_DEFAULT_DOMAIN_ID;
@@ -82,7 +83,6 @@ Napi::Value Init(const Napi::CallbackInfo& info) {
       RCL_RET_OK, rcl_logging_configure(&context->global_arguments, &allocator),
       rcl_get_error_string().str);
 
-  RCPPUTILS_SCOPE_EXIT({ FreeArgs(argv, argc); });
   return env.Undefined();
 }
 

package/src/rcl_graph_bindings.cpp

@@ -18,10 +18,10 @@
 #include <rcl/graph.h>
 #include <rcl/rcl.h>
 
-#include <rcpputils/scope_exit.hpp>
-// NOLINTNEXTLINE
 #include <string>
 
+#include <rcpputils/scope_exit.hpp>
+
 #include "macros.h"
 #include "rcl_handle.h"
 #include "rcl_utilities.h"

package/src/rcl_subscription_bindings.cpp

@@ -16,13 +16,15 @@
 
 #include <rcl/error_handling.h>
 #include <rcl/rcl.h>
+#include <rcl/subscription.h>
+#include <rmw/types.h>
 
 #include <cstdio>
 #include <memory>
-#include <rcpputils/scope_exit.hpp>
-// NOLINTNEXTLINE
 #include <string>
 
+#include <rcpputils/scope_exit.hpp>
+
 #include "macros.h"
 #include "rcl_handle.h"
 #include "rcl_utilities.h"
@@ -53,6 +55,53 @@ Napi::Value RclTake(const Napi::CallbackInfo& info) {
   return env.Undefined();
 }
 
+Napi::Value RclTakeWithInfo(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  RclHandle* subscription_handle =
+      RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_subscription_t* subscription =
+      reinterpret_cast<rcl_subscription_t*>(subscription_handle->ptr());
+  void* msg_taken = info[1].As<Napi::Buffer<char>>().Data();
+
+  rmw_message_info_t message_info = rmw_get_zero_initialized_message_info();
+  rcl_ret_t ret = rcl_take(subscription, msg_taken, &message_info, nullptr);
+
+  if (ret != RCL_RET_OK && ret != RCL_RET_SUBSCRIPTION_TAKE_FAILED) {
+    std::string error_string = rcl_get_error_string().str;
+    rcl_reset_error();
+    Napi::Error::New(env, error_string).ThrowAsJavaScriptException();
+    return env.Undefined();
+  }
+
+  if (ret == RCL_RET_SUBSCRIPTION_TAKE_FAILED) {
+    return env.Undefined();
+  }
+
+  // Build JS object with message info fields
+  Napi::Object js_info = Napi::Object::New(env);
+  js_info.Set("source_timestamp",
+              Napi::BigInt::New(env, message_info.source_timestamp));
+  js_info.Set("received_timestamp",
+              Napi::BigInt::New(env, message_info.received_timestamp));
+  js_info.Set(
+      "publication_sequence_number",
+      Napi::BigInt::New(
+          env, static_cast<int64_t>(message_info.publication_sequence_number)));
+  js_info.Set(
+      "reception_sequence_number",
+      Napi::BigInt::New(
+          env, static_cast<int64_t>(message_info.reception_sequence_number)));
+
+  // Publisher GID as Buffer
+  auto gid_buf =
+      Napi::Buffer<uint8_t>::Copy(env, message_info.publisher_gid.data,
+                                  sizeof(message_info.publisher_gid.data));
+  js_info.Set("publisher_gid", gid_buf);
+
+  return js_info;
+}
+
 Napi::Value CreateSubscription(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
@@ -216,6 +265,20 @@ Napi::Value GetSubscriptionTopic(const Napi::CallbackInfo& info) {
   return Napi::String::New(env, topic);
 }
 
+#if ROS_VERSION > 2505  // Rolling only
+Napi::Value IsContentFilterSupported(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+
+  RclHandle* subscription_handle =
+      RclHandle::Unwrap(info[0].As<Napi::Object>());
+  rcl_subscription_t* subscription =
+      reinterpret_cast<rcl_subscription_t*>(subscription_handle->ptr());
+
+  bool is_supported = rcl_subscription_is_cft_supported(subscription);
+  return Napi::Boolean::New(env, is_supported);
+}
+#endif
+
 Napi::Value HasContentFilter(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
 
@@ -422,11 +485,16 @@ Napi::Value GetPublisherCount(const Napi::CallbackInfo& info) {
 
 Napi::Object InitSubscriptionBindings(Napi::Env env, Napi::Object exports) {
   exports.Set("rclTake", Napi::Function::New(env, RclTake));
+  exports.Set("rclTakeWithInfo", Napi::Function::New(env, RclTakeWithInfo));
   exports.Set("createSubscription",
               Napi::Function::New(env, CreateSubscription));
   exports.Set("rclTakeRaw", Napi::Function::New(env, RclTakeRaw));
   exports.Set("getSubscriptionTopic",
               Napi::Function::New(env, GetSubscriptionTopic));
+#if ROS_VERSION > 2505  // Rolling only
+  exports.Set("isContentFilterSupported",
+              Napi::Function::New(env, IsContentFilterSupported));
+#endif
   exports.Set("hasContentFilter", Napi::Function::New(env, HasContentFilter));
   exports.Set("setContentFilter", Napi::Function::New(env, SetContentFilter));
   exports.Set("getContentFilter", Napi::Function::New(env, GetContentFilter));

package/src/rcl_timer_bindings.cpp

@@ -78,6 +78,15 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
 
   bool lossless;
   int64_t period_nsec = info[2].As<Napi::BigInt>().Int64Value(&lossless);
+  bool autostart = true;
+  if (info.Length() > 3) {
+    if (!info[3].IsBoolean()) {
+      Napi::TypeError::New(env, "Timer autostart must be a boolean")
+          .ThrowAsJavaScriptException();
+      return env.Undefined();
+    }
+    autostart = info[3].As<Napi::Boolean>().Value();
+  }
   rcl_timer_t* timer =
       reinterpret_cast<rcl_timer_t*>(malloc(sizeof(rcl_timer_t)));
   *timer = rcl_get_zero_initialized_timer();
@@ -85,8 +94,7 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
 #if ROS_VERSION > 2305  // After Iron.
   {
     rcl_ret_t ret = rcl_timer_init2(timer, clock, context, period_nsec, nullptr,
-                                    rcl_get_default_allocator(),
-                                    /*autostart=*/true);
+                                    rcl_get_default_allocator(), autostart);
     if (RCL_RET_OK != ret) {
       std::string error_msg = rcl_get_error_string().str;
       rcl_reset_error();
@@ -106,6 +114,17 @@ Napi::Value CreateTimer(const Napi::CallbackInfo& info) {
       Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
       return env.Undefined();
     }
+    if (!autostart) {
+      rcl_ret_t cancel_ret = rcl_timer_cancel(timer);
+      if (RCL_RET_OK != cancel_ret) {
+        std::string error_msg = rcl_get_error_string().str;
+        rcl_reset_error();
+        rcl_timer_fini(timer);
+        free(timer);
+        Napi::Error::New(env, error_msg).ThrowAsJavaScriptException();
+        return env.Undefined();
+      }
+    }
   }
 #endif
 

package/src/rcl_utilities.cpp

@@ -21,10 +21,10 @@
 
 #include <cstdio>
 #include <memory>
-#include <rcpputils/scope_exit.hpp>
-// NOLINTNEXTLINE
 #include <string>
 
+#include <rcpputils/scope_exit.hpp>
+
 namespace {
 
 const rmw_qos_profile_t* GetQoSProfileFromString(const std::string& profile) {

package/tools/jsdoc/Makefile

@@ -0,0 +1,5 @@
+.PHONY: docs
+
+docs:
+	npx jsdoc --package ../../package.json ../../index.js ../../lib/*.js ../../lib/action/*.js -t . -d ../../docs
+	node ./build-index.js

package/tools/jsdoc/README.md

@@ -0,0 +1,96 @@
+# JSDoc Workflow
+
+This directory contains the custom JSDoc template, the landing-page generator,
+and the staging script used to prepare the docs content that is published to the
+`gh-pages` branch.
+
+## Commands
+
+### `npm run docs`
+
+Build local docs for the current workspace version.
+
+Output:
+
+- `docs/<current-version>/`
+- `docs/index.html`
+
+Use this to verify the docs for the version currently declared in
+`package.json`.
+
+### `npm run docs:gh-pages`
+
+Stage the publishable docs tree under `build/gh-pages-docs/`.
+
+Behavior:
+
+- reads the currently published version set from `origin/gh-pages`
+- preserves that published history
+- regenerates docs for the current workspace version
+- rebuilds the staged landing page index
+
+This is the normal command to use for a new release.
+
+If you delete `build/` and rerun `npm run docs:gh-pages`, the staged tree will
+still contain all currently published versions. That command recreates
+`build/gh-pages-docs/` by copying the published docs snapshot from
+`origin/gh-pages`, then regenerating only the current workspace version.
+
+### `npm run docs:gh-pages:full`
+
+Fully rebuild the currently published docs history under
+`build/gh-pages-docs/`.
+
+Behavior:
+
+- reads the published version set from `origin/gh-pages`
+- rebuilds only those published versions from tags
+- regenerates docs for the current workspace version
+- rebuilds the staged landing page index
+
+This does **not** rebuild docs for every historical `rclnodejs` tag. It only
+rebuilds the subset that is actually published online.
+
+## New Release Example
+
+For a new release such as `1.9.0`:
+
+1. Update `package.json` to `1.9.0`.
+2. Run `npm run docs`.
+3. Verify the local output in `docs/1.9.0/` and `docs/index.html`.
+4. Run `npm run docs:gh-pages`.
+5. Verify the staged output in:
+   - `build/gh-pages-docs/docs/1.9.0/`
+   - `build/gh-pages-docs/docs/index.html`
+   - `build/gh-pages-docs/.nojekyll`
+6. Publish the contents of `build/gh-pages-docs/` to the `gh-pages` branch.
+
+## Manual Landing Page Rebuild
+
+If the staged docs tree already exists and you only want to rebuild
+`build/gh-pages-docs/docs/index.html`, run `tools/jsdoc/build-index.js` against
+that docs root and point it at the package metadata for the latest published
+version.
+
+Example for published version `1.8.0`:
+
+```bash
+mkdir -p build/gh-pages-docs/.tmp
+git show 1.8.0:package.json > build/gh-pages-docs/.tmp/package-1.8.0.json
+
+export RCLNODEJS_DOCS_ROOT="$PWD/build/gh-pages-docs/docs"
+export RCLNODEJS_DOCS_INDEX_PATH="$PWD/build/gh-pages-docs/docs/index.html"
+export RCLNODEJS_LOCAL_INDEX_PATH=''
+export RCLNODEJS_PACKAGE_JSON_PATH="$PWD/build/gh-pages-docs/.tmp/package-1.8.0.json"
+
+node tools/jsdoc/build-index.js
+rm -rf build/gh-pages-docs/.tmp
+```
+
+## Notes
+
+- The staged publish output keeps shared assets in `build/gh-pages-docs/docs/_static/`.
+- `.nojekyll` must remain in the staged output because the published docs tree
+  uses an underscore-prefixed directory.
+- The live docs index is the source of truth for which versions should remain
+  published.