myjs 0.0.2__py3-none-any.whl

myjs/__init__.py

@@ -0,0 +1,65 @@
+"""myjs -- a small JavaScript interpreter for Python.
+
+It runs a practical subset of ECMAScript (via the ``domonic_libs.acorn`` port and
+its tree-walking evaluator) against domonic's server-side DOM, and hands scripts
+an ``ffi`` global for calling native C libraries through ``ctypes``.
+
+    import myjs
+
+    myjs.eval("window.console.log('hi from myjs')")
+    myjs.run("script.js")
+
+    s = myjs.Session()
+    s.eval("const x = 21;")
+    s.eval("x * 2")            # -> 42
+
+Command line: ``myjs`` starts a REPL, ``myjs file.js`` executes a file.
+"""
+
+def _read_version() -> str:
+    from pathlib import Path
+    f = Path(__file__).resolve().parents[2] / "VERSION"   # repo-root source checkout
+    if f.is_file():
+        return f.read_text().strip()
+    from importlib.metadata import PackageNotFoundError, version
+    try:
+        return version("myjs")
+    except PackageNotFoundError:
+        return "0+unknown"
+
+
+__version__ = _read_version()
+
+from ._engine import JSError, Session
+
+__all__ = ["Session", "JSError", "eval", "run", "repl", "__version__"]
+
+_shared: Session | None = None
+
+
+def _session() -> Session:
+    global _shared
+    if _shared is None:
+        _shared = Session()
+    return _shared
+
+
+def eval(src: str, *, scope: dict | None = None):
+    """Evaluate a string of JavaScript and return its completion value.
+
+    With ``scope`` a throwaway :class:`Session` is used; otherwise a process-wide
+    session persists definitions between calls.
+    """
+    return (Session(scope=scope) if scope else _session()).eval(src)
+
+
+def run(path: str, *, scope: dict | None = None):
+    """Execute a ``.js`` file. Returns its completion value."""
+    return Session(scope=scope).run_file(path)
+
+
+def repl(**kwargs) -> int:
+    """Start the interactive REPL. Returns a process exit code."""
+    from .repl import repl as _repl
+
+    return _repl(**kwargs)

myjs/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

myjs/_engine.py

@@ -0,0 +1,125 @@
+"""The myjs session: a persistent JS interpreter over domonic's DOM + ``ffi``."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from domonic_libs.acorn.interpret import (
+    UNDEFINED,
+    JSThrow,
+    _Console,
+    _stringify,
+    make_interpreter,
+)
+
+from .ffi import scope as _ffi_scope
+from .host import async_fetch as _async_fetch
+from .host import scope as _host_scope
+from .host import websocket_ctor as _websocket_ctor
+
+
+class PrintConsole(_Console):
+    """Captures like the base console, and echoes each line to stdout."""
+
+    def log(self, *a):
+        super().log(*a)
+        print(self.lines[-1])
+
+    warn = error = info = debug = trace = log
+
+
+class JSError(Exception):
+    """A JavaScript exception (or syntax error) that escaped the script."""
+
+    def __init__(self, message, *, name="Error", line=None, trace=None):
+        super().__init__(message)
+        self.js_name = name
+        self.js_line = line
+        self.js_trace = trace
+
+    def __str__(self):
+        base = super().__str__()
+        where = f"  (line {self.js_line})" if self.js_line else ""
+        stack = f"\n  at {self.js_trace}" if self.js_trace else ""
+        return f"{self.js_name}: {base}{where}{stack}"
+
+
+def _reraise(exc):
+    val = getattr(exc, "value", None)
+    if isinstance(val, dict):
+        raise JSError(
+            val.get("message", ""),
+            name=val.get("name", "Error"),
+            line=getattr(exc, "js_line", None),
+            trace=getattr(exc, "js_trace", None),
+        ) from None
+    raise JSError(
+        str(exc),
+        name=type(exc).__name__,
+        line=getattr(exc, "js_line", None),
+        trace=getattr(exc, "js_trace", None),
+    ) from None
+
+
+class Session:
+    """One JS global scope. Feed it source with :meth:`eval`; state persists."""
+
+    def __init__(self, scope=None, console=None):
+        from . import __version__
+
+        extra = {**_ffi_scope(), **_host_scope(__version__)}
+        if scope:
+            extra.update(scope)
+        self.interp, self.console, self.document, self.window = make_interpreter(
+            extra_globals=extra, console=console
+        )
+        for name, value in (
+            ("fetch", _async_fetch(self.interp.loop)),
+            ("WebSocket", _websocket_ctor(self.interp.loop)),
+        ):
+            self.interp.global_env.declare(name, value)
+            self.window._own[name] = value
+
+    def eval(self, src, ecma_version=2022):
+        """Run ``src`` and return its completion value (``None`` for undefined)."""
+        try:
+            result = self.interp.run(src, ecma_version=ecma_version)
+        except (JSThrow, SyntaxError) as exc:
+            _reraise(exc)
+        return None if result is UNDEFINED else result
+
+    def run_file(self, path, ecma_version=2022):
+        p = Path(path).resolve()
+        self.interp.module_base = str(p.parent)
+        self.interp._cur_module["dir"] = str(p.parent)
+        return self.eval(p.read_text(), ecma_version=ecma_version)
+
+    @property
+    def console_lines(self):
+        return list(getattr(self.console, "lines", []))
+
+    def render_html(self):
+        """Serialise the DOM the script built into a standalone HTML document."""
+        try:
+            title = self.document.title
+        except Exception:
+            title = None
+        try:
+            root = str(self.document.documentElement)
+        except Exception:
+            root = f"<html><head></head><body>{self.document.body}</body></html>"
+        if title and isinstance(title, str) and "<title>" not in root:
+            root = root.replace("<head>", f"<head><title>{title}</title>", 1)
+        return "<!doctype html>\n" + root
+
+    @staticmethod
+    def display(value):
+        """Human-readable form of a completion value, for a REPL."""
+        if value is None or value is UNDEFINED:
+            return "undefined"
+        if isinstance(value, str):
+            return repr(value)
+        try:
+            return _stringify(value)
+        except Exception:
+            return repr(value)

myjs/cli.py

@@ -0,0 +1,87 @@
+"""``myjs`` command line: run a script, evaluate a snippet, or start a REPL."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from ._engine import JSError, PrintConsole, Session
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="myjs",
+        description="A small JavaScript interpreter on domonic's DOM, with an ffi bridge to native C.",
+    )
+    p.add_argument("script", nargs="?", help="a .js file to execute (omit for a REPL)")
+    p.add_argument("args", nargs="*", help="arguments passed to the script as globalThis.argv")
+    p.add_argument("-e", "--eval", dest="code", metavar="JS", help="evaluate a string and print the result")
+    p.add_argument("-i", "--interactive", action="store_true", help="enter the REPL after running")
+    p.add_argument("--gui", action="store_true",
+                   help="after running, show the DOM the script built in a native window")
+    p.add_argument("--version", action="version", version=f"myjs {__version__}")
+    return p
+
+
+def _open_gui(session: Session) -> int:
+    try:
+        import webview
+    except ImportError:
+        print("myjs --gui needs pywebview:  pip install 'domonic-libs[app]'", file=sys.stderr)
+        return 1
+    try:
+        title = session.eval("document.title") or "myjs"
+    except JSError:
+        title = "myjs"
+    webview.create_window(str(title) or "myjs", html=session.render_html(),
+                          width=960, height=720)
+    webview.start()
+    return 0
+
+
+def _report(exc: JSError) -> None:
+    print(exc, file=sys.stderr)
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.code is not None:
+        session = Session(console=PrintConsole())
+        try:
+            result = session.eval(args.code)
+        except JSError as exc:
+            _report(exc)
+            return 1
+        if result is not None:
+            print(result if isinstance(result, str) else session.display(result))
+        if args.interactive:
+            from .repl import repl
+            return repl(session)
+        return 0
+
+    if args.script:
+        session = Session(console=PrintConsole())
+        session.interp.global_env.declare("argv", list(args.args))
+        try:
+            session.run_file(args.script)
+        except FileNotFoundError:
+            print(f"myjs: cannot open {args.script}", file=sys.stderr)
+            return 1
+        except JSError as exc:
+            _report(exc)
+            return 1
+        if args.gui:
+            return _open_gui(session)
+        if args.interactive:
+            from .repl import repl
+            return repl(session)
+        return 0
+
+    from .repl import repl
+    return repl()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

myjs/ffi.py

@@ -0,0 +1,238 @@
+"""``ffi`` -- call native C libraries from JavaScript, via Python's ``ctypes``.
+
+Exposed to scripts as the global ``ffi`` (plus a small ``os`` namespace). The
+interpreter reaches arbitrary Python objects through ``getattr`` / ``setattr`` /
+``__call__``, so the wrappers here are thin: a :class:`Library` yields
+:class:`CFunc` proxies that marshal JS values to and from C.
+
+    const libc = ffi.loadLibrary("c");
+    libc.abs.argtypes = [ffi.types.int];
+    libc.abs.restype  = ffi.types.int;
+    console.log(libc.abs(-42));            // 42
+
+Strings are encoded to UTF-8 ``bytes`` on the way in and decoded on the way out;
+a :class:`Buffer` (from ``ffi.createStringBuffer``) passes its underlying storage
+straight through. C -> JS callbacks are built with ``ffi.callback``.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import os
+import sys
+
+# --- C type table ---------------------------------------------------------
+
+TYPES = {
+    "void": None,
+    "bool": ctypes.c_bool,
+    "char": ctypes.c_char,
+    "schar": ctypes.c_char,
+    "uchar": ctypes.c_ubyte,
+    "byte": ctypes.c_ubyte,
+    "short": ctypes.c_short,
+    "ushort": ctypes.c_ushort,
+    "int": ctypes.c_int,
+    "uint": ctypes.c_uint,
+    "long": ctypes.c_long,
+    "ulong": ctypes.c_ulong,
+    "longlong": ctypes.c_longlong,
+    "ulonglong": ctypes.c_ulonglong,
+    "int8": ctypes.c_int8,
+    "uint8": ctypes.c_uint8,
+    "int16": ctypes.c_int16,
+    "uint16": ctypes.c_uint16,
+    "int32": ctypes.c_int32,
+    "uint32": ctypes.c_uint32,
+    "int64": ctypes.c_int64,
+    "uint64": ctypes.c_uint64,
+    "size_t": ctypes.c_size_t,
+    "ssize_t": ctypes.c_ssize_t,
+    "float": ctypes.c_float,
+    "double": ctypes.c_double,
+    "string": ctypes.c_char_p,
+    "wstring": ctypes.c_wchar_p,
+    "pointer": ctypes.c_void_p,
+}
+
+
+# --- marshalling ---------------------------------------------------------
+
+def _to_c(value):
+    """JS value -> something ctypes accepts as an argument."""
+    if isinstance(value, Buffer):
+        return value._buf
+    if isinstance(value, CFunc):
+        return value._ptr
+    if isinstance(value, str):
+        return value.encode("utf-8")
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return value
+
+
+def _from_c(value):
+    """ctypes return value -> JS-friendly value."""
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace")
+    return value
+
+
+# --- library / function proxies ---------------------------------------------
+
+class CFunc:
+    """A single C function. ``argtypes`` / ``restype`` accept ``ffi.types`` and
+    are forwarded to the underlying ctypes pointer."""
+
+    def __init__(self, ptr, name):
+        object.__setattr__(self, "_ptr", ptr)
+        object.__setattr__(self, "_name", name)
+
+    def __call__(self, *args):
+        try:
+            return _from_c(self._ptr(*[_to_c(a) for a in args]))
+        except Exception as exc:  # surfaced to JS as a thrown error
+            raise RuntimeError(f"ffi call {self._name}(): {exc}") from exc
+
+    def __setattr__(self, key, value):
+        if key == "argtypes":
+            self._ptr.argtypes = [t for t in value if t is not None] or None
+        elif key == "restype":
+            self._ptr.restype = value
+        elif key == "errcheck":
+            self._ptr.errcheck = value
+        else:
+            object.__setattr__(self, key, value)
+
+    def __getattr__(self, key):
+        if key.startswith("__") and key.endswith("__"):
+            raise AttributeError(key)
+        return getattr(object.__getattribute__(self, "_ptr"), key)
+
+    def __repr__(self):
+        return f"<ffi function {self._name}>"
+
+
+class Library:
+    """A loaded shared library. ``lib.<name>`` resolves a :class:`CFunc`."""
+
+    def __init__(self, cdll, name):
+        object.__setattr__(self, "_cdll", cdll)
+        object.__setattr__(self, "_name", name)
+        object.__setattr__(self, "_cache", {})
+
+    def __getattr__(self, key):
+        if key.startswith("__") and key.endswith("__"):
+            raise AttributeError(key)
+        cache = object.__getattribute__(self, "_cache")
+        if key not in cache:
+            try:
+                cache[key] = CFunc(getattr(self._cdll, key), key)
+            except AttributeError:
+                raise AttributeError(f"{self._name!r} has no symbol {key!r}")
+        return cache[key]
+
+    def __repr__(self):
+        return f"<ffi library {self._name!r}>"
+
+
+class Buffer:
+    """A mutable C string / byte buffer (``ffi.createStringBuffer``)."""
+
+    def __init__(self, buf):
+        object.__setattr__(self, "_buf", buf)
+
+    @property
+    def value(self):
+        return self._buf.value.decode("utf-8", "replace")
+
+    @value.setter
+    def value(self, v):
+        self._buf.value = v.encode("utf-8") if isinstance(v, str) else v
+
+    @property
+    def raw(self):
+        return self._buf.raw
+
+    @property
+    def length(self):
+        return len(self._buf)
+
+    def __len__(self):
+        return len(self._buf)
+
+    def __repr__(self):
+        return f"<ffi buffer {self.value!r}>"
+
+
+# --- loading -----------------------------------------------------------------
+
+def load_library(name):
+    """Load a shared library by short name (``"c"``, ``"m"``), by path
+    (``"./libfoo.so"``), or -- on macOS -- by system-framework name
+    (``"CoreFoundation"``)."""
+    if os.sep in str(name) or str(name).endswith((".so", ".dylib", ".dll")):
+        return Library(ctypes.CDLL(name), name)
+    found = ctypes.util.find_library(name)
+    if found:
+        return Library(ctypes.CDLL(found), name)
+    if sys.platform == "darwin":
+        fw = f"/System/Library/Frameworks/{name}.framework/{name}"
+        if os.path.exists(fw):
+            return Library(ctypes.CDLL(fw), name)
+    return Library(ctypes.CDLL(name), name)  # let ctypes raise a clear OSError
+
+
+def create_string_buffer(init):
+    if isinstance(init, str):
+        return Buffer(ctypes.create_string_buffer(init.encode("utf-8")))
+    if isinstance(init, (int, float)):
+        return Buffer(ctypes.create_string_buffer(int(init)))
+    if isinstance(init, (bytes, bytearray)):
+        return Buffer(ctypes.create_string_buffer(bytes(init)))
+    raise TypeError("createStringBuffer expects a string or a size")
+
+
+def make_callback(restype, argtypes, fn):
+    """Wrap a JS function as a C callback pointer (``CFUNCTYPE``)."""
+    proto = ctypes.CFUNCTYPE(restype, *[t for t in (argtypes or []) if t is not None])
+
+    def thunk(*c_args):
+        return _to_c(fn(*[_from_c(a) for a in c_args]))
+
+    holder = proto(thunk)
+    _CALLBACK_KEEPALIVE.append(holder)  # ctypes callbacks must outlive the call
+    return holder
+
+
+_CALLBACK_KEEPALIVE = []
+
+
+def c_string(ptr):
+    """Read a NUL-terminated C string at ``ptr`` (an int address or c_char_p)."""
+    return ctypes.cast(ptr, ctypes.c_char_p).value.decode("utf-8", "replace")
+
+
+# --- the scope handed to the interpreter -----------------------------------
+
+FFI = {
+    "loadLibrary": load_library,
+    "createStringBuffer": create_string_buffer,
+    "callback": make_callback,
+    "string": c_string,
+    "sizeof": lambda t: ctypes.sizeof(t),
+    "addressof": lambda b: ctypes.addressof(b._buf if isinstance(b, Buffer) else b),
+    "cast": lambda v, t: ctypes.cast(_to_c(v), t),
+    "pointer": ctypes.pointer,
+    "byref": ctypes.byref,
+    "NULL": None,
+    "errno": lambda: ctypes.get_errno(),
+    "types": dict(TYPES),
+}
+
+def scope():
+    """Fresh copies so one session cannot mutate another's ``ffi.types``."""
+    return {"ffi": {**FFI, "types": dict(TYPES)}}

myjs/host.py

@@ -0,0 +1,568 @@
+"""Host bindings for myjs -- the things that make "it's just JavaScript" land:
+a filesystem (``fs``), shell (``sh``), synchronous HTTP (``http`` / ``fetch``),
+a ``process`` object, and ``py`` for reaching into the whole Python ecosystem.
+
+Everything here is synchronous on purpose -- there is no event loop yet, and a
+one-liner that blocks is what reads as magic in a REPL. All of it is handed to
+scripts as globals (see :func:`scope`).
+"""
+
+from __future__ import annotations
+
+import base64 as _base64
+import hashlib as _hashlib
+import importlib
+import json as _json
+import os
+import platform
+import shutil
+import socket as _socket
+import ssl as _ssl
+import subprocess
+import sys
+import threading
+import time as _time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+from domonic_libs.acorn.interpret import JSArray, JSObject
+
+
+# --- fs --------------------------------------------------------------------
+
+def _read_file(path, encoding="utf-8"):
+    data = Path(path).read_bytes()
+    return data if encoding in (None, "buffer", "binary") else data.decode(encoding)
+
+
+def _write_file(path, data, encoding="utf-8"):
+    p = Path(path)
+    if isinstance(data, (bytes, bytearray)):
+        p.write_bytes(bytes(data))
+    else:
+        p.write_text(str(data), encoding=encoding)
+    return len(data)
+
+
+def _append_file(path, data, encoding="utf-8"):
+    with open(path, "a", encoding=encoding) as fh:
+        fh.write(str(data))
+
+
+def _stat(path):
+    st = os.stat(path)
+    return JSObject({
+        "size": st.st_size,
+        "mtimeMs": st.st_mtime * 1000,
+        "isFile": os.path.isfile(path),
+        "isDirectory": os.path.isdir(path),
+        "mode": st.st_mode,
+    })
+
+
+def _mkdir(path, opts=None):
+    recursive = bool(opts and opts.get("recursive"))
+    Path(path).mkdir(parents=recursive, exist_ok=recursive)
+
+
+def _rm(path, opts=None):
+    opts = opts or {}
+    p = Path(path)
+    if p.is_dir() and opts.get("recursive"):
+        shutil.rmtree(p, ignore_errors=bool(opts.get("force")))
+    elif p.exists() or not opts.get("force"):
+        p.unlink()
+
+
+FS = {
+    "readFileSync": _read_file,
+    "writeFileSync": _write_file,
+    "appendFileSync": _append_file,
+    "existsSync": lambda p: Path(p).exists(),
+    "readdirSync": lambda p: JSArray(sorted(os.listdir(p))),
+    "mkdirSync": _mkdir,
+    "rmSync": _rm,
+    "renameSync": lambda a, b: os.replace(a, b),
+    "copyFileSync": lambda a, b: shutil.copyfile(a, b),
+    "statSync": _stat,
+    "realpathSync": lambda p: str(Path(p).resolve()),
+    "cwd": os.getcwd,
+}
+
+PATH = {
+    "join": lambda *parts: os.path.join(*[str(p) for p in parts]),
+    "dirname": lambda p: os.path.dirname(p),
+    "basename": lambda p, ext="": os.path.basename(p)[: -len(ext)] if ext and os.path.basename(p).endswith(ext) else os.path.basename(p),
+    "extname": lambda p: os.path.splitext(p)[1],
+    "resolve": lambda *parts: str(Path(*[str(p) for p in parts]).resolve()) if parts else os.getcwd(),
+    "sep": os.sep,
+}
+
+
+# --- sh -------------------------------------------------------------------
+
+class ShellResult(JSObject):
+    def __init__(self, proc):
+        super().__init__({
+            "stdout": proc.stdout,
+            "stderr": proc.stderr,
+            "code": proc.returncode,
+            "ok": proc.returncode == 0,
+        })
+
+    def __str__(self):
+        return self["stdout"]
+
+    def trim(self):
+        return self["stdout"].strip()
+
+    def json(self):
+        return _to_js(_json.loads(self["stdout"]))
+
+    def lines(self):
+        return JSArray(self["stdout"].splitlines())
+
+
+def _sh(cmd, opts=None):
+    opts = opts or {}
+    proc = subprocess.run(
+        cmd, shell=True, capture_output=True, text=True,
+        cwd=opts.get("cwd"), timeout=opts.get("timeout"),
+    )
+    return ShellResult(proc)
+
+
+def _say(text, *_):
+    if sys.platform == "darwin":
+        subprocess.run(["say", str(text)], check=False)
+    elif sys.platform.startswith("linux") and shutil.which("espeak"):
+        subprocess.run(["espeak", str(text)], check=False)
+    else:
+        print(f"\a(say) {text}")
+
+
+def _osa(script):
+    subprocess.run(["osascript", "-e", script], check=False, capture_output=True)
+
+
+def _notify(text, title="myjs"):
+    if sys.platform == "darwin":
+        _osa(f'display notification {_json.dumps(str(text))} with title {_json.dumps(str(title))}')
+    elif shutil.which("notify-send"):
+        subprocess.run(["notify-send", str(title), str(text)], check=False)
+    else:
+        print(f"(notify) {title}: {text}")
+
+
+def _alert(text, title="myjs"):
+    if sys.platform == "darwin":
+        _osa(f'display dialog {_json.dumps(str(text))} with title {_json.dumps(str(title))} '
+             f'buttons {{"OK"}} default button "OK"')
+    else:
+        print(f"(alert) {title}: {text}")
+
+
+def _open(target, *_):
+    opener = {"darwin": "open", "win32": "start"}.get(sys.platform, "xdg-open")
+    subprocess.run([opener, str(target)], check=False, shell=(opener == "start"))
+
+
+# --- http / fetch --------------------------------------------------------
+
+class Response(JSObject):
+    def __init__(self, url, status, headers, body):
+        super().__init__({
+            "url": url,
+            "status": status,
+            "ok": 200 <= status < 300,
+            "headers": JSObject({k.lower(): v for k, v in headers}),
+        })
+        self._body = body
+
+    @property
+    def text(self):
+        return self._body.decode("utf-8", "replace")
+
+    def json(self):
+        return _to_js(_json.loads(self._body.decode("utf-8", "replace")))
+
+    def bytes(self):
+        return self._body
+
+
+def _request(url, opts=None):
+    opts = opts or {}
+    data = opts.get("body")
+    if data is not None and not isinstance(data, (bytes, bytearray)):
+        data = str(data).encode("utf-8")
+    headers = {k: str(v) for k, v in (opts.get("headers") or {}).items()}
+    req = urllib.request.Request(url, data=data, headers=headers, method=opts.get("method"))
+    try:
+        with urllib.request.urlopen(req, timeout=opts.get("timeout", 30)) as resp:
+            return Response(resp.geturl(), resp.status, resp.getheaders(), resp.read())
+    except urllib.error.HTTPError as e:
+        return Response(url, e.code, list(e.headers.items()), e.read())
+
+
+HTTP = {
+    "get": lambda url, opts=None: _request(url, {**(opts or {}), "method": "GET"}),
+    "post": lambda url, body=None, opts=None: _request(url, {**(opts or {}), "method": "POST", "body": body}),
+    "request": _request,
+    "requestSync": _request,
+    "serve": None,  # set in scope() -- needs the calling session's interpreter
+}
+
+
+def async_fetch(loop):
+    """A real asynchronous ``fetch``: the request runs on a background thread and
+    settles a promise through ``loop``, so ``await Promise.all([...])`` genuinely
+    runs requests concurrently."""
+    import threading
+
+    from domonic_libs.acorn.interpret import _make_error, _Promise
+
+    def fetch(url, opts=None):
+        p = _Promise(loop)
+        loop.io_start()
+
+        def worker():
+            try:
+                resp = _request(url, opts)
+                loop.io_finish(lambda: p._resolve(resp))
+            except Exception as exc:  # noqa: BLE001
+                loop.io_finish(lambda exc=exc: p._reject(_make_error("TypeError", f"fetch failed: {exc}")))
+
+        threading.Thread(target=worker, daemon=True).start()
+        return p
+
+    return fetch
+
+
+def _make_serve():
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+
+    def serve(port, handler):
+        class H(BaseHTTPRequestHandler):
+            def _run(self):
+                length = int(self.headers.get("content-length", 0) or 0)
+                body = self.rfile.read(length).decode("utf-8", "replace") if length else ""
+                req = JSObject({
+                    "method": self.command,
+                    "path": self.path,
+                    "headers": JSObject(dict(self.headers)),
+                    "body": body,
+                })
+                out = handler(req)
+                if isinstance(out, dict):
+                    status = int(out.get("status", 200))
+                    text = str(out.get("body", ""))
+                    extra = out.get("headers") or {}
+                else:
+                    status, text, extra = 200, str(out), {}
+                payload = text.encode("utf-8")
+                self.send_response(status)
+                self.send_header("content-type", extra.get("content-type", "text/html; charset=utf-8"))
+                self.send_header("content-length", str(len(payload)))
+                for k, v in extra.items():
+                    if k != "content-type":
+                        self.send_header(k, str(v))
+                self.end_headers()
+                self.wfile.write(payload)
+
+            do_GET = do_POST = do_PUT = do_DELETE = _run
+
+            def log_message(self, *a):  # quiet
+                pass
+
+        srv = HTTPServer(("127.0.0.1", int(port)), H)
+        print(f"myjs http.serve listening on http://127.0.0.1:{int(port)}  (Ctrl-C to stop)")
+        try:
+            srv.serve_forever()
+        except KeyboardInterrupt:
+            print("\nstopped")
+        finally:
+            srv.server_close()
+
+    return serve
+
+
+# --- WebSocket (RFC 6455 client, dependency-free) --------------------------
+
+def _fire(handler, event):
+    if callable(handler):
+        handler(event)
+
+
+class WebSocketClient:
+    CONNECTING, OPEN, CLOSING, CLOSED = 0, 1, 2, 3
+
+    def __init__(self, url, loop, protocols=None):
+        self.url = url
+        self.protocol = ""
+        self.readyState = self.CONNECTING
+        self.onopen = self.onmessage = self.onclose = self.onerror = None
+        self._loop = loop
+        self._sock = None
+        self._buf = b""
+        loop.io_start()
+        threading.Thread(target=self._run, daemon=True).start()
+
+    # -- lifecycle
+    def _run(self):
+        try:
+            self._connect()
+            self.readyState = self.OPEN
+            self._loop.post(lambda: _fire(self.onopen, JSObject({"type": "open"})))
+            self._read_loop()
+        except Exception as exc:  # noqa: BLE001
+            self._loop.post(lambda exc=exc: _fire(self.onerror, JSObject({"type": "error", "message": str(exc)})))
+        finally:
+            self.readyState = self.CLOSED
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+            self._loop.io_finish(lambda: _fire(self.onclose, JSObject({"type": "close"})))
+
+    def _connect(self):
+        u = urllib.parse.urlparse(self.url)
+        port = u.port or (443 if u.scheme == "wss" else 80)
+        raw = _socket.create_connection((u.hostname, port), timeout=10)
+        if u.scheme == "wss":
+            raw = _ssl.create_default_context().wrap_socket(raw, server_hostname=u.hostname)
+        key = _base64.b64encode(os.urandom(16)).decode()
+        path = (u.path or "/") + (f"?{u.query}" if u.query else "")
+        raw.sendall((
+            f"GET {path} HTTP/1.1\r\nHost: {u.hostname}\r\nUpgrade: websocket\r\n"
+            f"Connection: Upgrade\r\nSec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n"
+        ).encode())
+        resp = b""
+        while b"\r\n\r\n" not in resp:
+            chunk = raw.recv(4096)
+            if not chunk:
+                raise ConnectionError("connection closed during handshake")
+            resp += chunk
+        if b" 101 " not in resp.split(b"\r\n", 1)[0]:
+            raise RuntimeError(f"handshake rejected: {resp.splitlines()[0].decode('latin1')}")
+        self._sock = raw
+        self._buf = resp.split(b"\r\n\r\n", 1)[1]
+
+    # -- framing
+    def _recv(self, n):
+        while len(self._buf) < n:
+            chunk = self._sock.recv(65536)
+            if not chunk:
+                raise ConnectionError("closed")
+            self._buf += chunk
+        out, self._buf = self._buf[:n], self._buf[n:]
+        return out
+
+    def _read_loop(self):
+        while self.readyState == self.OPEN:
+            b1, b2 = self._recv(2)
+            opcode = b1 & 0x0F
+            length = b2 & 0x7F
+            if length == 126:
+                length = int.from_bytes(self._recv(2), "big")
+            elif length == 127:
+                length = int.from_bytes(self._recv(8), "big")
+            payload = self._recv(length)
+            if b2 & 0x80:
+                mask = payload[:4]
+                payload = bytes(c ^ mask[i % 4] for i, c in enumerate(payload[4:]))
+            if opcode == 0x8:
+                return
+            if opcode == 0x9:
+                self._frame(0xA, payload)
+                continue
+            if opcode in (0x1, 0x2):
+                data = payload.decode("utf-8", "replace") if opcode == 0x1 else payload
+                self._loop.post(lambda d=data: _fire(self.onmessage, JSObject({"type": "message", "data": d})))
+
+    def _frame(self, opcode, data):
+        if isinstance(data, str):
+            data = data.encode("utf-8")
+        mask = os.urandom(4)
+        body = bytes(c ^ mask[i % 4] for i, c in enumerate(data))
+        header = bytes([0x80 | opcode])
+        n = len(data)
+        if n < 126:
+            header += bytes([0x80 | n])
+        elif n < 65536:
+            header += bytes([0x80 | 126]) + n.to_bytes(2, "big")
+        else:
+            header += bytes([0x80 | 127]) + n.to_bytes(8, "big")
+        self._sock.sendall(header + mask + body)
+
+    # -- JS surface
+    def send(self, data):
+        if self.readyState != self.OPEN:
+            raise RuntimeError("WebSocket is not open")
+        self._frame(0x1 if isinstance(data, str) else 0x2, data)
+
+    def close(self, code=1000, reason=""):
+        if self.readyState == self.OPEN:
+            self.readyState = self.CLOSING
+            try:
+                self._frame(0x8, int(code).to_bytes(2, "big"))
+            except Exception:
+                pass
+
+    def addEventListener(self, event, fn):
+        setattr(self, "on" + event, fn)
+
+    def removeEventListener(self, event, fn=None):
+        setattr(self, "on" + event, None)
+
+
+def websocket_ctor(loop):
+    def WebSocket(url, protocols=None, *_):
+        return WebSocketClient(url, loop, protocols)
+    WebSocket.CONNECTING = 0
+    WebSocket.OPEN = 1
+    WebSocket.CLOSING = 2
+    WebSocket.CLOSED = 3
+    return WebSocket
+
+
+# --- py: the whole Python ecosystem ------------------------------------------
+
+def _to_js(v):
+    if isinstance(v, dict):
+        return JSObject({k: _to_js(val) for k, val in v.items()})
+    if isinstance(v, (list, tuple)):
+        return JSArray(_to_js(x) for x in v)
+    return v
+
+
+PY = {
+    "import": importlib.import_module,
+    "eval": lambda expr: eval(expr, {}),  # noqa: S307 - explicit host feature
+    "list": lambda it: JSArray(it),
+    "dict": lambda o: JSObject(dict(o)),
+    "tuple": lambda it: tuple(it),
+    "repr": repr,
+    "str": str,
+    "int": int,
+    "float": float,
+    "len": len,
+    "dir": lambda o: JSArray(dir(o)),
+    "type": lambda o: type(o).__name__,
+    "toJS": _to_js,
+}
+
+
+# --- os (Node-flavoured) -------------------------------------------------
+
+def _totalmem():
+    try:
+        return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+    except (ValueError, AttributeError, OSError):
+        return None
+
+
+def _cpus():
+    n = os.cpu_count() or 1
+    model = platform.processor() or platform.machine()
+    if sys.platform == "darwin":
+        try:
+            model = subprocess.run(
+                ["sysctl", "-n", "machdep.cpu.brand_string"],
+                capture_output=True, text=True, check=True,
+            ).stdout.strip() or model
+        except Exception:
+            pass
+    return JSArray(JSObject({"model": model}) for _ in range(n))
+
+
+OS = {
+    "platform": lambda: sys.platform if sys.platform != "win32" else "win32",
+    "arch": lambda: {"AMD64": "x64", "x86_64": "x64"}.get(platform.machine(), platform.machine()),
+    "type": platform.system,
+    "release": platform.release,
+    "version": lambda: platform.version(),
+    "hostname": platform.node,
+    "homedir": lambda: os.path.expanduser("~"),
+    "tmpdir": lambda: __import__("tempfile").gettempdir(),
+    "cpus": _cpus,
+    "totalmem": _totalmem,
+    "uptime": lambda: _time.clock_gettime(_time.CLOCK_MONOTONIC) if hasattr(_time, "CLOCK_MONOTONIC") else None,
+    "userInfo": lambda *_: JSObject({
+        "username": __import__("getpass").getuser(),
+        "homedir": os.path.expanduser("~"),
+        "shell": os.environ.get("SHELL"),
+    }),
+    "EOL": os.linesep,
+    "python": platform.python_version(),
+    # convenience shorthands (not Node, but handy in a REPL)
+    "system": platform.system,
+    "name": platform.system(),
+}
+
+
+# --- process --------------------------------------------------------------
+
+def _process(myjs_version):
+    return JSObject({
+        "argv": JSArray(sys.argv[1:]),
+        "env": JSObject(dict(os.environ)),
+        "platform": sys.platform,
+        "arch": platform.machine(),
+        "pid": os.getpid(),
+        "version": f"myjs/{myjs_version}",
+        "cwd": os.getcwd,
+        "chdir": os.chdir,
+        "exit": lambda code=0: sys.exit(int(code)),
+        "hrtime": lambda *_: _time.perf_counter_ns(),
+    })
+
+
+# --- assembly ------------------------------------------------------------
+
+def scope(myjs_version="0.0.1"):
+    fs = dict(FS)
+    http = dict(HTTP)
+    http["serve"] = _make_serve()
+    os_ns = dict(OS)
+    require_table = {
+        "fs": fs, "path": dict(PATH), "http": http, "https": http, "os": os_ns,
+        "child_process": {"exec": _sh, "execSync": lambda c, o=None: _sh(c, o)["stdout"]},
+        "crypto": {
+            "md5": lambda s: _hashlib.md5(str(s).encode()).hexdigest(),
+            "sha256": lambda s: _hashlib.sha256(str(s).encode()).hexdigest(),
+            "randomUUID": lambda: __import__("uuid").uuid4().hex,
+        },
+    }
+
+    def require(name):
+        if name.startswith("node:"):
+            name = name[5:]
+        if name in require_table and require_table[name] is not None:
+            return require_table[name]
+        return importlib.import_module(name)  # fall through to any Python module
+
+    return {
+        "fs": fs,
+        "path": dict(PATH),
+        "http": http,
+        "os": os_ns,
+        "sh": _sh,
+        "say": _say,
+        "notify": _notify,
+        "alert": _alert,
+        "open": _open,
+        "fetchSync": _request,   # `fetch` (async) is installed per-session by the engine
+        "process": _process(myjs_version),
+        "py": dict(PY),
+        "require": require,
+        "atob": lambda s: _base64.b64decode(s).decode("utf-8", "replace"),
+        "btoa": lambda s: _base64.b64encode(str(s).encode("utf-8")).decode("ascii"),
+        "sleep": _time.sleep,
+        "now": lambda: _time.time() * 1000,
+        "hash": {
+            "md5": lambda s: _hashlib.md5(str(s).encode()).hexdigest(),
+            "sha256": lambda s: _hashlib.sha256(str(s).encode()).hexdigest(),
+        },
+    }

myjs/repl.py

@@ -0,0 +1,90 @@
+"""The ``myjs`` interactive REPL."""
+
+from __future__ import annotations
+
+import sys
+
+from . import __version__
+from ._engine import JSError, PrintConsole, Session
+
+
+def _incomplete(src: str) -> bool:
+    """True if ``src`` has unclosed brackets / strings / block comments -- a
+    cheap heuristic so the REPL keeps reading multi-line input."""
+    depth = 0
+    i, n = 0, len(src)
+    quote = None
+    while i < n:
+        c = src[i]
+        if quote:
+            if c == "\\":
+                i += 2
+                continue
+            if c == quote:
+                quote = None
+        elif c in "\"'`":
+            quote = c
+        elif c == "/" and i + 1 < n and src[i + 1] == "/":
+            nl = src.find("\n", i)
+            if nl == -1:
+                return False
+            i = nl
+        elif c == "/" and i + 1 < n and src[i + 1] == "*":
+            end = src.find("*/", i + 2)
+            if end == -1:
+                return True
+            i = end + 1
+        elif c in "([{":
+            depth += 1
+        elif c in ")]}":
+            depth -= 1
+        i += 1
+    return depth > 0 or quote in ('`',)
+
+
+def repl(session: Session | None = None) -> int:
+    session = session or Session(console=PrintConsole())
+    print(f"myjs {__version__} - JavaScript on domonic. Ctrl-D or .exit to quit, .help for help.")
+    buffer = ""
+    while True:
+        prompt = "... " if buffer else "js> "
+        try:
+            line = input(prompt)
+        except EOFError:
+            print()
+            return 0
+        except KeyboardInterrupt:
+            print("^C")
+            buffer = ""
+            continue
+
+        if not buffer and line.strip() in (".exit", ".quit"):
+            return 0
+        if not buffer and line.strip() == ".help":
+            print("  .exit    quit\n  .clear   reset the session\n  .help    this message\n"
+                  "  _        the last result\n  ffi, os  native bindings; window/document the DOM")
+            continue
+        if not buffer and line.strip() == ".clear":
+            session = Session(console=PrintConsole())
+            print("(session cleared)")
+            continue
+
+        buffer = f"{buffer}\n{line}" if buffer else line
+        if _incomplete(buffer):
+            continue
+
+        src, buffer = buffer, ""
+        if not src.strip():
+            continue
+        try:
+            result = session.eval(src)
+        except JSError as exc:
+            print(exc, file=sys.stderr)
+            continue
+        except RecursionError:
+            print("RangeError: Maximum call stack size exceeded", file=sys.stderr)
+            continue
+        if result is not None:
+            session.interp.global_env.declare("_", result)
+            print(session.display(result))
+    return 0

myjs-0.0.2.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: myjs
+Version: 0.0.2
+Summary: A JavaScript interpreter for Python -- run .js against a DOM, call native C via ffi, reach the Python ecosystem
+Author-email: byteface <byteface@googlemail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/byteface/domonic-libs/tree/master/src/myjs
+Project-URL: Source, https://github.com/byteface/domonic-libs
+Project-URL: Documentation, https://github.com/byteface/domonic-libs/blob/master/docs/myjs.md
+Project-URL: Tracker, https://github.com/byteface/domonic-libs/issues
+Keywords: javascript,interpreter,ecmascript,acorn,ffi,ctypes,dom,repl,domonic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: domonic-libs>=0.0.2
+Provides-Extra: gui
+Requires-Dist: pywebview>=5.0; extra == "gui"
+Dynamic: license-file
+
+# myjs
+
+A JavaScript interpreter for Python. It runs a practical subset of ECMAScript against a server-side DOM, hands scripts an `ffi` bridge to native C libraries, and lets JavaScript reach the entire Python ecosystem.
+
+```bash
+pip install myjs
+```
+
+```bash
+myjs                 # start a REPL
+myjs script.js       # execute a file
+myjs -e "6 * 7"      # evaluate a snippet
+myjs --gui app.js    # run, then show the DOM the script built in a native window
+```
+
+```python
+import myjs
+
+myjs.eval("1 + 2 * 3")            # -> 7
+myjs.run("script.js")
+
+s = myjs.Session()                # an isolated global scope
+s.eval("const x = 21;")
+s.eval("x * 2")                   # -> 42
+```
+
+## What a script can reach
+
+- **The DOM** — `document`, `window`, and ~190 constructors (`URL`, `Headers`, `Event`, `DOMRect`, …). `document.createElement(...).appendChild(...)` builds a real object tree.
+- **An event loop** — `Promise` (with `all` / `allSettled` / `race` / `any`), `async` / `await`, `setTimeout` / `setInterval`, `queueMicrotask`. Microtasks run before timers.
+- **ES modules** — `import` / `export` from `.js` files; a bare specifier resolves to a Python module.
+- **`ffi`** — call native C libraries through `ctypes`, no compiler:
+
+  ```javascript
+  const libc = ffi.loadLibrary("c");
+  libc.abs.argtypes = [ffi.types.int];
+  libc.abs.restype  = ffi.types.int;
+  libc.abs(-42);                       // 42
+  ```
+
+- **Host bindings** — `fs`, `path`, `sh` (shell), `http` + an async `fetch`, `os` (Node-flavoured), `process`, `WebSocket` (a real RFC 6455 client), `say` / `notify` / `open`, `hash`, `atob` / `btoa`.
+- **`py`** — `py.import("numpy")`, `py.eval(...)`, `py.list(iter)` → the whole Python package index from JavaScript.
+
+The language layer passes a curated test262-style battery: closures, classes (extends / super / fields / getters-setters / private / static), destructuring, generators, labelled break, `async` / `await`, and the `Array` / `String` / `Object` / `Number` / `Math` / `JSON` / `RegExp` built-ins. Not covered: real prototype chains, `Proxy` / `Symbol`, `with`.
+
+## Language embedding
+
+```python
+s = myjs.Session(scope={"answer": 42})
+s.eval("answer * 2")              # -> 84
+```
+
+A JavaScript exception that escapes becomes `myjs.JSError` with `js_name`, `js_line`, and `js_trace` (the call stack).
+
+## How it is built
+
+`myjs` is the runtime layer on top of the [`domonic-libs`](https://pypi.org/project/domonic-libs/) `acorn` port — a faithful Python port of the [acorn](https://github.com/acornjs/acorn) parser plus a tree-walking evaluator — which in turn runs on [`domonic`](https://pypi.org/project/domonic/)'s DOM. Full reference: [docs/myjs.md](https://github.com/byteface/domonic-libs/blob/master/docs/myjs.md).
+
+MIT licensed.

myjs-0.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+myjs/__init__.py,sha256=nie5sW_zre7MxT0V3_V4h8ajGsqKQN_abdWlPzjFSfY,1866
+myjs/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+myjs/_engine.py,sha256=HejwkF_qXZFI7TEHr6LxNY9-zTeO-1Ks0y4XDzKEL6A,4032
+myjs/cli.py,sha256=4w9aDliQC9Q2ggBIY9mrEcfMf8RYV9UTzKcF-bpj1V8,2798
+myjs/ffi.py,sha256=k1aO7Ffxci1PSqutWw_tlqC4Xig7QtwOhzUVkjHHX64,7613
+myjs/host.py,sha256=1SnluwQjIzzqMtpRdmcDGD_vyuKckL67eZlN6M2RbQo,18915
+myjs/repl.py,sha256=XELA1ilpPTov4E2pyXgevZvCCCjt_FhQdtpLmbAgMsc,2761
+myjs-0.0.2.dist-info/licenses/LICENSE,sha256=QAxrfKvz2-qZ3wES7ocFTmPJDj74dyL-5uxRjiDhZn4,1065
+myjs-0.0.2.dist-info/METADATA,sha256=r3MvNDFNk3EIqgyd7F7jMv0iCftdn5AA-XxT_CbWm90,4210
+myjs-0.0.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+myjs-0.0.2.dist-info/entry_points.txt,sha256=erJBPK-zEJBVlNW2u_tmAiQJCJHpXVhBDERgnIO4pAM,39
+myjs-0.0.2.dist-info/top_level.txt,sha256=bfUZ6eSxZ2MUr9ybXAUbnPAWL0IGnZkujU5ToVClU3U,5
+myjs-0.0.2.dist-info/RECORD,,

myjs-0.0.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

myjs-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+myjs = myjs.cli:main

myjs-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 byteface
+
+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.

myjs-0.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+myjs