Add Module Loader

src/common/module-loader/README.md

@@ -0,0 +1,42 @@
+<h1 align="center"> Module Loader </h1>
+
+<p align="center">A protocol to load Source Academy modules</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sourceacademy/common-module-loader"><img src="https://img.shields.io/npm/v/@sourceacademy/common-module-loader?color=1a2530&label=npm"></a>
+  <a href="https://github.com/source-academy/plugins/tree/main/src/common/module-loader"><img src="https://img.shields.io/badge/github-repo-blue?logo=github"></a>
+</p>
+
+## Features
+- Protocol for loading Source Academy modules on the runner side, from a changeable module directory on the host side
+
+## Installation
+```bash
+yarn add @sourceacademy/common-module-loader
+# OR
+npm i @sourceacademy/common-module-loader
+# OR
+pnpm add @sourceacademy/common-module-loader
+```
+
+## Structure
+This package ([`@sourceacademy/common-module-loader`](https://github.com/source-academy/plugins/tree/main/src/common/module-loader)) contains the shared constants and types required by both the runner-side and web-side plugin implementations.
+
+These include:
+- The IDs and channel name the two plugins use to find each other (`RUNNER_ID`, `WEB_ID`, `CHANNEL_ID`)
+- The message type (`ModuleLoaderMessage`) sent between the two plugins
+
+## Usage
+Ideally, you should not need to use this package directly. Instead, use the runner-side plugin ([`@sourceacademy/runner-module-loader`](https://github.com/source-academy/plugins/tree/main/src/runner/module-loader)) or the web-side plugin ([`@sourceacademy/web-module-loader`](https://github.com/source-academy/plugins/tree/main/src/web/module-loader)).
+
+However, if you do need to use this package directly, you can import the constants and types as follows:
+
+```ts
+import type { ModuleLoaderMessage } from '@sourceacademy/common-module-loader';
+...
+```
+
+## Further reading
+- To load a module, use [`@sourceacademy/runner-module-loader`](https://github.com/source-academy/plugins/tree/main/src/runner/module-loader)
+- To provide the module directory URL, use [`@sourceacademy/web-module-loader`](https://github.com/source-academy/plugins/tree/main/src/web/module-loader)
+- The [plugins wiki](https://github.com/source-academy/plugins/wiki) covers how Conductor plugins communicate

src/common/module-loader/manifest.json

@@ -0,0 +1,3 @@
+{
+  "type": "installable"
+}

src/common/module-loader/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@sourceacademy/common-module-loader",
+  "version": "0.0.1",
+  "packageManager": "yarn@4.6.0",
+  "description": "The common types for loading modules in Source Academy",
+  "scripts": {
+    "build": "rollup -c",
+    "prepack": "yarn build"
+  },
+  "license": "ISC",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "rollup": "^4.60.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}

src/common/module-loader/rollup.config.mjs

@@ -0,0 +1,21 @@
+import nodeResolve from "@rollup/plugin-node-resolve";
+import terser from "@rollup/plugin-terser";
+import typescript from "@rollup/plugin-typescript";
+
+/**
+ * @type {import('rollup').RollupOptions}
+ */
+export default {
+  input: "src/index.ts",
+  output: [
+    {
+      file: "dist/index.cjs",
+      format: "cjs",
+    },
+    {
+      file: "dist/index.mjs",
+      format: "esm",
+    },
+  ],
+  plugins: [nodeResolve(), typescript(), terser()],
+};

src/common/module-loader/src/index.ts

@@ -0,0 +1,27 @@
+export const WEB_ID = "__web_module_loader";
+export const RUNNER_ID = "__runner_module_loader";
+
+export const CHANNEL_ID = "module_config";
+
+export enum ModuleLoaderMessageType {
+  REQUEST_MODULE = "request_module",
+  MODULE_RESPONSE = "module_response",
+  MODULE_ERROR = "module_error",
+}
+
+export type ModuleLoaderMessage =
+  | {
+      type: ModuleLoaderMessageType.REQUEST_MODULE;
+      moduleName: string;
+    }
+  | {
+      type: ModuleLoaderMessageType.MODULE_RESPONSE;
+      moduleName: string;
+      moduleURL: string;
+      tabs: string[];
+    }
+  | {
+      type: ModuleLoaderMessageType.MODULE_ERROR;
+      moduleName: string;
+      error: string;
+    };

src/common/module-loader/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "exclude": ["./dist"],
+  "include": ["./src"],
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  }
+}

src/runner/module-loader/README.md

@@ -0,0 +1,46 @@
+<h1 align="center">Module Loader</h1>
+
+<p align="center">Runner-side plugin for loading Source Academy modules</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@sourceacademy/runner-module-loader"><img src="https://img.shields.io/npm/v/@sourceacademy/runner-module-loader?color=1a2530&label=npm"></a>
+  <a href="https://github.com/source-academy/plugins/tree/main/src/runner/module-loader"><img src="https://img.shields.io/badge/github-repo-blue?logo=github"></a>
+</p>
+
+## Features
+The plugin provides an interface to load modules with a module ID
+
+## Installation
+```bash
+yarn add @sourceacademy/runner-module-loader
+# OR
+npm i @sourceacademy/runner-module-loader
+# OR
+pnpm add @sourceacademy/runner-module-loader
+```
+
+## Structure
+This package ([`@sourceacademy/runner-module-loader`](https://github.com/source-academy/plugins/tree/main/src/runner/module-loader)) contains the `ModuleLoaderRunnerPlugin` class — a Conductor runner plugin that an evaluator can call to load modules.
+
+### API Reference
+| Name | Description |
+|------|-------------|
+| `instance` | The singleton instance of the plugin. | 
+| `async requestModule(moduleName: string): Promise<IModulePlugin>` | Request a module by name from the host plugin. Rejects with an error if the module is not found. |
+
+## Usage
+After installation, import `ModuleLoaderRunnerPlugin` and register it with the Conductor evaluator. When evaluating `import` statements, call `requestModule` to load the module.
+
+```ts
+...
+const pluginObj = await ModuleLoaderRunnerPlugin.instance.requestModule(moduleName);
+context.nativeStorage.loadedModules[moduleName] = Object.fromEntries(
+    pluginObj?.exports.map(t => [t.symbol, t]) || [],
+);
+...
+```
+
+## Further reading
+- For the shared protocol types and IDs, see [`@sourceacademy/common-module-loader`](https://github.com/source-academy/plugins/tree/main/src/common/module-loader)
+- For the host-side plugin that accepts the module directory URL, see [`@sourceacademy/web-module-loader`](https://github.com/source-academy/plugins/tree/main/src/web/module-loader)
+- The [plugins wiki](https://github.com/source-academy/plugins/wiki) covers how Conductor plugins communicate

src/runner/module-loader/manifest.json

@@ -0,0 +1,3 @@
+{
+  "type": "installable"
+}

src/runner/module-loader/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@sourceacademy/runner-module-loader",
+  "version": "0.0.1",
+  "packageManager": "yarn@4.12.0",
+  "description": "The runner plugin for the module loader in Source Academy",
+  "scripts": {
+    "build": "rollup -c",
+    "prepack": "yarn build"
+  },
+  "license": "ISC",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "@sourceacademy/conductor": ">=0.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@sourceacademy/common-module-loader": "workspace:*",
+    "@sourceacademy/conductor": ">=0.3.0",
+    "@sourceacademy/runner-remote-execution": "workspace:*",
+    "@vitest/coverage-istanbul": "^4.1.9",
+    "rollup": "^4.60.2",
+    "tslib": "^2.8.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}

src/runner/module-loader/rollup.config.mjs

@@ -0,0 +1,19 @@
+import nodeResolve from "@rollup/plugin-node-resolve";
+import terser from "@rollup/plugin-terser";
+import typescript from "@rollup/plugin-typescript";
+
+/** @type {import('rollup').RollupOptions} */
+export default {
+  input: "src/index.ts",
+  output: [
+    {
+      file: "dist/index.cjs",
+      format: "cjs",
+    },
+    {
+      file: "dist/index.mjs",
+      format: "esm",
+    },
+  ],
+  plugins: [nodeResolve(), typescript(), terser()],
+};