zuzu-js 0.1.0

package/LICENSE

@@ -0,0 +1,5 @@
+zuzu-js is free software; you may redistribute it and/or modify it
+under the terms of either the Artistic License 1.0 or the GNU General
+Public License version 2 or later.
+
+SPDX-License-Identifier: Artistic-1.0 OR GPL-2.0-or-later

package/README.md

@@ -0,0 +1,113 @@
+# ZuzuScript JavaScript Runtime
+
+`zuzu-js` is the JavaScript implementation of ZuzuScript. It provides a
+Node command-line runtime, a browser bundle, an Electron launcher, and a
+compiler that can emit standalone JavaScript from ZuzuScript source.
+
+## Installation
+
+```sh
+npm install -g zuzu-js
+```
+
+The global npm bin directory must be in your `PATH`. After installation,
+the package provides these commands:
+
+- `zuzu`: dispatches to the first available ZuzuScript implementation in
+  `PATH`, checking `zuzu-rust`, `zuzu.pl`, then `zuzu-js`.
+- `zuzu-js`: runs ZuzuScript with the JavaScript runtime.
+- `zuzu-js-compile`: compiles a ZuzuScript program into standalone
+  JavaScript.
+- `zuzu-js-electron`: runs GUI-oriented ZuzuScript programs through
+  Electron.
+
+Set `ZUZU` to force the dispatcher to use a specific implementation:
+
+```sh
+ZUZU=zuzu-js zuzu -e 'say("Hello from ZuzuScript");'
+```
+
+## Command Line
+
+Run inline source:
+
+```sh
+zuzu-js -e 'say("Hello, world");'
+```
+
+Run a script:
+
+```sh
+zuzu-js path/to/script.zzs
+```
+
+Compile a script:
+
+```sh
+zuzu-js-compile path/to/script.zzs -o script.js
+node script.js
+```
+
+Use `zuzu` when you want the first installed ZuzuScript implementation
+available on your `PATH`:
+
+```sh
+zuzu -e 'from std/string import kebab; say kebab("hello world");'
+```
+
+## Browser Bundle
+
+The package includes prebuilt browser assets:
+
+- `dist/zuzu-browser.js`
+- `dist/zuzu-browser-worker.js`
+
+Load the browser bundle from an installed package, copied asset, or your
+application bundler:
+
+```html
+<script src="dist/zuzu-browser.js"></script>
+<script>
+const runtime = ZuzuBrowser.createBrowserRuntime();
+const result = runtime.zuzu_eval('say("Hello from the browser");');
+console.log(result.stdout);
+</script>
+```
+
+The package also contains internal browser bundle helper scripts under
+`bin/`, but they are not installed as global npm commands.
+
+## JavaScript API
+
+```js
+const { createNodeRuntime } = require('zuzu-js');
+
+const runtime = createNodeRuntime();
+runtime.runSource('say("Hello from JavaScript");').then((result) => {
+	process.stdout.write(result.stdout);
+});
+```
+
+The public API is still evolving. The command-line tools and bundled
+runtime entry points are the most stable interfaces.
+
+## Standard Library
+
+The npm package includes JavaScript-backed runtime modules under
+`modules/` and pure ZuzuScript standard-library modules under
+`stdlib/modules/`. Pure ZuzuScript modules are loaded, parsed, and
+evaluated through normal ZuzuScript runtime semantics.
+
+## Status
+
+This is an early npm release of the JavaScript runtime. It is useful for
+running and compiling ZuzuScript programs, but language and standard
+library compatibility are still under active development.
+
+## Licence
+
+`zuzu-js` is free software; you may redistribute it and/or modify it
+under the terms of either the Artistic License 1.0 or the GNU General
+Public License version 2 or later.
+
+SPDX-License-Identifier: `Artistic-1.0 OR GPL-2.0-or-later`

package/bin/zuzu

@@ -0,0 +1,17 @@
+#!/bin/sh
+set -eu
+
+if [ "${ZUZU+x}" = x ] && [ -n "$ZUZU" ]; then
+	export ZUZU
+	exec "$ZUZU" "$@"
+fi
+
+for ZUZU in zuzu-rust zuzu.pl zuzu-js; do
+	if command -v "$ZUZU" >/dev/null 2>&1; then
+		export ZUZU
+		exec "$ZUZU" "$@"
+	fi
+done
+
+echo "zuzu: no ZuzuScript implementation found in PATH" >&2
+exit 127

package/bin/zuzu-build-browser-bundle

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+ROOT_DIR="$( cd -- "${SCRIPT_DIR}/.." >/dev/null 2>&1 && pwd )"
+
+for arg in "$@"; do
+	if [[ "${arg}" == "--help" ]]; then
+		printf '%s\n' \
+			"Usage: zuzu-build-browser-bundle [OPTIONS]" \
+			"" \
+			"Build dist/zuzu-browser.js and zuzu-browser-worker.js." \
+			"" \
+			"Options:" \
+			"  -M DIR                 Add a pure ZuzuScript module directory." \
+			"  -MDIR                  Add a pure ZuzuScript module directory." \
+			"  --include MODULE       Include an additional module." \
+			"  --include=MODULE       Include an additional module." \
+			"  --exclude MODULE       Exclude a bundled module." \
+			"  --exclude=MODULE       Exclude a bundled module." \
+			"  --help                 Show this help text."
+		exit 0
+	fi
+done
+
+mkdir -p "${ROOT_DIR}/dist"
+GEN_DIR="$( mktemp -d "${TMPDIR:-/tmp}/zuzu-browser-build.XXXXXX" )"
+trap 'rm -rf "${GEN_DIR}"' EXIT
+node "${ROOT_DIR}/bin/zuzu-generate-browser-stdlib" "${GEN_DIR}" "$@"
+
+npx --yes esbuild \
+	"${GEN_DIR}/browser-worker-entry.generated.js" \
+	--bundle \
+	--format=iife \
+	--platform=browser \
+	--external:node:* \
+	--external:./host/node-host \
+	--external:./host/node-host.js \
+	--outfile="${ROOT_DIR}/dist/zuzu-browser-worker.js"
+
+node -e 'const fs = require("node:fs"); const source = fs.readFileSync(process.argv[1], "utf8"); fs.writeFileSync(process.argv[2], `"use strict";\n\nmodule.exports = {\n\tbrowserWorkerSource: ${JSON.stringify(source)},\n};\n`, "utf8");' \
+	"${ROOT_DIR}/dist/zuzu-browser-worker.js" \
+	"${GEN_DIR}/browser-worker-source.generated.js"
+
+npx --yes esbuild \
+	"${GEN_DIR}/browser-bundle-entry.generated.js" \
+	--bundle \
+	--format=iife \
+	--global-name=ZuzuBrowser \
+	--platform=browser \
+	--external:node:* \
+	--external:./host/node-host \
+	--external:./host/node-host.js \
+	--outfile="${ROOT_DIR}/dist/zuzu-browser.js"
+
+echo "Built ${ROOT_DIR}/dist/zuzu-browser.js"
+echo "Built ${ROOT_DIR}/dist/zuzu-browser-worker.js"