@tgrv/void-cli 1.0.9 → 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,48 +100,82 @@ function copyFolderRecursive(src, dest, replacements = {}) {
   }
 }
 
-function copyNonSourceFiles(src, dest, buildOutputDir) {
-  ensureDir(dest);
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    
-    // Prevent copying the build output directory into itself
-    if (srcPath === buildOutputDir || srcPath.startsWith(buildOutputDir + path.sep)) {
-      continue;
+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;
     }
-    
-    // Skip standard build/dev folders
-    if (entry.name === "@void" || 
-        entry.name === "@tgrv" || 
-        entry.name === "target" || 
-        entry.name === ".git" || 
-        entry.name === "node_modules") {
-      continue;
+    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 (entry.isDirectory()) {
-      copyNonSourceFiles(srcPath, destPath, buildOutputDir);
-    } else {
-      const ext = path.extname(entry.name).toLowerCase();
-      const filename = entry.name.toLowerCase();
+    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);
       
-      // Exclude Go/Rust/Cargo files and build binaries/configs
-      if (ext === ".go" || 
-          ext === ".rs" || 
-          filename === "cargo.toml" || 
-          filename === "cargo.lock" || 
-          filename === "go.mod" || 
-          filename === "go.sum" || 
-          filename === "void.json" ||
-          filename === "plugin.wasm") {
+      // Prevent copying build output directory or skipped directories
+      if (fullPath === buildOutputDir || fullPath.startsWith(buildOutputDir + path.sep)) {
         continue;
       }
-      
-      fs.copyFileSync(srcPath, destPath);
+      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);
@@ -192,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}`);
@@ -227,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" },
     });
@@ -247,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) {
@@ -258,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 = {
@@ -273,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";
@@ -295,14 +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);
+  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.9",
+  "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"
+  ]
 }