Update template package docs

Author: kateinoigakukun

packages/npm-packages/ruby-head-wasm-emscripten/README.md

@@ -0,0 +1,92 @@
+# ruby-head-wasm-emscripten
+
+WebAssembly port of CRuby by Emscripten with a thin JavaScript wrapper.
+
+This package distributes the latest `master` branch of CRuby.
+
+## Installation
+
+For instaling ruby-head-wasm-emscripten, just run this command in your shell:
+
+```console
+$ npm install --save ruby-head-wasm-emscripten
+```
+
+## Quick Start
+
+This quick start is for browsers and Node.js environments. See [the example project](./example) for more details.
+
+```javascript
+import { loadRuby } from "ruby-head-wasm-emscripten";
+
+const main = async () => {
+  const args = ["--disable-gems", "-e", "puts 'Hello :)'"];
+  console.log(`$ ruby.wasm ${args.join(" ")}`);
+
+  const defaultModule = {
+    locateFile: (path) => "./node_modules/ruby-head-wasm-emscripten/dist/" + path,
+    setStatus: (msg) => console.log(msg),
+    print: (line) => console.log(line),
+    arguments: args,
+  };
+
+  await loadRuby(defaultModule);
+};
+
+main();
+
+```
+
+## APIs
+
+`loadRuby(defaultModule): Promise<Module>`
+
+This package provides only `loadRuby` function, which loads the Ruby interpreter and stdlib asynchronously.
+
+This takes a `defaultModule` object as an argument, which is used as a base for the Emscripten's Module object.
+
+### Module object
+
+> Module is a global JavaScript object with attributes that Emscripten-generated code calls at various points in its execution.
+
+https://emscripten.org/docs/api_reference/module.html
+
+This package is a thin wrapper of Emscripten module, so you can control the behavior of the interpreter by modifying the Emscripten's Module object.
+
+
+## Building the package from source
+
+For building the package from source, you need to prepare a Ruby build produced by Emscripten, and you need Emscripten SDK in your PATH.
+
+The instructions for building a Ruby targeting WebAssembly are available at: [TODO](./).
+
+Then, you can run the following command in your shell:
+
+```console
+# Check the directory structure of your Ruby build
+$ tree -L 3 path/to/wasm32-unknown-emscripten-full/
+path/to/wasm32-unknown-emscripten-full/
+├── usr
+│   └── local
+│       ├── bin
+│       ├── include
+│       ├── lib
+│       └── share
+└── var
+    └── lib
+        └── gems
+$ ./build-package.sh path/to/wasm32-unknown-emscripten-full/
+Remember to build the main file with  -s FORCE_FILESYSTEM=1  so that it includes support for loading this file package
+
+index.js → dist...
+created dist in 3.5s
+```
+
+It's recommended to build on a Docker container with the following command:
+
+```console
+$ docker run -it --rm \
+    -v $(pwd):/src \
+    -v path/to/wasm32-unknown-emscripten-full:/install \
+    emscripten/emsdk /bin/bash
+```

packages/npm-packages/ruby-head-wasm-emscripten/README.md

@@ -1,3 +1,275 @@
 # ruby-head-wasm-wasi
 
-See also https://github.com/kateinoigakukun/ruby.wasm/blob/main/packages/npm-packages/ruby-wasm-wasi/README.md
+WebAssembly port of CRuby with WASI.
+
+This package distributes the latest `master` branch of CRuby.
+
+## Installation
+
+For instaling ruby-head-wasm-wasi family, just run this command in your shell:
+
+```console
+$ npm install --save ruby-head-wasm-wasi
+```
+
+## Quick Start (for Node.js)
+
+See [the example project](./example) for more details.
+
+```javascript
+import fs from "fs/promises";
+import { DefaultRubyVM } from "ruby-head-wasm-wasi/dist/node.cjs.js";
+
+const main = async () => {
+  const binary = await fs.readFile(
+    "./node_modules/ruby-head-wasm-wasi/dist/ruby.wasm"
+  );
+  const module = await WebAssembly.compile(binary);
+  const { vm } = await DefaultRubyVM(module);
+
+  vm.eval(`
+    luckiness = ["Lucky", "Unlucky"].sample
+    puts "You are #{luckiness}"
+  `);
+};
+
+main();
+```
+
+Then you can run the example project in your terminal:
+
+```console
+$ node --experimental-wasi-unstable-preview1 index.node.js
+```
+
+## Quick Start (for Browser)
+
+In browser, you need a WASI polyfill
+See [the example project](./example) for more details.
+
+```html
+<html>
+  <script src="https://cdn.jsdelivr.net/npm/ruby-head-wasm-wasi@latest/dist/browser.umd.js"></script>
+  <script>
+    const { DefaultRubyVM } = window["ruby-wasm-wasi"];
+    const main = async () => {
+      // Fetch and instntiate WebAssembly binary
+      const response = await fetch(
+        "https://cdn.jsdelivr.net/npm/ruby-head-wasm-wasi@latest/dist/ruby.wasm"
+      );
+      const buffer = await response.arrayBuffer();
+      const module = await WebAssembly.compile(buffer);
+      const { vm } = await DefaultRubyVM(module);
+
+      vm.printVersion();
+      vm.eval(`
+        require "js"
+        luckiness = ["Lucky", "Unlucky"].sample
+        JS::eval("document.body.innerText = '#{luckiness}'")
+      `);
+    };
+
+    main();
+  </script>
+  <body></body>
+</html>
+```
+
+<!-- The APIs section was generated by `npx documentation readme ./dist/index.esm.js --section=APIs` -->
+
+## APIs
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+#### Table of Contents
+
+- [ruby-head-wasm-wasi](#ruby-head-wasm-wasi)
+  - [Installation](#installation)
+  - [Quick Start (for Node.js)](#quick-start-for-nodejs)
+  - [Quick Start (for Browser)](#quick-start-for-browser)
+  - [APIs](#apis)
+      - [Table of Contents](#table-of-contents)
+    - [RubyVM](#rubyvm)
+      - [Examples](#examples)
+      - [initialize](#initialize)
+        - [Parameters](#parameters)
+      - [setInstance](#setinstance)
+        - [Parameters](#parameters-1)
+      - [addToImports](#addtoimports)
+        - [Parameters](#parameters-2)
+      - [printVersion](#printversion)
+      - [eval](#eval)
+        - [Parameters](#parameters-3)
+        - [Examples](#examples-1)
+    - [RbValue](#rbvalue)
+      - [Parameters](#parameters-4)
+      - [call](#call)
+        - [Parameters](#parameters-5)
+        - [Examples](#examples-2)
+      - [toPrimitive](#toprimitive)
+        - [Parameters](#parameters-6)
+      - [toString](#tostring)
+      - [toJS](#tojs)
+    - [RbError](#rberror)
+      - [Parameters](#parameters-7)
+  - [Building the package from source](#building-the-package-from-source)
+
+### RubyVM
+
+A Ruby VM instance
+
+#### Examples
+
+```javascript
+const wasi = new WASI();
+const vm = new RubyVM();
+const imports = {
+  wasi_snapshot_preview1: wasi.wasiImport,
+};
+
+vm.addToImports(imports);
+
+const instance = await WebAssembly.instantiate(rubyModule, imports);
+await vm.setInstance(instance);
+wasi.initialize(instance);
+```
+
+#### initialize
+
+Initialize the Ruby VM with the given command line arguments
+
+##### Parameters
+
+- `args` The command line arguments to pass to Ruby. Must be
+  an array of strings starting with the Ruby program name. (optional, default `["ruby.wasm","--disable-gems","-e_=0"]`)
+
+#### setInstance
+
+Set a given instance to interact JavaScript and Ruby's
+WebAssembly instance. This method must be called before calling
+Ruby API.
+
+##### Parameters
+
+- `instance` The WebAssembly instance to interact with. Must
+  be instantiated from a Ruby built with JS extension, and built
+  with Reactor ABI instead of command line.
+
+#### addToImports
+
+Add intrinsic import entries, which is necessary to interact JavaScript
+and Ruby's WebAssembly instance.
+
+##### Parameters
+
+- `imports` The import object to add to the WebAssembly instance
+
+#### printVersion
+
+Print the Ruby version to stdout
+
+#### eval
+
+Runs a string of Ruby code from JavaScript
+
+##### Parameters
+
+- `code` The Ruby code to run
+
+##### Examples
+
+```javascript
+vm.eval("puts 'hello world'");
+const result = vm.eval("1 + 2");
+console.log(result.toString()); // 3
+```
+
+Returns **any** the result of the last expression
+
+### RbValue
+
+A RbValue is an object that represents a value in Ruby
+
+#### Parameters
+
+- `inner`
+- `vm`
+- `exporter`
+
+#### call
+
+Call a given method with given arguments
+
+##### Parameters
+
+- `callee` name of the Ruby method to call
+- `args` **...any** arguments to pass to the method. Must be an array of RbValue
+
+##### Examples
+
+```javascript
+const ary = vm.eval("[1, 2, 3]");
+ary.call("push", 4);
+console.log(ary.call("sample").toString());
+```
+
+#### toPrimitive
+
+- **See**: <https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive>
+
+##### Parameters
+
+- `hint`
+
+#### toString
+
+Returns a string representation of the value by calling `to_s`
+
+#### toJS
+
+Returns a JavaScript object representation of the value
+by calling `to_js`.
+
+Returns null if the value is not convertible to a JavaScript object.
+
+### RbError
+
+**Extends Error**
+
+Error class thrown by Ruby execution
+
+#### Parameters
+
+- `message`
+
+## Building the package from source
+
+For building the package from source, you need to prepare a Ruby build produced by WASI SDK, and you need [`wit-bindgen`](https://github.com/bytecodealliance/wit-bindgen) and [`wasm-opt`](https://github.com/webassembly/binaryen#tools) in your PATH.
+
+The instructions for building a Ruby targeting WebAssembly are available at: [TODO](./).
+
+Then, you can run the following command in your shell:
+
+```console
+# Check the directory structure of your Ruby build
+$ tree -L 3 path/to/wasm32-unknown-wasi-full-js/
+path/to/wasm32-unknown-wasi-full-js/
+├── usr
+│   └── local
+│       ├── bin
+│       ├── include
+│       ├── lib
+│       └── share
+└── var
+    └── lib
+        └── gems
+$ ./build-package.sh path/to/wasm32-unknown-wasi-full-js/
+Generating "/Users/katei/.ghq/github.com/kateinoigakukun/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/intrinsics.js"
+Generating "/Users/katei/.ghq/github.com/kateinoigakukun/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-abi-guest.d.ts"
+Generating "/Users/katei/.ghq/github.com/kateinoigakukun/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-abi-guest.js"
+Generating "/Users/katei/.ghq/github.com/kateinoigakukun/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-js-abi-host.d.ts"
+Generating "/Users/katei/.ghq/github.com/kateinoigakukun/ruby.wasm/packages/ruby-head-wasm-wasi/src/bindgen/rb-js-abi-host.js"
+
+src/index.ts → dist/index.umd.js, dist/index.esm.js, dist/index.cjs.js...
+created dist/index.umd.js, dist/index.esm.js, dist/index.cjs.js in 682ms
+```

packages/npm-packages/ruby-head-wasm-wasi/README.md

@@ -1,3 +1,8 @@
-# ruby-head-wasm-emscripten
+# ruby-wasm-emscripten
+
+This package is a template for each channel-specific package.
+
+| Channel | Package |
+| ------- | ------- |
+| `head`  | [`ruby-head-wasm-emscripten`](./../ruby-head-wasm-emscripten) |
 
-See also https://github.com/kateinoigakukun/ruby.wasm/blob/main/packages/npm-packages/ruby-wasm-emscripten/README.md