[FL-3918] Full-fledged JS SDK + npm packages (#3963)

* feat: js sdk
* refactor: move js back where it belongs
* docs: generate docs using typedoc
* feat: sdk versioning scheme
* ci: silence pvs warning
* docs: bring back old incomplete js docs
* style: readAnalog naming
* fix: rename script compatibility screens

Co-authored-by: あく <alleteam@gmail.com>

.gitignore

@@ -63,4 +63,7 @@ PVS-Studio.log
 
 .gdbinit
 
-/fbt_options_local.py
+/fbt_options_local.py
+
+# JS packages
+node_modules/

applications/debug/unit_tests/resources/unit_tests/js/basic.js

@@ -1,4 +1,15 @@
 let tests = require("tests");
+let flipper = require("flipper");
 
 tests.assert_eq(1337, 1337);
 tests.assert_eq("hello", "hello");
+
+tests.assert_eq("compatible", sdkCompatibilityStatus(0, 1));
+tests.assert_eq("firmwareTooOld", sdkCompatibilityStatus(100500, 0));
+tests.assert_eq("firmwareTooNew", sdkCompatibilityStatus(-100500, 0));
+tests.assert_eq(true, doesSdkSupport(["baseline"]));
+tests.assert_eq(false, doesSdkSupport(["abobus", "other-nonexistent-feature"]));
+
+tests.assert_eq("flipperdevices", flipper.firmwareVendor);
+tests.assert_eq(0, flipper.jsSdkVersion[0]);
+tests.assert_eq(1, flipper.jsSdkVersion[1]);

applications/system/application.fam

@@ -5,7 +5,6 @@ App(
     provides=[
         "updater_app",
         "js_app",
-        "js_app_start",
         # "archive",
     ],
 )

applications/system/js_app/application.fam

@@ -6,13 +6,24 @@ App(
     stack_size=2 * 1024,
     resources="examples",
     order=0,
+    provides=["js_app_start"],
+    sources=[
+        "js_app.c",
+        "js_modules.c",
+        "js_thread.c",
+        "plugin_api/app_api_table.cpp",
+        "views/console_view.c",
+        "modules/js_flipper.c",
+        "modules/js_tests.c",
+    ],
 )
 
 App(
     appid="js_app_start",
     apptype=FlipperAppType.STARTUP,
     entry_point="js_app_on_system_start",
     order=160,
+    sources=["js_app.c"],
 )
 
 App(

applications/system/js_app/examples/apps/Scripts/gpio.js

@@ -19,7 +19,7 @@ eventLoop.subscribe(eventLoop.timer("periodic", 1000), function (_, _item, led,
 // read potentiometer when button is pressed
 print("Press the button (PC1)");
 eventLoop.subscribe(button.interrupt(), function (_, _item, pot) {
-    print("PC0 is at", pot.read_analog(), "mV");
+    print("PC0 is at", pot.readAnalog(), "mV");
 }, pot);
 
 // the program will just exit unless this is here

applications/system/js_app/js_modules.c

@@ -1,6 +1,8 @@
 #include <core/common_defines.h>
 #include "js_modules.h"
 #include <m-array.h>
+#include <dialogs/dialogs.h>
+#include <assets_icons.h>
 
 #include "modules/js_flipper.h"
 #ifdef FW_CFG_unit_tests
@@ -76,6 +78,12 @@ JsModuleData* js_find_loaded_module(JsModules* instance, const char* name) {
 }
 
 mjs_val_t js_module_require(JsModules* modules, const char* name, size_t name_len) {
+    // Ignore the initial part of the module name
+    const char* optional_module_prefix = "@" JS_SDK_VENDOR "/fz-sdk/";
+    if(strncmp(name, optional_module_prefix, strlen(optional_module_prefix)) == 0) {
+        name += strlen(optional_module_prefix);
+    }
+
     // Check if module is already installed
     JsModuleData* module_inst = js_find_loaded_module(modules, name);
     if(module_inst) { //-V547
@@ -175,3 +183,133 @@ void* js_module_get(JsModules* modules, const char* name) {
     furi_string_free(module_name);
     return module_inst ? module_inst->context : NULL;
 }
+
+typedef enum {
+    JsSdkCompatStatusCompatible,
+    JsSdkCompatStatusFirmwareTooOld,
+    JsSdkCompatStatusFirmwareTooNew,
+} JsSdkCompatStatus;
+
+/**
+ * @brief Checks compatibility between the firmware and the JS SDK version
+ *        expected by the script
+ */
+static JsSdkCompatStatus
+    js_internal_sdk_compatibility_status(int32_t exp_major, int32_t exp_minor) {
+    if(exp_major < JS_SDK_MAJOR) return JsSdkCompatStatusFirmwareTooNew;
+    if(exp_major > JS_SDK_MAJOR || exp_minor > JS_SDK_MINOR)
+        return JsSdkCompatStatusFirmwareTooOld;
+    return JsSdkCompatStatusCompatible;
+}
+
+#define JS_SDK_COMPAT_ARGS \
+    int32_t major, minor;  \
+    JS_FETCH_ARGS_OR_RETURN(mjs, JS_EXACTLY, JS_ARG_INT32(&major), JS_ARG_INT32(&minor));
+
+void js_sdk_compatibility_status(struct mjs* mjs) {
+    JS_SDK_COMPAT_ARGS;
+    JsSdkCompatStatus status = js_internal_sdk_compatibility_status(major, minor);
+    switch(status) {
+    case JsSdkCompatStatusCompatible:
+        mjs_return(mjs, mjs_mk_string(mjs, "compatible", ~0, 0));
+        return;
+    case JsSdkCompatStatusFirmwareTooOld:
+        mjs_return(mjs, mjs_mk_string(mjs, "firmwareTooOld", ~0, 0));
+        return;
+    case JsSdkCompatStatusFirmwareTooNew:
+        mjs_return(mjs, mjs_mk_string(mjs, "firmwareTooNew", ~0, 0));
+        return;
+    }
+}
+
+void js_is_sdk_compatible(struct mjs* mjs) {
+    JS_SDK_COMPAT_ARGS;
+    JsSdkCompatStatus status = js_internal_sdk_compatibility_status(major, minor);
+    mjs_return(mjs, mjs_mk_boolean(mjs, status == JsSdkCompatStatusCompatible));
+}
+
+/**
+ * @brief Asks the user whether to continue executing an incompatible script
+ */
+static bool js_internal_compat_ask_user(const char* message) {
+    DialogsApp* dialogs = furi_record_open(RECORD_DIALOGS);
+    DialogMessage* dialog = dialog_message_alloc();
+    dialog_message_set_header(dialog, message, 64, 0, AlignCenter, AlignTop);
+    dialog_message_set_text(
+        dialog, "This script may not\nwork as expected", 79, 32, AlignCenter, AlignCenter);
+    dialog_message_set_icon(dialog, &I_Warning_30x23, 0, 18);
+    dialog_message_set_buttons(dialog, "Go back", NULL, "Run anyway");
+    DialogMessageButton choice = dialog_message_show(dialogs, dialog);
+    dialog_message_free(dialog);
+    furi_record_close(RECORD_DIALOGS);
+    return choice == DialogMessageButtonRight;
+}
+
+void js_check_sdk_compatibility(struct mjs* mjs) {
+    JS_SDK_COMPAT_ARGS;
+    JsSdkCompatStatus status = js_internal_sdk_compatibility_status(major, minor);
+    if(status != JsSdkCompatStatusCompatible) {
+        FURI_LOG_E(
+            TAG,
+            "Script requests JS SDK %ld.%ld, firmware provides JS SDK %d.%d",
+            major,
+            minor,
+            JS_SDK_MAJOR,
+            JS_SDK_MINOR);
+
+        const char* message = (status == JsSdkCompatStatusFirmwareTooOld) ? "Outdated Firmware" :
+                                                                            "Outdated Script";
+        if(!js_internal_compat_ask_user(message)) {
+            JS_ERROR_AND_RETURN(mjs, MJS_NOT_IMPLEMENTED_ERROR, "Incompatible script");
+        }
+    }
+}
+
+static const char* extra_features[] = {
+    "baseline", // dummy "feature"
+};
+
+/**
+ * @brief Determines whether a feature is supported
+ */
+static bool js_internal_supports(const char* feature) {
+    for(size_t i = 0; i < COUNT_OF(extra_features); i++) { // -V1008
+        if(strcmp(feature, extra_features[i]) == 0) return true;
+    }
+    return false;
+}
+
+/**
+ * @brief Determines whether all of the requested features are supported
+ */
+static bool js_internal_supports_all_of(struct mjs* mjs, mjs_val_t feature_arr) {
+    furi_assert(mjs_is_array(feature_arr));
+
+    for(size_t i = 0; i < mjs_array_length(mjs, feature_arr); i++) {
+        mjs_val_t feature = mjs_array_get(mjs, feature_arr, i);
+        const char* feature_str = mjs_get_string(mjs, &feature, NULL);
+        if(!feature_str) return false;
+
+        if(!js_internal_supports(feature_str)) return false;
+    }
+
+    return true;
+}
+
+void js_does_sdk_support(struct mjs* mjs) {
+    mjs_val_t features;
+    JS_FETCH_ARGS_OR_RETURN(mjs, JS_EXACTLY, JS_ARG_ARR(&features));
+    mjs_return(mjs, mjs_mk_boolean(mjs, js_internal_supports_all_of(mjs, features)));
+}
+
+void js_check_sdk_features(struct mjs* mjs) {
+    mjs_val_t features;
+    JS_FETCH_ARGS_OR_RETURN(mjs, JS_EXACTLY, JS_ARG_ARR(&features));
+    if(!js_internal_supports_all_of(mjs, features)) {
+        FURI_LOG_E(TAG, "Script requests unsupported features");
+
+        if(!js_internal_compat_ask_user("Unsupported Feature")) {
+            JS_ERROR_AND_RETURN(mjs, MJS_NOT_IMPLEMENTED_ERROR, "Incompatible script");
+        }
+    }
+}

applications/system/js_app/js_modules.h

@@ -9,6 +9,10 @@
 #define PLUGIN_APP_ID      "js"
 #define PLUGIN_API_VERSION 1
 
+#define JS_SDK_VENDOR "flipperdevices"
+#define JS_SDK_MAJOR  0
+#define JS_SDK_MINOR  1
+
 /**
  * @brief Returns the foreign pointer in `obj["_"]`
  */
@@ -275,3 +279,28 @@ mjs_val_t js_module_require(JsModules* modules, const char* name, size_t name_le
  * @returns Pointer to module context, NULL if the module is not instantiated
  */
 void* js_module_get(JsModules* modules, const char* name);
+
+/**
+ * @brief `sdkCompatibilityStatus` function
+ */
+void js_sdk_compatibility_status(struct mjs* mjs);
+
+/**
+ * @brief `isSdkCompatible` function
+ */
+void js_is_sdk_compatible(struct mjs* mjs);
+
+/**
+ * @brief `checkSdkCompatibility` function
+ */
+void js_check_sdk_compatibility(struct mjs* mjs);
+
+/**
+ * @brief `doesSdkSupport` function
+ */
+void js_does_sdk_support(struct mjs* mjs);
+
+/**
+ * @brief `checkSdkFeatures` function
+ */
+void js_check_sdk_features(struct mjs* mjs);

applications/system/js_app/js_thread.c

@@ -231,18 +231,29 @@ static int32_t js_thread(void* arg) {
     struct mjs* mjs = mjs_create(worker);
     worker->modules = js_modules_create(mjs, worker->resolver);
     mjs_val_t global = mjs_get_global(mjs);
-    mjs_set(mjs, global, "print", ~0, MJS_MK_FN(js_print));
-    mjs_set(mjs, global, "delay", ~0, MJS_MK_FN(js_delay));
-    mjs_set(mjs, global, "toString", ~0, MJS_MK_FN(js_global_to_string));
-    mjs_set(mjs, global, "ffi_address", ~0, MJS_MK_FN(js_ffi_address));
-    mjs_set(mjs, global, "require", ~0, MJS_MK_FN(js_require));
-
     mjs_val_t console_obj = mjs_mk_object(mjs);
-    mjs_set(mjs, console_obj, "log", ~0, MJS_MK_FN(js_console_log));
-    mjs_set(mjs, console_obj, "warn", ~0, MJS_MK_FN(js_console_warn));
-    mjs_set(mjs, console_obj, "error", ~0, MJS_MK_FN(js_console_error));
-    mjs_set(mjs, console_obj, "debug", ~0, MJS_MK_FN(js_console_debug));
-    mjs_set(mjs, global, "console", ~0, console_obj);
+
+    JS_ASSIGN_MULTI(mjs, global) {
+        JS_FIELD("print", MJS_MK_FN(js_print));
+        JS_FIELD("delay", MJS_MK_FN(js_delay));
+        JS_FIELD("toString", MJS_MK_FN(js_global_to_string));
+        JS_FIELD("ffi_address", MJS_MK_FN(js_ffi_address));
+        JS_FIELD("require", MJS_MK_FN(js_require));
+        JS_FIELD("console", console_obj);
+
+        JS_FIELD("sdkCompatibilityStatus", MJS_MK_FN(js_sdk_compatibility_status));
+        JS_FIELD("isSdkCompatible", MJS_MK_FN(js_is_sdk_compatible));
+        JS_FIELD("checkSdkCompatibility", MJS_MK_FN(js_check_sdk_compatibility));
+        JS_FIELD("doesSdkSupport", MJS_MK_FN(js_does_sdk_support));
+        JS_FIELD("checkSdkFeatures", MJS_MK_FN(js_check_sdk_features));
+    }
+
+    JS_ASSIGN_MULTI(mjs, console_obj) {
+        JS_FIELD("log", MJS_MK_FN(js_console_log));
+        JS_FIELD("warn", MJS_MK_FN(js_console_warn));
+        JS_FIELD("error", MJS_MK_FN(js_console_error));
+        JS_FIELD("debug", MJS_MK_FN(js_console_debug));
+    }
 
     mjs_set_ffi_resolver(mjs, js_dlsym, worker->resolver);
 

applications/system/js_app/modules/js_flipper.c

@@ -27,11 +27,19 @@ static void js_flipper_get_battery(struct mjs* mjs) {
 
 void* js_flipper_create(struct mjs* mjs, mjs_val_t* object, JsModules* modules) {
     UNUSED(modules);
+    mjs_val_t sdk_vsn = mjs_mk_array(mjs);
+    mjs_array_push(mjs, sdk_vsn, mjs_mk_number(mjs, JS_SDK_MAJOR));
+    mjs_array_push(mjs, sdk_vsn, mjs_mk_number(mjs, JS_SDK_MINOR));
+
     mjs_val_t flipper_obj = mjs_mk_object(mjs);
-    mjs_set(mjs, flipper_obj, "getModel", ~0, MJS_MK_FN(js_flipper_get_model));
-    mjs_set(mjs, flipper_obj, "getName", ~0, MJS_MK_FN(js_flipper_get_name));
-    mjs_set(mjs, flipper_obj, "getBatteryCharge", ~0, MJS_MK_FN(js_flipper_get_battery));
     *object = flipper_obj;
+    JS_ASSIGN_MULTI(mjs, flipper_obj) {
+        JS_FIELD("getModel", MJS_MK_FN(js_flipper_get_model));
+        JS_FIELD("getName", MJS_MK_FN(js_flipper_get_name));
+        JS_FIELD("getBatteryCharge", MJS_MK_FN(js_flipper_get_battery));
+        JS_FIELD("firmwareVendor", mjs_mk_string(mjs, JS_SDK_VENDOR, ~0, false));
+        JS_FIELD("jsSdkVersion", sdk_vsn);
+    }
 
     return (void*)1;
 }

applications/system/js_app/modules/js_gpio.c

@@ -220,7 +220,7 @@ static void js_gpio_interrupt(struct mjs* mjs) {
  * let gpio = require("gpio");
  * let pot = gpio.get("pc0");
  * pot.init({ direction: "in", inMode: "analog" });
- * print("voltage:" pot.read_analog(), "mV");
+ * print("voltage:" pot.readAnalog(), "mV");
  * ```
  */
 static void js_gpio_read_analog(struct mjs* mjs) {
@@ -274,7 +274,7 @@ static void js_gpio_get(struct mjs* mjs) {
     mjs_set(mjs, manager, "init", ~0, MJS_MK_FN(js_gpio_init));
     mjs_set(mjs, manager, "write", ~0, MJS_MK_FN(js_gpio_write));
     mjs_set(mjs, manager, "read", ~0, MJS_MK_FN(js_gpio_read));
-    mjs_set(mjs, manager, "read_analog", ~0, MJS_MK_FN(js_gpio_read_analog));
+    mjs_set(mjs, manager, "readAnalog", ~0, MJS_MK_FN(js_gpio_read_analog));
     mjs_set(mjs, manager, "interrupt", ~0, MJS_MK_FN(js_gpio_interrupt));
     mjs_return(mjs, manager);
 

applications/system/js_app/packages/create-fz-app/README.md

@@ -0,0 +1,20 @@
+# Flipper Zero JavaScript SDK Wizard
+This package contains an interactive wizard that lets you scaffold a JavaScript
+application for Flipper Zero.
+
+## Getting started
+Create your application using the interactive wizard:
+```shell
+npx @flipperdevices/create-fz-app@latest
+```
+
+Then, enter the directory with your application and launch it:
+```shell
+cd my-flip-app
+npm start
+```
+
+You are free to use `pnpm` or `yarn` instead of `npm`.
+
+## Documentation
+Check out the [JavaScript section in the Developer Documentation](https://developer.flipper.net/flipperzero/doxygen/js.html)