port language directory upgrades to plugin directory

Author: tsammeow

.github/workflows/build-deploy.yml

@@ -0,0 +1,56 @@
+name: Build and deploy directory
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    name: Build directory
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Enable corepack
+        run: corepack enable
+
+      - name: Setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: yarn
+
+      - name: yarn install
+        run: yarn install --immutable
+
+      - name: yarn build
+        run: yarn build
+
+      - name: Upload artifacts
+        id: deployment
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/
+
+  deploy:
+    needs: build
+
+    name: Deploy directory
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -3,22 +3,49 @@
 This repository acts as a directory for Conductor plugins officially supported
 by Source Academy.
 
+## Using this directory
+
+### As a static asset
+
+You may import the `plugins` array directly after installing this repository
+(as `import { plugins } from 'plugin-directory'`). This will cause the array
+to be bundled together at build time.
+
+Caution: when including this repository as a dependency in your `package.json`,
+**be sure to specify a specific commit hash or tag**.
+Failure to do this may cause problems with CI/CD due to lockfile issues when this
+directory is updated.
+
+### Retrieved dynamically
+
+The `plugins` array is available dynamically at
+[`https://source-academy.github.io/plugin-directory/directory.json`](https://source-academy.github.io/plugin-directory/directory.json).
+
+In this case, you probably do not want to bundle the array at build time. You may
+bundle only the utility functions by importing from `'plugin-directory/dist/util'` instead.
+
+You can reconstruct the `pluginMap` using the `generatePluginMap` utility function.
+
 ## Plugin definitions
 
 Plugin definitions should follow the `IPluginDefinition` interface.
 
-Plugins consist of a name, an optional description, and a record mapping
+Plugins consist of an ID, a name, an optional description, and a record mapping
 execution environment to a URL to the plugin's entrypoint file.
 
-## Adding a new Plugin
-
 To add a new plugin to the plugins directory, define your plugin according to
-the interface, and add the definition to the `plugins` array in `src/index.ts`.
-
-Please export your plugin definitions `as const`.
+the interface, and add the definition to the `plugins` array in `src/plugins.ts`.
 
 For plugins meant to use Conductor's Module API, create an entry for
 `PluginType.MODULE`, and do not create one for `PluginType.RUNNER`.
 
 For plugins meant to use the Source Academy Frontend's API, create an entry for
 `PluginType.WEB`.
+
+## Local testing
+
+You may test any changes (e.g. adding your new language) locally by running `yarn start`.
+This starts a development server and compiles the directory in watch mode (recompiling on any changes).
+
+The directory will be available at [`http://localhost:8126/directory.json`](http://localhost:8126/directory.json).
+On the Source Academy frontend, set the feature flag `plugindir.url` to point to this location.

package.json

@@ -1,12 +1,14 @@
 {
   "name": "plugin-directory",
   "packageManager": "[email protected]",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "This repository acts as a directory for Conductor plugins officially supported by Source Academy.",
   "type": "module",
   "main": "dist/index.js",
   "scripts": {
-    "build": "rollup -c",
+    "build": "rollup -c && yarn make-json",
+    "start": "rollup -cw --watch.onEnd='yarn make-json' & http-server ./dist -p8126 -c-1 --cors &",
+    "make-json": "node ./scripts/make-json.js > dist/directory.json",
     "prepack": "yarn build"
   },
   "repository": {
@@ -23,9 +25,9 @@
   },
   "homepage": "https://github.com/source-academy/plugin-directory#readme",
   "devDependencies": {
-    "@rollup/plugin-node-resolve": "^16.0.0",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
+    "http-server": "^14.1.1",
     "rollup": "^4.34.1",
     "tslib": "^2.8.1",
     "typescript": "^5.5.3"

rollup.config.js

@@ -1,10 +1,9 @@
-import nodeResolve from "@rollup/plugin-node-resolve";
 import terser from "@rollup/plugin-terser";
 import typescript from "@rollup/plugin-typescript";
 
-export default [{
-    plugins: [nodeResolve(), typescript()],
-    input: "src/index.ts",
+export default {
+    plugins: [typescript()],
+    input: ["src/index.ts", "src/plugins.ts", "src/util.ts"],
     output: {
         plugins: [terser({
             module: true,
@@ -17,4 +16,4 @@ export default [{
         format: "es",
         sourcemap: true,
     }
-}];
+};

scripts/make-json.js

@@ -0,0 +1,3 @@
+import { plugins } from "../dist/plugins.js";
+
+console.log(JSON.stringify(plugins));

src/index.ts

@@ -1,17 +1,3 @@
-import { soundsPlugin } from "./plugins/sounds";
-import type { IPluginDefinition } from "./types/IPluginDefinition";
-
-function toRecord<const P extends IPluginDefinition[]>(plugins: P) {
-    const pluginRecord: Record<P[number]["name"], IPluginDefinition> = {} as any; // to be populated
-    for (const plugin of plugins) {
-        // @ts-expect-error
-        pluginRecord[plugin.name] = plugin;
-    }
-    return pluginRecord;
-}
-
-export const plugins = /*#__PURE__*/ toRecord([
-    soundsPlugin
-]);
-
-export { PluginType } from "./types";
+export * from "./types";
+export * from "./plugins";
+export * from "./util";

src/plugins.ts

@@ -0,0 +1,13 @@
+import { IPluginDefinition } from "./types";
+import { generatePluginMap } from "./util";
+
+export const plugins: IPluginDefinition[] = [
+];
+
+export const pluginMap: Map<string, IPluginDefinition> = /*#__PURE__*/ generatePluginMap(plugins);
+
+if (plugins.length !== pluginMap.size) {
+    console.warn("Non-unique plugin ID in plugin directory");
+}
+
+export default plugins;

src/plugins/sounds.ts

@@ -1,8 +1,9 @@
 import { IPluginDefinition } from "../types";
 
-export const soundsPlugin = {
-    name: "sounds",
+export const soundsPlugin: IPluginDefinition = {
+    id: "sounds",
+    name: "Sounds",
     resolutions: {
         // TODO: add sounds plugin resolutions
     }
-} as const satisfies IPluginDefinition;
+};

src/types/IPluginDefinition.ts

@@ -1,7 +1,15 @@
 import type { PluginType } from "./PluginType";
 
 export interface IPluginDefinition {
-    name: string;
-    description?: string;
-    resolutions: Partial<Record<PluginType, string>>;
+    /** The plugin's identifier. */
+    readonly id: string;
+
+    /** The name of the plugin. */
+    readonly name: string;
+
+    /** An optional description of the plugin. */
+    readonly description?: string;
+
+    /** The paths to the plugin's script file, by target. */
+    readonly resolutions: Partial<Record<PluginType, string>>;
 }

src/util.ts

@@ -0,0 +1,15 @@
+import { IPluginDefinition } from "./types";
+
+export function generatePluginMap(plugins: IPluginDefinition[]): Map<string, IPluginDefinition> {
+    return new Map(plugins.map(plugin => [plugin.id, plugin]));
+}
+
+/**
+ * Retrieve by ID a definition for a plugin from the directory.
+ * @param pluginMap The plugin map of the directory.
+ * @param pluginId The ID of the plugin to get the definition of.
+ * @returns The retrieved plugin definition, or undefined if not found.
+ */
+export function getPluginDefinition(pluginMap: Map<string, IPluginDefinition>, pluginId: string) {
+    return pluginMap.get(pluginId);
+}