Scratch package refactor readme

README.md

@@ -21,29 +21,29 @@ This section contains concise explanations on how to accomplish something (often
 Assuming you have...
 - Git installed (if not, jump to: [Git](#Git))
 - **_(Windows only)_** WSL setup (if not, jump to: [Windows Setup](#windows-only))
-- Node <=16 is installed (if not, jump to: [Node](#Node))
-- NPM >= 8.3.0 installed (if not, jump to: [NPM](#NPM))
+- Node is installed (if not, jump to: [Node](#Node))
+- PNPM is installed: [PNPM](#PNPM)
 - VS Code installed with Typescript Extension added (if not, jump to: [Vs Code](#VS-Code-(Recommended)))
 
 Run the following from the command line:
 
 (**NOTE:** If using gitpod, this all will be done for you on startup)
 
 ```shell script
-git clone [email protected]:mitmedialab/prg-extension-boilerplate.git
-# Clone the repository onto your computer. This could take a while (~5m), grab a beverage!
+git clone --recurse-submodules [email protected]:mitmedialab/prg-extension-boilerplate.git
+# Clone the repository (including git submodules: scratch-gui and scratch-vm) onto your computer. This could take a while (~5m), grab a beverage!
 
 cd prg-extension-boilerplate/
 # Change directory (cd) to the repository
 
 git checkout dev 
 
-npm run init
+pnpm install
 # This will symlink the packages together to allow for seamless local development, and installs dependencies for each package. 
 # This should only need to be ran once (unless you checkout a branch that adds new package dependencies).
 # Takes ~1.5 minutes
 
-npm run dev -- --include examples
+pnpm dev -i examples
 # This starts up a development server, serving the two "example" extensions.
 # It takes about ~20s to initially startup and serve everything.
 # Open http://localhost:8601/ in your browser (keep refreshing if nothing's coming up)
@@ -61,8 +61,8 @@ git checkout dev
 git pull # Update branch with any remote changes
 git checkout -b <my branch> # Checkout your 'feature' branch, e.g. git checkout -b new_rad_extension
 
-npm run new:extension <folder to contain extension>
-# For example: npm run new:extension my_awesome_extension
+pnpm new:extension <folder to contain extension>
+# For example: pnpm new:extension my_awesome_extension
 # If succesful, the output of this command will tell you where to find your new extension file.
 # It will be an index.ts file, and its documentation should help you get started
 ```
@@ -72,7 +72,7 @@ npm run new:extension <folder to contain extension>
 If you're a pro extension-maker, use the following command to make a new extension that contains no documentation and/or filler text. 
 
 ```shell script
-npm run new:extension <folder to contain extension> barebones 
+pnpm new:extension <folder to contain extension> barebones 
 # Note the 'barenones' at the end
 ```
 
@@ -84,24 +84,22 @@ After you've [made your extension](#-making-an-extension), run the following com
 cd prg-extension-boilerplate/ # If not already there
 # Change directory (cd) to prg-extension-boilerplate/ 
 
-npm run dev -- --include <folder name of extension(s)>
-# For example: npm run dev -- --include my_awesome_extension
+pnpm dev -i <folder name of extension(s)>
+# For example: pnpm dev -i my_awesome_extension
 # Start a development server to view your extension and reload it as you make changes
 # This command will take ~20s to startup and serve everything to http://localhost:8601/
 
 # Note: you can use the '-i' shorthand instead of writing out '--include'
-npm run dev -- -i <folder name of extension(s)>
+pnpm dev -i <folder name of extension(s)>
 
 # Alternatively, serve all the currently implemented extensions
-npm run dev -- --include all
+pnpm dev -i all
 # NOTE: This will be much more intensive on your computer
 ```
 
-> **_FYI:_** If you're wondering why the extra `--` are necessary in the above commands, it's to ensure that node does not parse the `--include` flag (or any other options following the standalone `--`) as node options, and instead passes those arguments to the appropriate script. [See more.](https://nodejs.org/docs/latest-v8.x/api/cli.html#cli_1)
-
 Then, after navigating to http://localhost:8601/, follow the 'Adding Extensions' guidance in the [official extension documentation](https://en.scratch-wiki.info/wiki/Extension) to add your extension to the workspace. 
 
-As long as the development server is running (meaning the `npm run dev` command is still executing), every change you make to the extension file(s) will trigger the page to refresh and your changes will be reflected automagically 🪄. 
+As long as the development server is running (meaning the `pnpm dev` command is still executing), every change you make to the extension file(s) will trigger the page to refresh and your changes will be reflected automagically 🪄. 
 
 ### 📦 Committing, pushing, and deploying an extension 
 
@@ -217,22 +215,23 @@ Please [install git](https://git-scm.com/downloads), which helps us with [source
 
 Like many web development projects, this project requires [node](https://nodejs.org/en/).
 
-Also, [due to a Webpack 4 issue](https://github.com/webpack/webpack/issues/14532), we require a node version <=16.
-
-Please locate the [latest v16 release](https://nodejs.org/en/blog/release) and install a suitable version for your operating system. If you already have node and need to downgrade to a version <= 16, please see these [instructions for downgrading node](https://www.educative.io/answers/how-to-downgrade-node-version).
+If you don't have Node installed, check out [this page](https://nodejs.org/en/download/package-manager) on how to download it.
 
 #### Maintainer Note (9/15/22)
 
 > In October 2022, node 18 LTS will be released, making it slightly harder to get node 16 LTS. 
 Before then, we either need to upgrade webpack to be able to use node 18, or revise the above instructions to help users locate node 16.
 
-### NPM
+### PNPM
 
-[NPM](https://www.npmjs.com/) (Node Package Manager) is a [package manager](https://en.wikipedia.org/wiki/Package_manager) that is *usually* automatically installed with [Node](#Node). 
+[PNPM](https://pnpm.io/) (Performant Node Package Manager) is a [package manager](https://en.wikipedia.org/wiki/Package_manager) that enhances dependency management for JavaScript projects by storing package files globally and using symbolic links in the `node_modules` folder. This approach reduces disk space usage and maintains the module dependency tree, making it a faster and more space-efficient alternative to traditional package managers like [NPM](https://www.npmjs.com/), [Node](#Node)'s default package manager.
 
-This project requires you to have NPM version ***8.3.0*** or later (in order to leverage [overrides](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides)).
+If you've already installed [Node](#Node), you'll likely have NPM automatically installed. Run the command below to install PNPM using NPM.
+```shell script
+npm install -g pnpm
+```
 
-Please follow [these instructions](https://docs.npmjs.com/try-the-latest-stable-version-of-npm) to check which version of NPM you have and upgrade it if it's older than ***8.3.0***.
+If you don't have NPM, you can [follow these instructions](https://pnpm.io/installation) to install PNPM.
 
 ### VS Code (Recommended)
 

extensions/README.md

@@ -32,7 +32,7 @@ If you want to edit it, please go to [extensions/documentation/src/anatomy/READM
 
 Extensions are defined by all the files that appear in their associated directory, located within `/extensions/src/`.
 
-This directory is created when you run the command `npm run new:extension <extension name>` from the root of the project, where the value you provide for `<extension name>` is used to name this new directory. 
+This directory is created when you run the command `pnpm new:extension <extension name>` from the root of the project, where the value you provide for `<extension name>` is used to name this new directory. 
 
 > **NOTE:** It is important to keep in mind that the name of an extension's associated directory is internally used to identify it, so it is best to avoid changing the directory's name (as this could affect previously saved `.sb3` projects that reference the extension).
 
@@ -58,11 +58,11 @@ export default class ExampleExtension extends extension({ name: "Example" }) {
             - For example, if your extension folder is `myExtension`, you can do the following:
                 ```
                 cd extensions/myExtension # only do this once
-                npm run dev 
+                pnpm dev 
                 ```
              - Instead of running the following from the root of the project every time:
                 ```
-                npm run dev -- --include myExtension
+                pnpm dev -i myExtension
                 ```
             - Inspect the `package.json` file to see all augmented scripts.
 
@@ -614,8 +614,8 @@ Please first make sure you've satisfied [Svelte Dependency](https://github.com/m
 To generate a new svelte file, run the following command from the root of the project:
 
 ```bash
-npm run add:ui <extension folder>
-# For example: npm run add:ui myExtension
+pnpm add:ui <extension folder>
+# For example: pnpm add:ui myExtension
 ```
 
 If succesful, the above command will point you to a generated file with the `.svelte` file-extension that lives inside of your extension's directory.
@@ -707,7 +707,7 @@ Here's how:
 2. Create your "new" framework-based extension using the command outlined in [Making an Extension](https://github.com/mitmedialab/prg-extension-boilerplate/tree/main#-making-an-extension) and use the ***Extension ID*** you found in step 1 as the value of `<folder to contain extension>`
     - For example, if your "old" extension's ***Extension ID*** is `prgRocks` you'll run the following command:
     ```bash
-    npm run new:extension prgRocks
+    pnpm new:extension prgRocks
     ``` 
     - The reason this is necessary is two-fold: First, in the new extension framework, the name of the folder that contains an extension is automatically used as its ***Extension ID***. Second, because already saved `.sb3` / Scratch projects that use your extension refernce the specific ***Extension ID***, we need to make sure our updated, typescript-based extension has the same ID.
 3. Once you have created an extension with a folder name matching the ***Extension ID*** found in step 1, you can actually delete the corresponding entry inside of the `builtinExtensions` object of [scratch-packages/scratch-vm/src/extension-support/extension-manager.js](https://github.com/mitmedialab/prg-extension-boilerplate/blob/main/scratch-packages/scratch-vm/src/extension-support/extension-manager.js)
@@ -720,7 +720,7 @@ Here's how:
     - You can do this as the extension framework will automatically handle adding your extension (and its Extension Menu Display Details) to the [Extension Menu](https://en.scratch-wiki.info/wiki/Extension#Adding_Extensions)
 6. Now you can start coding! See the below comparison of a vanilla JS extension class and a typescript / framework based one.
     - NOTE: If there's a chance anyone has saved projects with the extension you're porting over, you need to make sure to follow the [Legacy Support](#legacy-support) instructions so those saved projects will continue to load correctly.
-7. Once you have migrated all of the "old" ***Impementation*** to your new extension folder & typescript code, you can go ahead and delete the ***Implementation*** folder inside of [pacakges/scratch-vm/src/extensions/](https://github.com/mitmedialab/prg-extension-boilerplate/tree/main/scratch-packages/scratch-vm/src/extensions).
+7. Once you have migrated all of the "old" ***Impementation*** to your new extension folder & typescript code, you can go ahead and delete the ***Implementation*** folder inside of [scratch-packages/scratch-vm/src/extensions/](https://github.com/mitmedialab/prg-extension-boilerplate/tree/main/scratch-packages/scratch-vm/src/extensions).
 8. Now, there should be no remnants of the "old" extension inside of either [scratch-packages/scratch-vm](https://github.com/mitmedialab/prg-extension-boilerplate/tree/main/scratch-packages/scratch-vm) or [scratch-packages/scratch-gui](https://github.com/mitmedialab/prg-extension-boilerplate/tree/main/scratch-packages/scratch-gui) folders, and instead everything lives neatly inside its own directory within [extensions/src](https://github.com/mitmedialab/prg-extension-boilerplate/tree/dev/extensions/src)
 9. Test out the project you saved in step 0 to verify that your port worked as expected.
 
@@ -1279,8 +1279,8 @@ For a quick breakdown of how we handle UI generally in the Extension Framework,
 Then run the following command:
 
 ```bash
-npm run add:arg <extension directory>
-# For example: npm run add:arg myExtension
+pnpm add:arg <extension directory>
+# For example: pnpm add:arg myExtension
 ```
 
 This will create a new `.svelte` file for you within your extension's directory pre-configured to handle custom arguments. However, there's still some more you need to do before you can visualize and modify custom arguments.
@@ -1561,7 +1561,7 @@ sequenceDiagram
     participant B as /scratch-packages/scratch-gui/
     participant C as /scratch-packages/scratch-vm/
     Note over root,C: INITIALIZATION
-    C-->>B: Lerna utility forces scratch-gui <br>to use /scratch-packages/scratch-vm for its dependency <br>instead of using the external npm package
+    C-->>B: PNPM tells scratch-gui <br>to use /scratch-packages/scratch-vm for its dependency <br>instead of using the external npm package
     Note over root,C: BUILD
     Note over root: /scripts/build.ts
     activate root

extensions/src/.templates/package.json

@@ -5,10 +5,10 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo replace-with-directory-name",
-    "test": "npm run test --prefix ../../ -- replace-with-directory-name/index.test.ts",
-    "dev": "npm run dev --prefix ../../../ -- --include replace-with-directory-name",
-    "add:ui": "npm run add:ui --prefix ../../../  -- replace-with-directory-name",
-    "add:arg": "npm run --prefix ../../../-- replace-with-directory-name"
+    "test": "pnpm --filter prg-extension-root test replace-with-directory-name/index.test.ts",
+    "dev": "pnpm --filter prg-extension-root dev --include replace-with-directory-name",
+    "add:ui": "pnpm --filter prg-extension-root add:ui replace-with-directory-name",
+    "add:arg": "pnpm --filter prg-extension-root add:arg replace-with-directory-name"
   },
   "author": "",
   "license": "ISC"

extensions/src/appinventor_example/package.json

@@ -5,10 +5,10 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo appinventor_example",
-    "test": "npm run test --prefix ../../ -- appinventor_example/index.test.ts",
-    "dev": "npm run dev --prefix ../../../ -- --include appinventor_example",
-    "add:ui": "npm run add:ui --prefix ../../../  -- appinventor_example",
-    "add:arg": "npm run --prefix ../../../-- appinventor_example"
+    "test": "pnpm --filter prg-extension-root test appinventor_example/index.test.ts",
+    "dev": "pnpm --filter extensions-root dev --include appinventor_example",
+    "add:ui": "pnpm --filter prg-extension-root add:ui appinventor_example",
+    "add:arg": "pnpm --filter prg-extension-root add:arg appinventor_example"
   },
   "author": "",
   "license": "ISC"

extensions/src/bundle_test/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "bundle_test-extension",
+  "version": "1.0.0",
+  "description": "An extension created using the PRG AI Blocks framework",
+  "main": "index.ts",
+  "scripts": {
+    "directory": "echo bundle_test",
+    "test": "pnpm --filter prg-extension-root test bundle_test/index.test.ts",
+    "dev": "pnpm --filter prg-extension-root dev --include bundle_test",
+    "add:ui": "pnpm --filter prg-extension-root add:ui bundle_test",
+    "add:arg": "pnpm --filter prg-extension-root add:arg bundle_test"
+  },
+  "author": "",
+  "license": "ISC"
+}

extensions/src/complex_example/package.json

@@ -5,8 +5,8 @@
   "main": "index.ts",
   "scripts": {
     "dir:name": "complex_example",
-    "dev": "npm run dev --prefix ../../../ -- --include complex_example",
-    "test": "npm run test --prefix ../../ -- complex_example/index.test.ts"
+    "dev": "pnpm --filter prg-extension-root dev --include complex_example",
+    "test": "pnpm --filter prg-extension-root test complex_example/index.test.ts"
   },
   "author": "",
   "license": "ISC"

extensions/src/extensionProbe/package.json

@@ -4,7 +4,7 @@
   "description": "",
   "main": "index.ts",
   "scripts": {
-    "dev": "npm run dev --prefix ../../../ -- --include extensionProbe"
+    "dev": "pnpm --filter prg-extension-root dev --include extensionProbe"
   },
   "author": "",
   "license": "ISC",

extensions/src/objectDetection/package.json

@@ -5,10 +5,10 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo objectDetection",
-    "test": "npm run test --prefix ../../ -- objectDetection/index.test.ts",
-    "dev": "npm run dev --prefix ../../../ -- --include objectDetection",
-    "add:ui": "npm run add:ui --prefix ../../../  -- objectDetection",
-    "add:arg": "npm run --prefix ../../../-- objectDetection"
+    "test": "pnpm --filter prg-extension-root test objectDetection/index.test.ts",
+    "dev": "pnpm --filter prg-extension-root dev --include objectDetection",
+    "add:ui": "pnpm --filter prg-extension-root add:ui objectDetection",
+    "add:arg": "pnpm --filter prg-extension-root add:arg objectDetection"
   },
   "author": "",
   "license": "ISC",

extensions/src/onnxTest/package.json

@@ -5,8 +5,8 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo onnxTest",
-    "dev": "npm run dev --prefix ../../../ -- --include onnxTest",
-    "test": "npm run test --prefix ../../ -- onnxTest/index.test.ts"
+    "dev": "pnpm --filter prg-extension-root dev --include onnxTest",
+    "test": "pnpm --filter prg-extension-root test onnxTest/index.test.ts"
   },
   "author": "",
   "license": "ISC",

extensions/src/poseBody/package.json

@@ -5,8 +5,8 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo poseBody",
-    "dev": "npm run dev --prefix ../../../ -- --include poseBody",
-    "test": "npm run test --prefix ../../ -- poseBody/index.test.ts"
+    "dev": "pnpm --filter prg-extension-root dev --include poseBody",
+    "test": "pnpm --filter prg-extension-root test poseBody/index.test.ts"
   },
   "author": "",
   "license": "ISC",

extensions/src/poseFace/package.json

@@ -5,8 +5,8 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo poseFace",
-    "test": "npm run test --prefix ../../ -- poseFace/index.test.ts",
-    "dev": "npm run dev --prefix ../../../ -- --include poseFace"
+    "test": "pnpm --filter prg-extension-root test poseFace/index.test.ts",
+    "dev": "pnpm --filter prg-extension-root dev --include poseFace"
   },
   "author": "",
   "license": "ISC"

extensions/src/poseHand/package.json

@@ -5,8 +5,8 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo poseHand",
-    "dev": "npm run dev --prefix ../../../ -- --include poseHand",
-    "test": "npm run test --prefix ../../ -- poseHand/index.test.ts"
+    "dev": "pnpm --filter prg-extension-root dev --include poseHand",
+    "test": "pnpm --filter prg-extension-root test poseHand/index.test.ts"
   },
   "author": "",
   "license": "ISC",

extensions/src/projectProbe/package.json

@@ -5,10 +5,10 @@
   "main": "index.ts",
   "scripts": {
     "directory": "echo projectProbe",
-    "test": "npm run test --prefix ../../ -- projectProbe/index.test.ts",
-    "dev": "npm run dev --prefix ../../../ -- --include projectProbe",
-    "add:ui": "npm run add:ui --prefix ../../../  -- projectProbe",
-    "add:arg": "npm run add:arg --prefix ../../../-- projectProbe"
+    "test": "pnpm --filter prg-extension-root test projectProbe/index.test.ts",
+    "dev": "pnpm --filter prg-extension-root dev --include projectProbe",
+    "add:ui": "pnpm --filter prg-extension-root add:ui projectProbe",
+    "add:arg": "pnpm --filter prg-extension-root add:arg projectProbe"
   },
   "author": "",
   "license": "ISC",