*NIX platform support for WelsonJS (experimental)

[gnh1201]

Summary

WelsonJS uses a syntax model based on ES3 with pseudo-ES5 features provided via core-js polyfills. This approach maintains compatibility with modern JavaScript runtimes while intentionally offering a different execution model.

Support for *NIX platforms is currently in an early exploratory and experimental phase. To evaluate feasibility, we plan to implement a separate, non-production runtime capable of handling this specification.

As an initial proof of concept, limited functionality—such as FSO (Scripting.FileSystemObject)–style APIs—has already been validated. However, this does not imply full feature parity or stability at this stage.

This work should be considered research-oriented, and the final implementation details (or even the choice of engine) may change based on the results of ongoing experiments.

[linear]

CAT-99

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• [Roadmap] WelsonJS on non-Windows OS #160

Related Issues

• [Roadmap] Support for Multiple Built-in ECMAScript Engines in Windows #289
• WinDbg Javascript #332
• Register WelsonJS to Cloud Marketplace (e, g., Microsoft Azure) #158
• [app] Bundler (like a Webpack) with WelsonJS #177
• [Roadmap] SQL query library based on the Windows built-in database system #232

🔗 Related PRs

#348 - Release 0.2.7.56 Ready [merged]

👤 Suggested Assignees

• gnh1201

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Create an experimental, non-production *NIX runtime for WelsonJS using the goja JavaScript engine, implementing platform abstraction layers for core functionality while maintaining ES3/ES5 compatibility through core-js polyfills.

Observations

WelsonJS is a Windows-centric JavaScript runtime built on Windows Script Host (WSH) with extensive COM object usage. The codebase features a custom require() module system, abstracted file operations through lib/file.js (wrapping Scripting.FileSystemObject), and polyfills from core-js for ES5 compatibility. Most examples (8/9) use abstracted libraries (lib/file, lib/http, lib/rand) suggesting portability potential. Windows-specific functionality (registry, WMI, COM automation) is isolated in dedicated libraries that can be excluded from the *NIX runtime.

Assumptions

Assumption 1: Runtime architecture approach

Options Considered:

• Compile all modules into a single Go binary for simplicity
• Load all modules dynamically at runtime from filesystem for flexibility
• Hybrid approach: embed core libraries in binary, load user scripts at runtime

Chosen Option: Hybrid approach: embed core libraries in binary, load user scripts at runtime

Rationale: Core libraries (lib/*) and polyfills are embedded in the Go binary for reliability and consistency, while user scripts and examples are loaded from filesystem at runtime. This matches the existing pattern where core functionality is always available, provides better performance for frequently-used modules, and simplifies distribution of the experimental runtime while maintaining flexibility for user code.

Assumption 2: API compatibility strategy

Options Considered:

• Maintain exact API compatibility by stubbing all Windows-specific calls
• Create entirely new *NIX-specific APIs with different naming
• Provide abstraction layer with platform-specific implementations behind unified API

Chosen Option: Provide abstraction layer with platform-specific implementations behind unified API

Rationale: This approach allows existing scripts to work with minimal changes, acknowledges platform differences through graceful degradation, and aligns with developer expectations that code should "just work" where possible. Platform-specific functionality that cannot be abstracted (registry, WMI) will return clear error messages rather than silently failing.

Assumption 3: Handling Windows-specific libraries

Options Considered:

• Stub all Windows-specific modules to return not-implemented errors
• Exclude them entirely from the *NIX require() search paths
• Create partial *NIX equivalents where conceptually similar (e.g., systemd for winservice)

Chosen Option: Stub all Windows-specific modules to return not-implemented errors

Rationale: When code attempts to load Windows-specific libraries, the require() system should load stub modules that throw descriptive errors explaining the limitation. This provides immediate feedback to developers, maintains API surface consistency, and avoids mysterious "module not found" errors. This aligns with the principle of explicit failures over silent incompatibility.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Experimental Runtime Foundation

Establish the core Go-based runtime infrastructure using goja as the JavaScript engine, implementing the bootstrap sequence and module loading system that mirrors the existing Windows runtime behavior while laying groundwork for platform abstraction.

Task 1: Create Go Runtime Binary

Build the main experimental runtime executable that initializes the goja engine and provides the execution environment for WelsonJS scripts.

• Create new directory welsonjs-unix/ at repository root for experimental runtime code
• Implement main.go that initializes goja runtime, sets up global objects (console, CreateObject replacement), and handles command-line arguments similar to app.js dispatching pattern
• Create runtime/engine.go module to wrap goja VM lifecycle (creation, script loading, error handling)
• Implement polyfill loader that embeds core-js-3.38.0.minified.js content and executes it during engine initialization
• Set up basic console object implementation mapping to Go's log package for console.log/warn/error methods

Task 2: Implement Module Loading System

Create the require() equivalent that loads modules from embedded core libraries and filesystem paths.

• Create runtime/loader.go implementing the module resolution algorithm from app.js (search paths: direct, index.js, node_modules, etc.)
• Implement module caching mechanism equivalent to require._cache to avoid re-evaluation
• Embed core library files (lib/*.js) into Go binary using embed directives
• Create module registry that maps require paths to embedded content or filesystem locations
• Implement extension point system equivalent to require._scriptProviders for future expandability

Task 3: Establish Bootstrap Sequence

Create the initialization flow that mirrors the Windows bootstrap.bat/bootstrap.js pattern but adapted for *NIX environments.

• Create runtime/bootstrap.go handling command-line argument parsing and loader dispatching
• Implement environment variable access for configuration (equivalent to settings.example.ini reading)
• Create graceful shutdown handling (signal handling for SIGINT/SIGTERM)
• Set up error reporting that distinguishes between JavaScript errors and runtime errors
• Implement exit handling that maps WScript.Quit() calls to os.Exit() with appropriate status codes

🤖 Prompt for AI agents

Build the core Go-based runtime infrastructure using goja JavaScript engine that
mirrors WelsonJS Windows runtime behavior.

Create welsonjs-unix/ directory structure at repository root with main.go,
runtime/engine.go, runtime/loader.go, and runtime/bootstrap.go.

In main.go and runtime/engine.go:
- Initialize goja VM with global objects (console mapped to Go log package,
CreateObject replacement)
- Embed and execute core-js-3.38.0.minified.js polyfills during initialization
- Handle command-line arguments similar to app.js dispatching
- Implement error handling and script loading

In runtime/loader.go:
- Implement require() with module resolution algorithm (search paths: direct,
index.js, node_modules)
- Add module caching (require._cache equivalent)
- Embed core libraries (lib/*.js) using Go embed directives
- Create module registry mapping require paths to embedded/filesystem locations
- Add extension points (require._scriptProviders equivalent)

In runtime/bootstrap.go:
- Parse command-line arguments and dispatch to loader
- Access environment variables for configuration
- Handle SIGINT/SIGTERM signals for graceful shutdown
- Distinguish JavaScript errors from runtime errors in reporting
- Map WScript.Quit() to os.Exit() with status codes

Phase 2: Platform Abstraction Layer

Implement the abstraction interfaces that allow core libraries to work across platforms, starting with file system operations (FSO-style API) and essential system utilities.

Task 1: Create Platform Detection System

Establish the mechanism for detecting and routing to platform-specific implementations.

• Create runtime/platform/ package with detector.go that identifies OS (using runtime.GOOS)
• Implement abstraction interface pattern where platform-agnostic API signatures are defined in interfaces
• Create registration system for platform-specific implementations (factory pattern)
• Add platform detection global accessible from JavaScript (equivalent to WScript detection in app.js)
• Document platform capabilities and limitations in structured format for runtime queries

Task 2: Implement FSO-Style File System Abstraction

Create the file system operation layer that provides Scripting.FileSystemObject compatibility using Go's os and io packages.

• Create runtime/platform/fs/ package defining FileSystem interface with methods matching lib/file.js API surface
• Implement Unix-specific file operations in fs/unix.go mapping FSO operations to POSIX calls:
  • fileExists/folderExists using os.Stat
  • readFile/writeFile using os.ReadFile/WriteFile
  • createFolder/deleteFolder using os.MkdirAll/RemoveAll
  • appendFile using os.OpenFile with O_APPEND
  • rotateFile implementing line-based rotation logic
• Create charset/encoding handling for UTF-8 and other encodings (similar to pipe-ipc charset support)
• Expose fs operations to JavaScript through goja bindings in exposed FileSystemObject
• Handle path operations (BuildPath, GetAbsolutePath) using Go's filepath package

Task 3: Create Platform-Agnostic System Utilities

Implement basic system information and shell execution capabilities without Windows-specific dependencies.

• Create runtime/platform/system/ package for cross-platform system operations
• Implement environment variable expansion (equivalent to lib/system.js getEnvString but using os.Getenv)
• Create basic process execution wrapper (equivalent to lib/shell.js but using os/exec package)
• Implement portable system information queries (OS, architecture, hostname) using Go's runtime and os packages
• Create stub implementations for Windows-specific operations (registry, WMI) that return not-implemented errors

🤖 Prompt for AI agents

Implement platform abstraction layer that enables cross-platform core library
functionality with FSO-compatible file system operations and system utilities.

Create runtime/platform/ package with detector.go:
- Detect OS using runtime.GOOS
- Define abstraction interfaces for platform-agnostic API signatures
- Implement factory pattern registration for platform-specific implementations
- Expose platform detection to JavaScript (WScript equivalent)
- Document platform capabilities/limitations

Create runtime/platform/fs/ package:
- Define FileSystem interface matching lib/file.js API
- Implement Unix file operations in fs/unix.go:
  - fileExists/folderExists (os.Stat)
  - readFile/writeFile (os.ReadFile/WriteFile)
  - createFolder/deleteFolder (os.MkdirAll/RemoveAll)
  - appendFile (os.OpenFile with O_APPEND)
  - rotateFile with line-based rotation
- Handle charset/encoding (UTF-8 and others)
- Expose FileSystemObject to JavaScript via goja bindings
- Implement path operations (BuildPath, GetAbsolutePath) using filepath

Create runtime/platform/system/ package:
- Implement environment variable expansion (os.Getenv)
- Create process execution wrapper (os/exec)
- Query system info (OS, architecture, hostname) using runtime and os
- Stub Windows-specific operations (registry, WMI) with not-implemented errors

Phase 3: Core Library Adaptation

Adapt the essential JavaScript libraries to work with the platform abstraction layer, prioritizing cross-platform utilities and those needed by portable examples.

Task 1: Adapt lib/file.js for Platform Abstraction

Modify the file operations library to use the abstraction layer instead of direct FSO calls.

• Refactor lib/file.js to detect execution environment (Windows WSH vs Unix runtime)
• When running in Unix runtime, route calls to exposed FileSystemObject from platform abstraction layer
• Maintain existing Windows behavior when CreateObject("Scripting.FileSystemObject") is available
• Preserve all existing API signatures and behavior for compatibility
• Add runtime checks that provide clear errors for unsupported operations (if any)

Task 2: Integrate Core Cross-Platform Libraries

Bundle the already-portable utility libraries with minimal or no modifications.

• Embed lib/strings.js (fully cross-platform string utilities)
• Embed lib/uri.js (URL/query parsing, no platform dependencies)
• Adapt lib/http.js to use XMLHttpRequest-compatible implementation provided by Go HTTP client bindings
• Verify lib/rand.js works with goja's Math.random or provide Go crypto/rand binding if needed
• Create library manifest documenting which libs are available in Unix runtime vs Windows-only

Task 3: Handle Windows-Specific Library Stubs

Create placeholder modules for Windows-specific libraries that cannot be ported.

• Create stub modules in runtime/stubs/ for: registry.js, wmi.js, winservice.js, winlibs.js, wintap.js, msmq.js, virtualinput.js, vbscript.js, autoit.js, powershell.js
• Each stub exports the same API surface but throws descriptive errors: "NotImplementedError: [module] is Windows-specific and not available on Unix platforms"
• Register stubs in module loader so require() succeeds but usage fails with clear messaging
• Document Windows-specific functionality and potential *NIX alternatives in developer guide

🤖 Prompt for AI agents

Adapt JavaScript core libraries to work with platform abstraction layer,
focusing on cross-platform utilities and portable examples.

Modify lib/file.js:
- Detect execution environment (Windows WSH vs Unix runtime)
- Route to platform abstraction FileSystemObject in Unix runtime
- Maintain Windows CreateObject("Scripting.FileSystemObject") behavior
- Preserve all existing API signatures for compatibility
- Add clear error messages for unsupported operations

Integrate cross-platform libraries:
- Embed lib/strings.js (no modifications needed)
- Embed lib/uri.js (no modifications needed)
- Adapt lib/http.js to use XMLHttpRequest-compatible Go HTTP client bindings
- Verify lib/rand.js works with goja's Math.random or bind Go crypto/rand
- Create library manifest documenting Unix vs Windows-only availability

Create Windows-specific stubs in runtime/stubs/:
- Stub modules: registry.js, wmi.js, winservice.js, winlibs.js, wintap.js,
msmq.js, virtualinput.js, vbscript.js, autoit.js, powershell.js
- Export matching API surfaces that throw "NotImplementedError: [module] is
Windows-specific and not available on Unix platforms"
- Register stubs in module loader (require() succeeds, usage fails with clear
errors)
- Document Windows functionality and potential *NIX alternatives

Phase 4: Validation and Documentation

Test the experimental runtime with portable examples, document capabilities and limitations, and provide guidance for developers working with the cross-platform codebase.

Task 1: Validate Portable Examples

Test examples that were identified as having minimal Windows dependencies to verify runtime functionality.

• Create test harness in welsonjs-unix/test/ that runs examples and captures output
• Test simple examples first: rotate_file.js, census.js (with test data)
• Verify file I/O operations work correctly with FSO-style API
• Test HTTP operations with certchecker.js or virustotal.js (if dependencies available)
• Document any behavioral differences or incompatibilities discovered during testing

Task 2: Create Developer Documentation

Document the experimental runtime capabilities, limitations, and usage patterns for developers.

• Create welsonjs-unix/README.md explaining experimental status, installation, and basic usage
• Document platform abstraction architecture and how to write cross-platform code
• Create compatibility matrix listing which lib/* modules work on Unix vs Windows-only
• Provide migration guide for adapting Windows-specific code to cross-platform patterns
• Document known limitations (goja ES6 limitations, missing COM features, performance characteristics)

Task 3: Establish Testing and Iteration Framework

Set up infrastructure for ongoing validation and improvement of the experimental runtime.

• Create simple test suite in welsonjs-unix/test/ with passing/failing test tracking
• Implement example runner script that executes all portable examples and reports results
• Document process for adding new examples or libraries to the runtime
• Create issue template for reporting Unix-specific bugs or incompatibilities
• Set expectations in documentation that this is experimental and not production-ready

🤖 Prompt for AI agents

Validate the experimental runtime with portable examples and create
comprehensive documentation for developers.

Create test harness in welsonjs-unix/test/:
- Run examples and capture output
- Test rotate_file.js and census.js with test data
- Verify file I/O operations with FSO-style API
- Test HTTP operations (certchecker.js, virustotal.js if available)
- Document behavioral differences and incompatibilities

Create welsonjs-unix/README.md:
- Explain experimental status, installation, and usage
- Document platform abstraction architecture and cross-platform coding practices
- Create compatibility matrix (Unix-available vs Windows-only lib/* modules)
- Provide migration guide for adapting Windows code to cross-platform patterns
- Document limitations (goja ES6, missing COM, performance)

Establish testing framework:
- Create test suite with pass/fail tracking in welsonjs-unix/test/
- Implement example runner script for all portable examples with result
reporting
- Document process for adding examples/libraries
- Create issue template for Unix-specific bugs
- Set clear expectations about experimental, non-production status

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Build the core Go-based runtime infrastructure using goja JavaScript engine that
mirrors WelsonJS Windows runtime behavior.

Create welsonjs-unix/ directory structure at repository root with main.go,
runtime/engine.go, runtime/loader.go, and runtime/bootstrap.go.

In main.go and runtime/engine.go:
- Initialize goja VM with global objects (console mapped to Go log package,
CreateObject replacement)
- Embed and execute core-js-3.38.0.minified.js polyfills during initialization
- Handle command-line arguments similar to app.js dispatching
- Implement error handling and script loading

In runtime/loader.go:
- Implement require() with module resolution algorithm (search paths: direct,
index.js, node_modules)
- Add module caching (require._cache equivalent)
- Embed core libraries (lib/*.js) using Go embed directives
- Create module registry mapping require paths to embedded/filesystem locations
- Add extension points (require._scriptProviders equivalent)

In runtime/bootstrap.go:
- Parse command-line arguments and dispatch to loader
- Access environment variables for configuration
- Handle SIGINT/SIGTERM signals for graceful shutdown
- Distinguish JavaScript errors from runtime errors in reporting
- Map WScript.Quit() to os.Exit() with status codes
===============================================================================

Task: 2

Implement platform abstraction layer that enables cross-platform core library
functionality with FSO-compatible file system operations and system utilities.

Create runtime/platform/ package with detector.go:
- Detect OS using runtime.GOOS
- Define abstraction interfaces for platform-agnostic API signatures
- Implement factory pattern registration for platform-specific implementations
- Expose platform detection to JavaScript (WScript equivalent)
- Document platform capabilities/limitations

Create runtime/platform/fs/ package:
- Define FileSystem interface matching lib/file.js API
- Implement Unix file operations in fs/unix.go:
  - fileExists/folderExists (os.Stat)
  - readFile/writeFile (os.ReadFile/WriteFile)
  - createFolder/deleteFolder (os.MkdirAll/RemoveAll)
  - appendFile (os.OpenFile with O_APPEND)
  - rotateFile with line-based rotation
- Handle charset/encoding (UTF-8 and others)
- Expose FileSystemObject to JavaScript via goja bindings
- Implement path operations (BuildPath, GetAbsolutePath) using filepath

Create runtime/platform/system/ package:
- Implement environment variable expansion (os.Getenv)
- Create process execution wrapper (os/exec)
- Query system info (OS, architecture, hostname) using runtime and os
- Stub Windows-specific operations (registry, WMI) with not-implemented errors
===============================================================================

Task: 3

Adapt JavaScript core libraries to work with platform abstraction layer,
focusing on cross-platform utilities and portable examples.

Modify lib/file.js:
- Detect execution environment (Windows WSH vs Unix runtime)
- Route to platform abstraction FileSystemObject in Unix runtime
- Maintain Windows CreateObject("Scripting.FileSystemObject") behavior
- Preserve all existing API signatures for compatibility
- Add clear error messages for unsupported operations

Integrate cross-platform libraries:
- Embed lib/strings.js (no modifications needed)
- Embed lib/uri.js (no modifications needed)
- Adapt lib/http.js to use XMLHttpRequest-compatible Go HTTP client bindings
- Verify lib/rand.js works with goja's Math.random or bind Go crypto/rand
- Create library manifest documenting Unix vs Windows-only availability

Create Windows-specific stubs in runtime/stubs/:
- Stub modules: registry.js, wmi.js, winservice.js, winlibs.js, wintap.js,
msmq.js, virtualinput.js, vbscript.js, autoit.js, powershell.js
- Export matching API surfaces that throw "NotImplementedError: [module] is
Windows-specific and not available on Unix platforms"
- Register stubs in module loader (require() succeeds, usage fails with clear
errors)
- Document Windows functionality and potential *NIX alternatives
===============================================================================

Task: 4

Validate the experimental runtime with portable examples and create
comprehensive documentation for developers.

Create test harness in welsonjs-unix/test/:
- Run examples and capture output
- Test rotate_file.js and census.js with test data
- Verify file I/O operations with FSO-style API
- Test HTTP operations (certchecker.js, virustotal.js if available)
- Document behavioral differences and incompatibilities

Create welsonjs-unix/README.md:
- Explain experimental status, installation, and usage
- Document platform abstraction architecture and cross-platform coding practices
- Create compatibility matrix (Unix-available vs Windows-only lib/* modules)
- Provide migration guide for adapting Windows code to cross-platform patterns
- Document limitations (goja ES6, missing COM, performance)

Establish testing framework:
- Create test suite with pass/fail tracking in welsonjs-unix/test/
- Implement example runner script for all portable examples with result
reporting
- Document process for adding examples/libraries
- Create issue template for Unix-specific bugs
- Set clear expectations about experimental, non-production status

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[gnh1201]

Checkpoints

• Fully supported FSO (Scripting.FileSystemObject) methods
• Support Enumerator (the non-standard iterator for Windows environment) class

[gnh1201]

I added catswords-jsrt-rs project to WelsonJS open-source ecosystem.

https://github.com/gnh1201/catswords-jsrt-rs