add readmes and add guardrails to debugging flag

Signed-off-by: karthik2804 <[email protected]>

Author: karthik2804

packages/build-tools/README.md

@@ -0,0 +1,76 @@
+# `@spinframework/build-tools`
+
+This pacakge provides tooling for building wasm components from JavaScript source code. 
+
+## Contents of the package
+
+### Build Tool CLI
+
+The package also provides a node executable `j2w` that enables compiling JS source code to wasm components.  
+
+```bash
+$ npx j2w --help
+Options:
+      --help     Show help                                             [boolean]
+      --version  Show version number                                   [boolean]
+  -i, --input    Path to the input file                               [required]
+  -o, --output   Path to the output file             [default: "component.wasm"]
+      --aot      Enable Ahead of Time compilation                      [boolean]
+  -d, --debug    Enable JavaScript debugging                           [boolean]
+```
+
+**Note:** The input source should be Javascript. 
+
+#### `wit-tools` crate
+
+This crate provides tools for interacting with `wit` files. It is compiled into a wasm component and then consumed from the CLI.
+
+### Webpack Plugin
+
+The webpack plugin can be found at [`./plugins/webpack/index.js`](./plugins/webpack/index.js). It can be used to add externals (modules that will be available at runtime) to the config automatically based on the `wit` imports of the packages being bundled. The plugin needs to be initialized before it can be used. The initialization is `async`, so it has to be awaited. A example usage:
+
+```js
+import SpinSdkPlugin from "@spinframework/build-tools/plugins/webpack/index.js";
+const config = async () => {
+    return {
+        ...
+        plugins: [
+            await SpinSdkPlugin.init()
+        ]
+    }
+}
+
+export default config
+```
+
+## How the Build System Works
+
+The build system works by parsing through the dependencies of a package as defined in the `package.json`. It recursively parses the dependencies to parse out all the package that have a `wit` dependency. The list of `wit` dependencies is then used to create a merged target world which is the union of all the dependencies. 
+
+### Configuring `package.json` for `wit` Dependencies
+
+For packages that leverage `wit` dependencies, they need to configure the `package.json` to include information about the location of the `wit`, the target world and the package name. The configuration needs nested under a `witDependencies` field  be under the `config` field of the `package.json`. An example configuration:
+
+```json
+...
+"config": {
+    "witDependencies": [
+      {
+        "witPath": "./wit",
+        "package": "spinframework:[email protected]",
+        "world": "wasi-cli"
+      }
+    ]
+  }
+...
+```
+
+### Testing the package
+
+The package has some tests for the `wit` dependency parser and can be run using 
+
+```bash
+npm run test
+```
+
+**Note:** Make sure to have a new enough version of `node.js`that can run typescript natively.

packages/build-tools/crates/wit-tools/Cargo.toml

@@ -2,6 +2,7 @@
 name = "wit-tools"
 version.workspace = true
 edition.workspace = true
+description = "package containing build tools to help with managing wit dependencies"
 
 [lib]
 crate-type = ["cdylib"]

packages/build-tools/crates/wit-tools/README.md

@@ -0,0 +1,19 @@
+# `wit-tools`
+
+This crate provides useful functionality for mananging wit dependencies in projects. It currently provides the functionality of:
+- Merging multiple `wit` packages and outputting a combined world.
+- Getting all the imports of a given world. 
+
+This crate can be compiled as a webassembly component and then consumed in language that do not have direct support for `wasm-tools` but has a wasm runtime capable of running components. (e.g) Can be used in Javascript programs using JCO. 
+
+## Developing
+
+The `wit` world that the library implements is defined in the [`wit` directory](./wit).
+
+### Building
+
+The component can be build by running 
+
+```bash
+cargo build --release
+```

packages/build-tools/src/index.ts

@@ -10,7 +10,7 @@ import {
 } from './utils.js';
 import { getCliArgs } from './cli.js';
 import { getBuildDataPath, ShouldComponentize } from './build.js';
-import { readFile, writeFile } from 'node:fs/promises';
+import { writeFile } from 'node:fs/promises';
 import { mergeWit } from '../lib/wit_tools.js';
 
 async function main() {
@@ -32,12 +32,20 @@ async function main() {
 
     // generate wit world string
     let wasiDeps = getPackagesWithWasiDeps(process.cwd(), new Set(), true);
-
     let { witPaths, targetWorlds } = processWasiDeps(wasiDeps);
 
     // Debugging requires some interfaces around reading env vars and making
     // socket connections to be available.
     if (CliArgs.debug) {
+      // check if @spinframework/http-trigger is already in the targetWorlds
+      let httpTrigger = targetWorlds.find(
+        (world) => world.packageName === 'spinframework:[email protected]',
+      );
+      if (!httpTrigger) {
+        throw new Error(
+          'Debugging requires the @spinframework/http-trigger package to be included in the target worlds.',
+        );
+      }
       targetWorlds.push({
         packageName: 'spinframework:[email protected]',
         worldName: 'debugging-support',
@@ -49,7 +57,8 @@ async function main() {
       witPaths,
       targetWorlds,
       'combined',
-      'combined-wit:[email protected]',
+      // Hardcode the version to atleast 0.2.0 to deal with wasm-tools bug with "include" slurping original package when `@since` is present
+      'combined-wit:[email protected]',
     );
 
     const { component } = await componentize({