@zappdev/cli 0.1.0 → 0.2.0

package/native/vendor/quickjs-ng/docs/docs/building.md

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+---
+
+# Building
+
+QuickJS uses [CMake] as its main build system, with an additional helper [Makefile].
+
+:::note
+Windows users will need to run the CMake commands manually.
+:::
+
+## Getting the source
+
+```bash
+git clone https://github.com/quickjs-ng/quickjs.git
+cd quickjs
+```
+
+## Compiling everything
+
+```bash
+make
+```
+
+This will build the `qjs` and `qjsc` executables and other test tools. Head over [here](./cli) for
+instructions on how to use them.
+
+## Amalgamated builds
+
+The amalgamated build rolls individual source files into a single big file.
+It's a good choice for projects that want to use QuickJS without CMake.
+
+Download quickjs-amalgam.zip from [Releases](https://github.com/quickjs-ng/quickjs/releases)
+
+To enable the std, os and bjson modules, compile quickjs-amalgam.c with
+`-DQJS_BUILD_LIBC`.
+
+## Debug builds
+
+```bash
+make debug
+```
+
+This will produce a debug build without optimizations, suitable for developers.
+
+## Running test262
+
+```bash
+make test262
+```
+
+This will run the test262 suite.
+
+```bash
+make test262-update
+```
+
+This will run the test262 suite and update the error / pass report, useful after
+implementing a new feature that would alter the result of the test suite.
+
+[CMake]: https://cmake.org
+[Makefile]: https://www.gnu.org/software/make/

package/native/vendor/quickjs-ng/docs/docs/cli.md

@@ -0,0 +1,130 @@
+---
+sidebar_position: 4
+---
+
+# The qjs and qjsc CLI tools
+
+## `qjs` - The QuickJS JavaScript interpreter
+
+The `qjs` executable runs the JavaScript interpreter. It includes a simple standard
+library and REPL.
+
+```
+$ qjs
+usage: qjs [options] [file [args]]
+-h  --help         list options
+-e  --eval EXPR    evaluate EXPR
+-i  --interactive  go to interactive mode
+-m  --module       load as ES6 module (default=autodetect)
+    --script       load as ES6 script (default=autodetect)
+-I  --include file include an additional file
+    --std          make 'std', 'os' and 'bjson' available to script
+-T  --trace        trace memory allocation
+-d  --dump         dump the memory usage stats
+-D  --dump-flags   flags for dumping debug data (see DUMP_* defines)
+-c  --compile FILE compile the given JS file as a standalone executable
+-o  --out FILE     output file for standalone executables
+    --exe          select the executable to use as the base, defaults to the current one
+    --memory-limit n       limit the memory usage to 'n' Kbytes
+    --stack-size n         limit the stack size to 'n' Kbytes
+    --unhandled-rejection  dump unhandled promise rejections
+-q  --quit         just instantiate the interpreter and quit
+```
+
+The following dump flags are supported:
+
+```
+DUMP_BYTECODE_FINAL   0x01  /* dump pass 3 final byte code */
+DUMP_BYTECODE_PASS2   0x02  /* dump pass 2 code */
+DUMP_BYTECODE_PASS1   0x04  /* dump pass 1 code */
+DUMP_BYTECODE_HEX     0x10  /* dump bytecode in hex */
+DUMP_BYTECODE_PC2LINE 0x20  /* dump line number table */
+DUMP_BYTECODE_STACK   0x40  /* dump compute_stack_size */
+DUMP_BYTECODE_STEP    0x80  /* dump executed bytecode */
+DUMP_READ_OBJECT     0x100  /* dump the marshalled objects at load time */
+DUMP_FREE            0x200  /* dump every object free */
+DUMP_GC              0x400  /* dump the occurrence of the automatic GC */
+DUMP_GC_FREE         0x800  /* dump objects freed by the GC */
+DUMP_MODULE_RESOLVE 0x1000  /* dump module resolution steps */
+DUMP_PROMISE        0x2000  /* dump promise steps */
+DUMP_LEAKS          0x4000  /* dump leaked objects and strings in JS_FreeRuntime */
+DUMP_ATOM_LEAKS     0x8000  /* dump leaked atoms in JS_FreeRuntime */
+DUMP_MEM           0x10000  /* dump memory usage in JS_FreeRuntime */
+DUMP_OBJECTS       0x20000  /* dump objects in JS_FreeRuntime */
+DUMP_ATOMS         0x40000  /* dump atoms in JS_FreeRuntime */
+DUMP_SHAPES        0x80000  /* dump shapes in JS_FreeRuntime */
+```
+
+### Creating standalone executables
+
+With the `qjs` CLI it's possible to create standalone executables that will bundle the given JavaScript file
+alongside the binary.
+
+```
+$ qjs -c app.js -o app --exe qjs
+```
+
+The resulting `app` binary will have the same runtime dependencies as the `qjs` binary. This is acomplished
+by compiling the target JavaScript file to bytecode and adding it a copy of the executable, with a little
+trailer to help locate it. `--exe` expects the absolute path to `qjs`, e.g., `~/bin/qjs` or `$HOME/bin/qjs`.
+
+Rather than using the current executable, it's possible to use the `--exe` switch to create standalone
+executables for other platforms.
+
+No JavaScript bundling is performed, the specified JS file cannot depend on other files. A bundler such
+as `esbuild` can be used to generate an app bundle which can then be turned into the executable.
+
+```
+npx esbuild my-app/index.js \
+    --bundle \
+    --outfile=app.js \
+    --external:qjs:* \
+    --minify \
+    --target=es2023 \
+    --platform=neutral \
+    --format=esm \
+    --main-fields=main,module
+```
+
+## `qjsc` - The QuickJS JavaScript compiler
+
+The `qjsc` executable runs the JavaScript compiler, it can generate bytecode from
+source files which can then be embedded in an executable, or it can generate the necessary
+scaffolding to build a C application which embeds QuickJS.
+
+```
+$ qjsc
+usage: qjsc [options] [files]
+
+options are:
+-b          output raw bytecode instead of C code
+-e          output main() and bytecode in a C file
+-o output   set the output filename
+-n script_name    set the script name (as used in stack traces)
+-N cname    set the C name of the generated data
+-m          compile as JavaScript module (default=autodetect)
+-D module_name         compile a dynamically loaded module or worker
+-M module_name[,cname] add initialization code for an external C module
+-p prefix   set the prefix of the generated C names
+-s          strip the source code, specify twice to also strip debug info
+-S n        set the maximum stack size to 'n' bytes (default=262144)
+```
+
+Here is an example on how to create a standalone executable that embeds QuickJS
+and the `examples/hello.js` JavaScript file:
+
+```bash
+# Make sure you are in the QuickJS source directory.
+$ cc hello.c dtoa.c libregexp.c libunicode.c quickjs.c quickjs-libc.c -I. -o hello
+```
+
+The resulting binary `hello` will be in the current directory.
+
+```bash
+$ ./hello
+Hello World
+```
+
+:::note
+See the ["Creating standalone executables"](#creating-standalone-executables) section for a simpler way.
+:::

package/native/vendor/quickjs-ng/docs/docs/developer-guide/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Developer Guide",
+  "position": 6,
+  "link": {
+    "type": "generated-index"
+  }
+}

package/native/vendor/quickjs-ng/docs/docs/developer-guide/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+WIP.

package/native/vendor/quickjs-ng/docs/docs/developer-guide/internals.md

@@ -0,0 +1,117 @@
+# Internals
+
+## Bytecode
+
+The compiler generates bytecode directly with no intermediate
+representation such as a parse tree, hence it is very fast. Several
+optimizations passes are done over the generated bytecode.
+
+A stack-based bytecode was chosen because it is simple and generates 
+compact code.
+
+For each function, the maximum stack size is computed at compile time so that
+no runtime stack overflow tests are needed.
+
+A separate compressed line number table is maintained for the debug
+information.
+
+Access to closure variables is optimized and is almost as fast as local
+variables.
+
+Direct `eval` in strict mode is optimized.
+
+## Runtime
+
+### Strings
+
+Strings are stored either as an 8 bit or a 16 bit array of
+characters. Hence random access to characters is always fast.
+
+The C API provides functions to convert JavaScript Strings to C UTF-8 encoded
+strings. The most common case where the JavaScript string contains
+only ASCII characters involves no copying.
+
+### Objects
+
+The object shapes (object prototype, property names and flags) are shared
+between objects to save memory.
+
+Arrays with no holes (except at the end of the array) are optimized.
+
+TypedArray accesses are optimized.
+
+### Atoms
+
+Object property names and some strings are stored as Atoms (unique
+strings) to save memory and allow fast comparison. Atoms are
+represented as a 32 bit integer. Half of the atom range is reserved for
+immediate integer literals from 0 to 2^31-1.
+
+### Numbers
+
+Numbers are represented either as 32-bit signed integers or 64-bit IEEE-754
+floating point values. Most operations have fast paths for the 32-bit
+integer case.
+
+### Garbage collection
+
+Reference counting is used to free objects automatically and
+deterministically. A separate cycle removal pass is done when the allocated
+memory becomes too large. The cycle removal algorithm only uses the
+reference counts and the object content, so no explicit garbage
+collection roots need to be manipulated in the C code.
+
+### JSValue
+
+It is a JavaScript value which can be a primitive type (such as
+Number, String, ...) or an Object. NaN boxing is used in the 32-bit version
+to store 64-bit floating point numbers. The representation is
+optimized so that 32-bit integers and reference counted values can be
+efficiently tested.
+
+In 64-bit code, JSValue are 128-bit large and no NaN boxing is used. The
+rationale is that in 64-bit code memory usage is less critical.
+
+In both cases (32 or 64 bits), JSValue exactly fits two CPU registers,
+so it can be efficiently returned by C functions.
+
+### Function call
+
+The engine is optimized so that function calls are fast. The system
+stack holds the JavaScript parameters and local variables.
+
+### RegExp
+
+A specific regular expression engine was developed. It is both small
+and efficient and supports all the ES2020+ features including the
+Unicode properties. As the JavaScript compiler, it directly generates
+bytecode without a parse tree.
+
+Backtracking with an explicit stack is used so that there is no
+recursion on the system stack. Simple quantifiers are specifically
+optimized to avoid recursions.
+
+Infinite recursions coming from quantifiers with empty terms are
+avoided.
+
+The full regexp library weighs about 15 KiB (x86 code), excluding the
+Unicode library.
+
+### Unicode
+
+A specific Unicode library was developed so that there is no
+dependency on an external large Unicode library such as ICU. All the
+Unicode tables are compressed while keeping a reasonable access
+speed.
+
+The library supports case conversion, Unicode normalization, Unicode
+script queries, Unicode general category queries and all Unicode
+binary properties.
+
+The full Unicode library weighs about 45 KiB (x86 code).
+
+### BigInt
+
+BigInt is implemented with the [libbf](https://bellard.org/libbf) library.
+It weights about 90 KiB (x86 code) and provides arbitrary precision IEEE 754 floating
+point operations and transcendental functions with exact rounding.

package/native/vendor/quickjs-ng/docs/docs/developer-guide/intro.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+---
+
+# The QuickJS C API
+
+The C API was designed to be simple and efficient. The C API is
+defined in the header `quickjs.h`.
+
+## Runtime and contexts
+
+`JSRuntime` represents a JavaScript runtime corresponding to an
+object heap. Several runtimes can exist at the same time but they
+cannot exchange objects. Inside a given runtime, no multi-threading is
+supported.
+
+`JSContext` represents a JavaScript context (or Realm). Each
+JSContext has its own global objects and system objects. There can be
+several JSContexts per JSRuntime and they can share objects, similar
+to frames of the same origin sharing JavaScript objects in a
+web browser.
+
+## JSValue
+
+`JSValue` represents a JavaScript value which can be a primitive
+type or an object. Reference counting is used, so it is important to
+explicitly duplicate (`JS_DupValue()`, increment the reference
+count) or free (`JS_FreeValue()`, decrement the reference count)
+JSValues.
+
+## C functions
+
+C functions can be created with
+`JS_NewCFunction()`. `JS_SetPropertyFunctionList()` is a
+shortcut to easily add functions, setters and getters properties to a
+given object.
+
+Unlike other embedded JavaScript engines, there is no implicit stack,
+so C functions get their parameters as normal C parameters. As a
+general rule, C functions take constant `JSValue`s as parameters
+(so they don't need to free them) and return a newly allocated (=live)
+`JSValue`.
+
+## Exceptions
+
+Most C functions can return a JavaScript exception. It
+must be explicitly tested and handled by the C code. The specific
+`JSValue` `JS_EXCEPTION` indicates that an exception
+occurred. The actual exception object is stored in the
+`JSContext` and can be retrieved with `JS_GetException()`.
+
+## Script evaluation
+
+Use `JS_Eval()` to evaluate a script or module source.
+
+If the script or module was compiled to bytecode with `qjsc`, it
+can be evaluated by calling `js_std_eval_binary()`. The advantage
+is that no compilation is needed so it is faster and smaller because
+the compiler can be removed from the executable if no `eval` is
+required.
+
+Note: the bytecode format is linked to a given QuickJS
+version. Moreover, no security check is done before its
+execution. Hence the bytecode should not be loaded from untrusted
+sources.
+
+## JS Classes
+
+C opaque data can be attached to a JavaScript object. The type of the
+C opaque data is determined with the class ID (`JSClassID`) of
+the object. Hence the first step is to register a new class ID and JS
+class (`JS_NewClassID()`, `JS_NewClass()`). Then you can
+create objects of this class with `JS_NewObjectClass()` and get or
+set the C opaque point with `JS_GetOpaque()` / `JS_SetOpaque()`.
+
+When defining a new JS class, it is possible to declare a finalizer
+which is called when the object is destroyed. The finalizer should be
+used to release C resources. It is invalid to execute JS code from
+it. A `gc_mark` method can be provided so that the cycle removal
+algorithm can find the other objects referenced by this object. Other
+methods are available to define exotic object behaviors.
+
+The Class ID are allocated per-runtime. The
+`JSClass` are allocated per `JSRuntime`. `JS_SetClassProto()`
+is used to define a prototype for a given class in a given
+`JSContext`. `JS_NewObjectClass()` sets this prototype in the
+created object.
+
+Examples are available in `quickjs-libc.c`.
+
+## C Modules
+
+Native ES6 modules are supported and can be dynamically or statically
+linked. The standard library `quickjs-libc.c` is a good example
+of a native module.
+
+## Memory handling
+
+Use `JS_SetMemoryLimit()` to set a global memory allocation limit
+to a given `JSRuntime`.
+
+Custom memory allocation functions can be provided with `JS_NewRuntime2()`.
+
+The maximum system stack size can be set with `JS_SetMaxStackSize()`.
+
+## Execution timeout and interrupts
+
+Use `JS_SetInterruptHandler()` to set a callback which is
+regularly called by the engine when it is executing code. This
+callback can be used to implement an execution timeout.
+
+It is used by the command line interpreter to implement a
+`Ctrl-C` handler.

package/native/vendor/quickjs-ng/docs/docs/diff.md

@@ -0,0 +1,68 @@
+# Differences with bellard/quickjs
+
+This project aims to be a drop-in replacement for those already using QuickJS.
+Minimal API changes might be necessary.
+
+## Community development
+
+NG is developed in the open, interacting with the wider community and through
+these interactions many improvements have already been made, including the incorporation
+of patches previously maintained in other forks.
+
+Each PR is reviewed, iterated on, and merged in GitHub.
+
+To date, NG has had over 40 distinct contributors and over 400 PRs.
+
+## Consistent release cadence
+
+As the project moves forward, a steady cadence of releases has been maintained, with an
+average of a new release every 2 months.
+
+## Testing
+
+Since its inception testing has been a focus. Each PR is tested in over 50 configurations,
+involving different operating systems, build types and sanitizers.
+
+The `test262` suite is also ran for every change.
+
+## Cross-platform support
+
+In order to better support other platforms such as Windows the build system was
+changed to use [CMake].
+
+In addition, Windows is treated as a first class citizen, with the addition of support
+for the MSVC compiler.
+
+[CMake]: https://cmake.org/
+
+## Performance
+
+While being an interpreter limits the performance in comparison with other engines which
+use a JIT, several significant performance improvements have been made:
+
+- Opcode fusion
+- Polymorphic inline caching
+- Memory allocation improvements
+- Improved parse speeds
+
+## New ECMAScript APIs
+
+The main focus of NG is to deliver state-of-the-art JavaScript features. Typically once they
+are stable (stage 4) but sometimes even at earlier stages. Here is a non-exhaustive list
+of ES features present in NG:
+
+- Resizable ArrayBuffer
+- Float16Array
+- WeakRef
+- FinalizationRegistry
+- Iterator Helpers
+- Promise.try
+- Error.isError
+- Set operations
+
+Some non-standard but widely used APIs have also been added:
+
+- V8's [stack trace API](https://v8.dev/docs/stack-trace-api)
+  - `Error.captureStackTrace`
+  - `Error.prepareStackTrace`
+  - `Error.stackTraceLimit`

package/native/vendor/quickjs-ng/docs/docs/es_features.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 7
+---
+
+# ECMAScript Features
+
+QuickJS aims to support the latest available ECMAScript features once they hit the spec.
+
+Progress on _test262_ compliance can be checked [here](https://test262.fyi/#|qjs_ng).
+
+Due to size constraints it is unlikely QuickJS will ever support the [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) APIs.

package/native/vendor/quickjs-ng/docs/docs/installation.md

@@ -0,0 +1,34 @@
+---
+sidebar_position: 3
+---
+
+# Installation
+
+Installing QuickJS is simple, and we provide several ways to do so.
+
+
+## Build from source
+
+If you built it from source as outlined in [building](./building) you can just run:
+
+```bash
+make install
+```
+
+and it will be installed in your system. The default installation path is `/usr/local`.
+
+
+## Using a prebuilt binary
+
+Each [release on GitHub] includes binaries for several systems and architectures.
+
+
+## Using jsvu
+
+As of version 2.2.0 of `jsvu`, QuickJS-ng will be installed when the `quickjs` engine is requested.
+
+```bash
+npm install jsvu -g
+```
+
+[release on GitHub]: https://github.com/quickjs-ng/quickjs/releases

package/native/vendor/quickjs-ng/docs/docs/intro.md

@@ -0,0 +1,33 @@
+---
+slug: /
+sidebar_position: 1
+sidebar_label: Welcome
+---
+
+# Welcome to QuickJS-NG
+
+QuickJS is a small and embeddable JavaScript engine. It aims to support the latest
+[ECMAScript] specification.
+
+This project is a _fork_ of the [original QuickJS project] by Fabrice Bellard and Charlie Gordon, after it went dormant, with the intent of reigniting its development.
+
+This project is focused on (but not limited to):
+
+- Community development
+- Testing
+- Cross-platform support
+- ES features
+
+You can check the differences with the original project [here.](./diff)
+
+:::note
+This site is under construction, the entire API is not yet documented.
+:::
+
+## Getting Started
+
+Head over to [building](./building) if you want to build QuickJS from source or [installation](./installation)
+for installing it from prebuilt binaries.
+
+[ECMAScript]: https://tc39.es/ecma262/
+[original QuickJS project]: https://bellard.org/quickjs

package/native/vendor/quickjs-ng/docs/docs/projects.md

@@ -0,0 +1,67 @@
+# Projects using NG
+
+Here is a list of projects currently using, supporting or migrating to QuickJS-NG.
+If you want yours to be listed here, please open a PR!
+
+## [txiki.js](https://github.com/saghul/txiki.js)
+
+A tiny JavaScript runtime.
+
+## [radare2](https://github.com/radareorg/radare2)
+
+Reverse engineering framework.
+
+## [rquickjs](https://github.com/DelSkayn/rquickjs)
+
+High level Rust bindings.
+
+## [llrt](https://github.com/awslabs/llrt)
+
+Lightweight JS runtime for serverless applications.
+
+## [nx.js](https://github.com/TooTallNate/nx.js)
+
+JavaScript runtime for Nintendo Switch homebrew applications.
+
+## [quickjs-rusty](https://github.com/Icemic/quickjs-rusty)
+
+Rust wrapper focus on embedding-ready and no-pain type conversion and interoperability. 
+
+## [GodotJS](https://github.com/godotjs/GodotJS)
+
+This project adds TypeScript/JavaScript support for Godot 4.x. It supports multiple javascript runtimes, including QuickJS-NG.
+
+## [quickjs_es_runtime](https://github.com/HiRoFa/quickjs_es_runtime)
+
+Rust wrapper with typescript, modules, promises, async/await and much more.
+
+## [Lua jsregexp](https://github.com/kmarius/jsregexp)
+
+JavaScript regular expressions for Lua.
+
+## [Edbrowse](https://edbrowse.org)
+
+A combination editor, web-browser, and mail client that is 100% text based.
+
+## [go-quickjs-wasi-reactor](https://github.com/aperturerobotics/go-quickjs-wasi-reactor)
+
+Go module that embeds QuickJS-NG compiled to WebAssembly using the WASI reactor model. Provides re-entrant execution via exported C API functions, a high-level Go API with wazero, non-blocking event loop control, and a command-line REPL.
+
+## [js-quickjs-wasi-reactor](https://github.com/aperturerobotics/js-quickjs-wasi-reactor)
+
+JavaScript/TypeScript harness for running QuickJS-NG in WASI reactor mode. Includes a browser-compatible WASI shim, virtual filesystem, custom I/O handlers, and non-blocking event loop integration for browser and Node.js/Bun environments.
+
+## [quickjs.ml](https://github.com/ml-in-barcelona/quickjs.ml)
+
+OCaml bindings to quickjs-ng. Exposing both low-level C library access (libregexp, libunicode, js_dtoa, js_atod, and cutils) and a high-level API mirroring JavaScript built-ins like RegExp, String, and Number.
+
+## [Python quickjs-ng](https://github.com/genotrance/quickjs-ng)
+
+Python bindings for quickjs-ng based on https://github.com/PetterS/quickjs.
+
+## [Px](https://github.com/genotrance/px)
+
+Proxy server using quickjs-ng for PAC file processing.
+
+## [std::slop](https://github.com/hsaliak/std_slop)
+A C++/SQL based Coding agent. It exposes a QuickJS-ng environment to the LLM. The Agent accomplishes all it's work through this QuickJS-NG based "control plane".