sharjeenux 0.3.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,175 @@
+# Sharjeenux
+
+Sharjeenux is a headless, in-memory Buildroot Linux VM controlled from Node.js.
+It boots an i686 Linux image through v86 and exposes one persistent serial shell
+as an async JavaScript API.
+
+The guest includes:
+
+- Node.js 20.20, npm, npx, TypeScript (`tsc` and `tsserver`)
+- Python 3 and pip
+- OpenJDK 21 (`java`, `javac`) and Apache Maven
+- Git, curl, GNU wget, OpenSSL, and CA certificates
+- Common archive tools: tar, gzip, bzip2, xz, zip, and unzip
+
+It has no desktop, display server, SSH server, or host port-forwarding layer.
+
+## Install
+
+```sh
+npm install sharjeenux
+```
+
+To test the generated package before registry publication:
+
+```sh
+npm install ./sharjeenux-0.3.0.tgz
+```
+
+## Use
+
+```js
+import { initialize, send, exec, shutdown } from "sharjeenux";
+
+await initialize();
+
+console.log(await send("ls -la"));
+console.log(await send("node -e 'console.log(6 * 7)'"));
+console.log(await send("python3 -c 'print(6 * 7)'"));
+console.log(await send("java --version"));
+console.log(await send("git --version"));
+
+const result = await exec("npm --version");
+console.log(result.output, result.exitCode, result.durationMs);
+
+await shutdown();
+```
+
+CommonJS is supported:
+
+```js
+const { initialize, send, shutdown } = require("sharjeenux");
+
+await initialize();
+console.log(await send("uname -a"));
+await shutdown();
+```
+
+Commands execute sequentially in one persistent shell rooted at
+`/mnt/workspace`. Directory changes, environment variables, and installed
+language packages remain available until `shutdown()`.
+
+## Package managers
+
+Use npm/npx for JavaScript and TypeScript, pip for Python, and Maven for Java:
+
+```js
+await send("npm install lodash");
+await send("pip3 install requests");
+await send("mvn --version");
+```
+
+Buildroot images are intentionally assembled at build time and do not have a
+compatible general-purpose remote system package feed. Therefore `apt`, `apk`,
+and `dnf` are not included. Add native Linux packages through the reproducible
+Buildroot configuration and rebuild the image.
+
+Pure JavaScript and pure-Python packages are supported. Packages that must
+compile native C/C++ extensions inside the guest are not guaranteed because
+this image does not ship an on-target C/C++ compiler toolchain. Java source is
+supported through `javac`.
+
+## Long-running commands
+
+`send()` resolves only when a command exits. Use `spawn()` for a development
+server or another long-lived process:
+
+```js
+const vm = await initialize();
+
+await vm.send("npm create vite@latest my-app -- --template react --no-interactive", {
+  onOutput: chunk => process.stdout.write(chunk),
+});
+await vm.send("cd my-app && npm install", {
+  onOutput: chunk => process.stdout.write(chunk),
+});
+
+// `cd my-app` persisted after the previous command.
+const dev = vm.spawn("npm run dev -- --host 0.0.0.0", {
+  timeoutMs: 0,
+  onOutput: chunk => process.stdout.write(chunk),
+});
+
+// The server runs inside the VM. Stop it later:
+dev.kill();
+await dev.exit;
+```
+
+Sharjeenux deliberately does not map guest listening ports to the host. A Vite
+server can run inside Linux, but its URL is not exposed to the host, browser,
+or public network.
+
+## Outbound networking
+
+The default is v86's fetch transport:
+
+```js
+await initialize({ networking: true });
+```
+
+This is outbound-only and optimized for HTTP. npm is configured to use an HTTP
+registry endpoint that the host fetch implementation can retrieve safely.
+Direct guest TCP/TLS connections, including many `https://` Git, pip, Maven,
+curl, and wget requests, require a Wisp relay supplied by the application:
+
+```js
+await initialize({
+  networkRelayUrl: "wisps://your-wisp-relay.example/",
+});
+```
+
+A Wisp relay enables arbitrary outbound TCP; use only a relay you trust. It
+still does not create inbound host-to-guest port forwarding. Set
+`networking: false` to disable the guest network completely.
+
+The fetch transport is much slower and less reliable for large dependency
+graphs than normal TCP. Sharjeenux configures npm retries and conservative
+parallelism, but a trusted Wisp relay is recommended for large installs.
+
+## Sandbox requirements
+
+Sharjeenux works in Node.js sandboxes that permit:
+
+- Node.js 20.6 or newer and WebAssembly execution
+- reading installed package assets and writing the host temporary directory
+- roughly 2 GiB of guest memory plus host/runtime overhead with the default configuration
+- enough execution time to boot a software-emulated x86 Linux VM
+- outbound `fetch` or WebSocket access when networking is enabled
+
+It is not a browser package: its host wrapper imports Node.js APIs. Serverless
+and edge runtimes with short CPU limits, no writable temporary storage, or no
+WebAssembly support are not compatible.
+
+## Performance and Base64 assets
+
+Every embedded binary is stored as Base64 text files of at most 1 KiB each.
+The first initialization must open and decode those files. Decoded images are
+hash-verified and cached under the host temporary directory, so later boots do
+not reopen all chunks.
+
+Sharjeenux emulates a complete 32-bit x86 computer. It will remain materially
+slower than native Node.js or StackBlitz WebContainers, whose architecture is
+designed specifically around browser-native execution. Streaming output with
+`onOutput` makes long installs observable but does not remove emulation cost.
+
+## Licensing and corresponding source
+
+The JavaScript wrapper is MIT-licensed. The Linux image contains components
+under their own licenses, including GPLv2 BusyBox and the Linux kernel. See
+`THIRD_PARTY_NOTICES.md`, `compliance/`, and `SOURCE_OFFER.md`.
+
+The release process produces a matching
+`sharjeenux-corresponding-source-0.3.0.tar.xz` archive. Use it together with
+`compliance/build-definition.tar.xz`, retain both, and honor the written source
+offer for its full stated period. This documentation is an engineering
+compliance aid, not legal advice.

package/SOURCE_OFFER.md

@@ -0,0 +1,22 @@
+# Written offer for corresponding source
+
+Sharjeel Baig offers any third party a complete machine-readable copy of the
+corresponding source code for the GPL- and LGPL-licensed executable components
+distributed in Sharjeenux 0.3.0, including the scripts and configuration used
+to control compilation and installation.
+
+This offer is valid for at least three years after the last distribution of
+this version and, in any event, through July 4, 2029. Electronic delivery is
+available at no charge. Physical delivery, if requested, will cost no more
+than the reasonable cost of the medium and delivery.
+
+To request the source, email `dr.sharjeel.6@gmail.com` with the subject
+`Sharjeenux 0.3.0 corresponding source request`. Include the package version
+and preferred delivery method.
+
+The prepared source materials comprise the corresponding-source archive and
+the exact `compliance/build-definition.tar.xz` shipped in the npm package.
+Together they contain the Buildroot tree, Buildroot and Linux configurations,
+Sharjeenux external tree and root-filesystem overlay, SeaBIOS/SeaVGABIOS source
+and configuration, patches, build scripts, license manifests, and collected
+package sources used for the distributed VM image.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,40 @@
+# Third-party software
+
+Sharjeenux boots third-party software inside an emulated x86 machine. The MIT
+license in `LICENSE` applies only to Sharjeenux's own JavaScript wrapper.
+
+Principal components include:
+
+- v86 0.5.420: BSD-2-Clause, <https://github.com/copy/v86>
+- ws 8.21.0: MIT, <https://github.com/websockets/ws>
+- SeaBIOS/SeaVGABIOS 1.16.2: LGPL-3.0-only,
+  <https://www.seabios.org/>
+- Linux 6.12.94: GPL-2.0-only, <https://kernel.org>
+- Buildroot 2025.02.15: GPL-2.0-or-later, <https://buildroot.org>
+- BusyBox 1.37.0: GPL-2.0-only, <https://busybox.net>
+- GNU C Library 2.41: LGPL-2.1-or-later,
+  <https://www.gnu.org/software/libc/>
+- GCC 13.4 runtime libraries: GPL with the GCC Runtime Library Exception,
+  <https://gcc.gnu.org/onlinedocs/libstdc++/manual/license.html>
+- Node.js 20.20.2 (unofficial Linux x86 build): MIT,
+  <https://github.com/nodejs/node>
+- npm CLI: Artistic-2.0, <https://github.com/npm/cli>
+- TypeScript 6.0.3: Apache-2.0,
+  <https://github.com/microsoft/TypeScript>
+- Python 3.12.13: Python-2.0, <https://www.python.org/>
+- pip: MIT, <https://github.com/pypa/pip>
+- OpenJDK 21.0.11+10: GPL-2.0 with Classpath Exception,
+  <https://github.com/openjdk/jdk21u>
+- Apache Maven 3.9.16: Apache-2.0, <https://maven.apache.org/>
+- Git 2.48.2: GPL-2.0-only, <https://git-scm.com/>
+- curl/libcurl: curl license, <https://curl.se/>
+- GNU Wget 1.25.0: GPL-3.0-or-later,
+  <https://www.gnu.org/software/wget/>
+
+This list is a summary, not a replacement for the complete license manifest
+and license texts produced by Buildroot. See `SOURCE_OFFER.md` for the offer
+that accompanies the binary image. The matching release process also creates
+`sharjeenux-corresponding-source-0.3.0.tar.xz`. Use that archive together
+with `compliance/build-definition.tar.xz` for the collected sources, exact
+patches and configurations, licenses, and Buildroot scripts used for the
+image.

package/compliance/README.md

@@ -0,0 +1,38 @@
+# Release build and compliance material
+
+These files identify and reproduce the Linux image distributed in
+Sharjeenux 0.3.0.
+
+## Binary image
+
+- Embedded `bzImage` SHA-256:
+  `5918718a5e8189b8fe72c26497c441b097c7086c8a27cfcc1f9952c57f09d91e`
+- Buildroot: 2025.02.15
+- Linux: 6.12.94
+- BusyBox: 1.37.0
+- Architecture: i686
+
+`buildroot.config` and `linux.config` are the complete configurations copied
+from the release build output. `build-definition.tar.xz` contains the exact
+Buildroot external tree, patches, root-filesystem overlay, Docker build
+environment, and release scripts used for the final binary. Its SHA-256 is:
+
+`0766caa8161b4a1cfe076ce6b7e429799ee08e51bbb0628aa532f472408caf13`
+
+## Corresponding source
+
+The release process also produced
+`sharjeenux-corresponding-source-0.3.0.tar.xz`. It contains the Buildroot tree,
+Buildroot `legal-info` output and collected package sources, Linux and BusyBox
+source, SeaBIOS/SeaVGABIOS source and configuration, package license files,
+and build material. Its SHA-256 is:
+
+`672c0e25a081b5ffce150909eded53c193ca639b76f5f134490c20f00ae6c94c`
+
+Use that corresponding-source archive together with the exact
+`build-definition.tar.xz` included here. The distributor must retain both and
+honor `SOURCE_OFFER.md` for the stated period.
+
+Buildroot's `legal-info` output is an aid, not an automatic legal conclusion.
+Review the generated manifests and warnings before each release. This folder
+is engineering compliance material, not legal advice.