@tgrv/void-cli 1.0.8 → 1.1.0

package/README.md

@@ -14,33 +14,37 @@ npm install -g @tgrv/void-cli
 
 ### 1. Initialize a new application project
 ```bash
-void init [path]
+void init [app-path]
 ```
-Creates standard configuration templates and installs the `@tgrv/void-runtime` engine automatically.
+Creates standard configuration templates and installs the `@tgrv/void-runtime` engine automatically. Defaults to the current folder (`.`).
 
 ### 2. Create a new Rust or Go plugin project
 ```bash
 void create [plugin-path]
 ```
-Prompts for language configuration and instantiates starting templates with pre-configured SDK targets.
+Prompts for language configuration and instantiates starting templates with pre-configured SDK targets. Defaults to the current folder (`.`).
 
 ### 3. Build a plugin locally
 ```bash
 void build [plugin-path]
 ```
-Compiles source files (Cargo/Go) and wraps the WASM binary under a local scoped output folder configured in `void.json`. Defaults to current folder (`.`).
+Compiles source files (Cargo/Go) and wraps the WebAssembly binary and configured assets under the build directory configured in `void.json`. Run from a plugin root folder (defaults to current folder `.`).
 
 ### 4. Publish a plugin
 ```bash
 void publish [plugin-path]
 ```
-Compiles and triggers `npm publish` natively from inside the scoped build directory. Defaults to current folder (`.`).
+Compiles the plugin and runs `npm publish` natively from inside the built directory. Run from a plugin root folder (defaults to current folder `.`).
 
 ### 5. Install / Add a plugin
 ```bash
-void add <plugin-name>
+void add <plugin-name-or-build-path>
 ```
-Downloads the plugin from the NPM registry, or links local build outputs during development, adding dependencies to `void.config.json` and `package.json`.
+Installs a plugin into the application:
+- **Registry:** `void add <plugin-name>` downloads the plugin from the NPM registry.
+- **Local Development / Testing:** `void add <build-folder-path>` (e.g. `void add ../plugins/math/@void/void-math`) copies the compiled local build output directory directly.
+
+Adds the plugin dependency automatically to `void.config.json` and `package.json`.
 
 ### 6. Remove a plugin
 ```bash

package/bin/void.js

@@ -100,6 +100,84 @@ function copyFolderRecursive(src, dest, replacements = {}) {
   }
 }
 
+function copyNonSourceFiles(src, dest, buildOutputDir, filesConfig, wasmFilename) {
+  if (!filesConfig || !Array.isArray(filesConfig) || filesConfig.length === 0) {
+    return;
+  }
+
+  function matchGlob(filePath, pattern) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const normalizedPattern = pattern.replace(/\\/g, "/");
+
+    if (normalizedPath === normalizedPattern) {
+      return true;
+    }
+    const prefix = normalizedPattern.endsWith('/') ? normalizedPattern : normalizedPattern + '/';
+    if (normalizedPath.startsWith(prefix)) {
+      return true;
+    }
+
+    const globToRegex = (glob) => {
+      return '^' + glob
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*\*/g, '___DOUBLE_STAR___')
+        .replace(/\*/g, '___SINGLE_STAR___')
+        .replace(/\?/g, '___QUESTION___')
+        .replace(/___DOUBLE_STAR___/g, '.*')
+        .replace(/___SINGLE_STAR___/g, '[^/]*')
+        .replace(/___QUESTION___/g, '.') + '$';
+    };
+
+    const regex = new RegExp(globToRegex(normalizedPattern));
+    
+    if (!normalizedPattern.includes('/')) {
+      const baseName = path.basename(normalizedPath);
+      if (regex.test(baseName)) {
+        return true;
+      }
+    }
+
+    return regex.test(normalizedPath);
+  }
+
+  function traverse(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      
+      // Prevent copying build output directory or skipped directories
+      if (fullPath === buildOutputDir || fullPath.startsWith(buildOutputDir + path.sep)) {
+        continue;
+      }
+      if (entry.name === "@void" || 
+          entry.name === "@tgrv" || 
+          entry.name === "target" || 
+          entry.name === ".git" || 
+          entry.name === "node_modules" ||
+          entry.name === "void.json" ||
+          (wasmFilename && entry.name === wasmFilename)) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        traverse(fullPath);
+      } else {
+        const relativePath = path.relative(src, fullPath);
+        
+        // Check if relativePath matches any glob in filesConfig
+        const matches = filesConfig.some(pattern => matchGlob(relativePath, pattern));
+        if (matches) {
+          const destPath = path.join(dest, relativePath);
+          ensureDir(path.dirname(destPath));
+          fs.copyFileSync(fullPath, destPath);
+        }
+      }
+    }
+  }
+
+  traverse(src);
+}
+
 const args = process.argv.slice(2);
 const command = args[0];
 
@@ -148,10 +226,20 @@ function runBuild(pluginPathArg) {
     process.exit(1);
   }
 
+  if (manifest.types) {
+    const typesPath = path.resolve(absolutePluginDir, manifest.types);
+    if (!fs.existsSync(typesPath) || !fs.statSync(typesPath).isFile()) {
+      console.error(`${cross} ${colors.red}Error: Types file '${manifest.types}' specified in void.json does not exist.${colors.reset}`);
+      process.exit(1);
+    }
+  }
+
   const pluginName = manifest.name;
   const pluginType = manifest.type;
   const buildDir = manifest.buildDir;
   const buildOutputDir = path.join(absolutePluginDir, buildDir);
+  const exportName = manifest.export || "plugin";
+  const wasmFilename = `${exportName}.wasm`;
 
   if (pluginType === "sdk") {
     console.log(`\n${info} Packaging SDK '${colors.bold}${pluginName}${colors.reset}' to local build at: ${colors.bold}${buildOutputDir}${colors.reset}`);
@@ -183,9 +271,9 @@ function runBuild(pluginPathArg) {
   }
   // Go plugin compilation
   else if (pluginType === "go") {
-    const outputWasm = path.join(absolutePluginDir, "plugin.wasm");
-    console.log(`${info} Running: ${colors.blue}go build -o plugin.wasm${colors.reset}`);
-    const compileSuccess = runCommand("go build -o plugin.wasm", {
+    const outputWasm = path.join(absolutePluginDir, wasmFilename);
+    console.log(`${info} Running: ${colors.blue}go build -o ${wasmFilename}${colors.reset}`);
+    const compileSuccess = runCommand(`go build -o ${wasmFilename}`, {
       cwd: absolutePluginDir,
       env: { ...process.env, GOOS: "wasip1", GOARCH: "wasm" },
     });
@@ -203,7 +291,7 @@ function runBuild(pluginPathArg) {
   ensureDir(buildOutputDir);
 
   // Copy WASM
-  fs.copyFileSync(builtWasmPath, path.join(buildOutputDir, "plugin.wasm"));
+  fs.copyFileSync(builtWasmPath, path.join(buildOutputDir, wasmFilename));
 
   // Clean up temporary compiled WASM
   if (path.dirname(builtWasmPath) === absolutePluginDir) {
@@ -214,7 +302,7 @@ function runBuild(pluginPathArg) {
     }
   }
 
-  // Write package.json if it does not already exist, or check version if it does
+  // Write package.json if it does not already exist, or check version/types if it does
   const packageJsonPath = path.join(buildOutputDir, "package.json");
   if (!fs.existsSync(packageJsonPath)) {
     const pkgJson = {
@@ -229,20 +317,39 @@ function runBuild(pluginPathArg) {
         access: "public"
       }
     };
+    if (manifest.types) {
+      pkgJson.types = manifest.types;
+    }
     fs.writeFileSync(packageJsonPath, JSON.stringify(pkgJson, null, 2));
   } else {
     try {
       const existingPkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+      let changed = false;
       if (existingPkg.version !== manifest.version) {
         console.log(`${info} Version mismatch detected in ${packageJsonPath}. Updating from ${existingPkg.version} to ${manifest.version} to match void.json.`);
         existingPkg.version = manifest.version || "1.0.0";
+        changed = true;
+      }
+      if (manifest.types && existingPkg.types !== manifest.types) {
+        existingPkg.types = manifest.types;
+        changed = true;
+      }
+      if (changed) {
         fs.writeFileSync(packageJsonPath, JSON.stringify(existingPkg, null, 2));
       }
     } catch (err) {
-      console.warn(`${warning} Failed to check/update existing package.json version: ${err.message}`);
+      console.warn(`${warning} Failed to check/update existing package.json version/types: ${err.message}`);
     }
   }
 
+  // Copy types file if specified
+  if (manifest.types) {
+    const typesPath = path.resolve(absolutePluginDir, manifest.types);
+    const destTypesPath = path.join(buildOutputDir, manifest.types);
+    ensureDir(path.dirname(destTypesPath));
+    fs.copyFileSync(typesPath, destTypesPath);
+  }
+
   // Generate standard ESM index.js loader
   const indexJsContent = `import { runtime } from "@tgrv/void-runtime";
 import { fileURLToPath } from "url";
@@ -251,13 +358,14 @@ import { dirname, join } from "path";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const plugin = await runtime.load(
-  join(__dirname, "plugin.wasm")
+const ${exportName} = await runtime.load(
+  join(__dirname, "${wasmFilename}")
 );
 
-export default plugin;
+export default ${exportName};
 `;
   fs.writeFileSync(path.join(buildOutputDir, "index.js"), indexJsContent);
+  copyNonSourceFiles(absolutePluginDir, buildOutputDir, buildOutputDir, manifest.files, wasmFilename);
   console.log(`${tick} ${colors.green}Successfully completed compilation & packaging!${colors.reset}`);
   return buildOutputDir;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tgrv/void-cli",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "type": "module",
   "bin": {
     "void": "./bin/void.js"

package/templates/go/README.md

@@ -0,0 +1,52 @@
+# Void Go Plugin Template
+
+A template for building WebAssembly (WASM) plugins for the **Void** framework using Go.
+
+## 🚀 Getting Started
+
+### 1. Where to Start
+Write your plugin logic inside [main.go](file:///main.go). Exported functions must match the signature:
+```go
+func MyFunction(args map[string]json.RawMessage) (any, error)
+```
+And register them in `main()` using the Void SDK:
+```go
+func main() {
+    void.Register("my_function", MyFunction)
+}
+```
+
+### 2. Build the Plugin
+Compile your plugin by running the build command in this directory:
+```bash
+npx void build
+```
+This compiles the Go code into a WebAssembly binary (`.wasm`) and packages it inside the build output directory configured in `void.json`.
+
+### 3. Test/Install Locally
+To test the built plugin in a local Void application:
+1. Initialize your application project: `npx void init`
+2. Add your compiled local plugin build output folder path:
+   ```bash
+   npx void add ./path/to/plugin/@void/<plugin-name>
+   ```
+
+### 4. Publish
+To build and publish the plugin to the npm registry:
+```bash
+npx void publish
+```
+
+---
+
+## ⚙️ Configuration (`void.json`)
+
+Your plugin configuration is defined in `void.json`. Here are the available fields:
+
+- **`name`**: The package name of your plugin (e.g. `@void/my-plugin`).
+- **`version`**: The current semantic version of the plugin.
+- **`type`**: The compilation target language. Set to `"go"`.
+- **`buildDir`**: The target directory where compilation and wrapping assets are generated (e.g. `@void/my-plugin`).
+- **`types`**: Path to the TypeScript declaration file (e.g. `"types.d.ts"`). During the build process, the CLI validates its existence, copies it to the build output, and automatically sets the `"types"` entry in `package.json` for autocomplete and editor support.
+- **`export`**: The name of the JavaScript variable used to load the WASM binary, which is also the default export name (e.g. `"myPlugin"`).
+- **`files`**: An array of glob patterns of non-source files (such as `*.md` or `*.d.ts`) to copy from the plugin root into the build output folder.

package/templates/go/void.json

@@ -1,6 +1,11 @@
 {
-  "name": "@void/{{name}}",
+  "name": "{{name}}",
   "version": "1.0.0",
   "type": "go",
-  "buildDir": "@void/{{name}}"
+  "buildDir": "@void/{{name}}",
+  "export": "{{name}}",
+  "files": [
+    "*.d.ts",
+    "*.md"
+  ]
 }

package/templates/rust/README.md

@@ -0,0 +1,44 @@
+# Void Rust Plugin Template
+
+A template for building WebAssembly (WASM) plugins for the **Void** framework using Rust.
+
+## 🚀 Getting Started
+
+### 1. Where to Start
+Write your plugin logic inside [src/lib.rs](file:///src/lib.rs). Functions must be annotated with the Void SDK macro and registered:
+Refer to the Void Rust SDK documentation for macro registry instructions.
+
+### 2. Build the Plugin
+Compile your plugin by running the build command in this directory:
+```bash
+npx void build
+```
+This compiles the Rust source code into a WebAssembly binary (`.wasm`) using `cargo build --target wasm32-unknown-unknown --release` and packages it under the build directory configured in `void.json`.
+
+### 3. Test/Install Locally
+To test the built plugin in a local Void application:
+1. Initialize your application project: `npx void init`
+2. Add your compiled local plugin build output folder path:
+   ```bash
+   npx void add ./path/to/plugin/@void/<plugin-name>
+   ```
+
+### 4. Publish
+To build and publish the plugin to the npm registry:
+```bash
+npx void publish
+```
+
+---
+
+## ⚙️ Configuration (`void.json`)
+
+Your plugin configuration is defined in `void.json`. Here are the available fields:
+
+- **`name`**: The package name of your plugin (e.g. `@void/my-plugin`).
+- **`version`**: The current semantic version of the plugin.
+- **`type`**: The compilation target language. Set to `"rust"`.
+- **`buildDir`**: The target directory where compilation and wrapping assets are generated (e.g. `@void/my-plugin`).
+- **`types`**: Path to the TypeScript declaration file (e.g. `"types.d.ts"`). During the build process, the CLI validates its existence, copies it to the build output, and automatically sets the `"types"` entry in `package.json` for autocomplete and editor support.
+- **`export`**: The name of the JavaScript variable used to load the WASM binary, which is also the default export name (e.g. `"myPlugin"`).
+- **`files`**: An array of glob patterns of non-source files (such as `*.md` or `*.d.ts`) to copy from the plugin root into the build output folder.

package/templates/rust/void.json

@@ -1,6 +1,11 @@
 {
-  "name": "@void/{{name}}",
+  "name": "{{name}}",
   "version": "1.0.0",
   "type": "rust",
-  "buildDir": "@void/{{name}}"
+  "buildDir": "@void/{{name}}",
+  "export": "{{name}}",
+  "files": [
+    "*.d.ts",
+    "*.md"
+  ]
 }