refactor: eliminate system strategy from all toolchains for hermetic builds

- Remove system strategy support from 7 toolchains (wasm, jco, wkg, wasmtime, etc)
- Update all toolchain defaults from system to hermetic alternatives (hybrid, download, npm)
- Remove system tool detection and PATH-based discovery logic
- Update toolchain validation to exclude system from supported strategies
- Modernize tools-builder workspace with cargo genrule approach
- Update documentation to reflect hermetic-only build requirements

This ensures complete build hermeticity by eliminating non-reproducible
system tool dependencies across the entire toolchain ecosystem.

Author: avrabe

TOOL_BUILDER_SOLUTION.md

@@ -13,9 +13,9 @@ The main issue was **cargo filesystem sandbox restrictions** in Bazel Central Re
 
 ### Dual-Track Approach
 
-1. **Immediate Solution: Hermetic Pre-built Binaries**
-   - ✅ Added wac and wkg to `toolchains/hermetic_extension.bzl`
-   - ✅ Using `http_file` for single binary downloads with verified checksums
+1. **Immediate Solution: Hermetic Download Strategies**
+   - ✅ All tools use download strategy with verified checksums
+   - ✅ Cross-platform support for all major platforms
    - ✅ All 5 core tools (wasm-tools, wit-bindgen, wasmtime, wac, wkg) working
 
 2. **Long-term Solution: Self-Hosted Tool Builder Workspace**
@@ -71,13 +71,10 @@ tools-builder/
 **Implementation**:
 
 ```starlark
-# toolchains/hermetic_extension.bzl
-http_file(
-    name = "wac_hermetic",
-    urls = ["https://github.com/bytecodealliance/wac/releases/download/v0.7.0/wac-cli-x86_64-unknown-linux-musl"],
-    sha256 = "dd734c4b049287b599a3f8c553325307687a17d070290907e3d5bbe481b89cc6",
-    executable = True,
-    downloaded_file_path = "wac",
+# wasm/extensions.bzl
+wasm_toolchain.register(
+    strategy = "download",
+    version = "1.235.0",  # wasm-tools, wit-bindgen, wac all downloaded with verified checksums
 )
 ```
 
@@ -153,9 +150,9 @@ tools-builder/ ──build──▶ GitHub Releases ──publish──▶ Main
 
 ### Modified Files
 
-- `MODULE.bazel`: Added wac_hermetic and wkg_hermetic to use_repo
-- `toolchains/hermetic_extension.bzl`: Added http_file downloads for wac/wkg
-- `toolchains/BUILD.bazel`: Added filegroups for new hermetic tools
+- `wasm/extensions.bzl`: Updated toolchain defaults to use download strategy
+- `toolchains/*.bzl`: Enhanced download strategies with cross-platform support
+- `MODULE.bazel`: Uses standard toolchain download strategies
 
 ### New Files (Tool Builder Workspace)
 

docs-site/src/content/docs/getting-started.mdx

@@ -119,6 +119,7 @@ Now that you have your first component working, explore more advanced features:
 - [**JavaScript Components**](/languages/javascript/) - ComponentizeJS integration
 
 ### Advanced Topics
+- [**Toolchain Configuration**](/guides/toolchain-configuration/) - Strategies, versions, CI/CD setup
 - [**Component Composition**](/composition/wac/) - Building multi-component systems
 - [**OCI Publishing**](/production/publishing/) - Distribute via container registries
 - [**Performance Optimization**](/production/performance/) - Wizer pre-initialization

docs-site/src/content/docs/installation.md

@@ -86,16 +86,13 @@ wasm_toolchain = use_extension(
 )
 wasm_toolchain.register(
     name = "wasm_tools",
-    version = "1.0.60",  # Optional, defaults to latest stable
-)
-
-# Configure wit-bindgen version
-wasm_toolchain.register(
-    name = "wit_bindgen",
-    version = "0.30.0",  # Optional, defaults to latest stable
+    strategy = "download",  # Default: hermetic builds
+    version = "1.235.0",    # Pin specific version
 )
 ```
 
+> **💡 Need advanced configuration?** See the [Toolchain Configuration Guide](/guides/toolchain-configuration/) for strategies, version management, CI/CD setup, and corporate environments.
+
 ## Language-Specific Setup
 
 ### Rust Configuration
@@ -167,7 +164,7 @@ For JavaScript/TypeScript components:
 # Configure jco (JavaScript Component Tools)
 jco = use_extension("@rules_wasm_component//wasm:extensions.bzl", "jco")
 jco.register(
-    strategy = "npm",  # or "system" or "download"
+    strategy = "npm",  # or "download"
     version = "1.4.0",  # Optional for npm/download strategies
 )
 ```

docs/toolchain_configuration.md

@@ -1,13 +1,13 @@
 # Toolchain Configuration
 
-The rules_wasm_component supports flexible toolchain configuration with three acquisition strategies: system tools, downloaded binaries, and building from source.
+The rules_wasm_component supports flexible toolchain configuration with multiple acquisition strategies: downloaded binaries, building from source, and hybrid approaches.
 
 ## Quick Reference
 
-### Use System Tools (Default)
+### Use Downloaded Tools (Default)
 
 ```starlark
-# MODULE.bazel - Uses tools from PATH (CI-friendly)
+# MODULE.bazel - Downloads prebuilt binaries for hermetic builds
 bazel_dep(name = "rules_wasm_component", version = "0.1.0")
 ```
 
@@ -39,26 +39,28 @@ wasm_toolchain.register(
 
 ## Configuration Options
 
-### Strategy: `"system"` (Default)
+### Strategy: `"download"` (Default)
 
-Uses tools installed on the system PATH. Perfect for:
+Downloads prebuilt binaries from GitHub releases for hermetic builds. Perfect for:
 
-- CI environments where tools are pre-installed
-- Developer machines with `cargo install wasm-tools wac-cli wit-bindgen-cli`
-- Consistent with existing CI setup
+- Reproducible builds with pinned versions
+- Corporate environments without system tool dependencies
+- CI environments requiring hermeticity
 
 ```starlark
 wasm_toolchain.register(
-    strategy = "system",
+    strategy = "download",
+    version = "1.235.0",
 )
 ```
 
-**Requirements:**
+**Benefits:**
 
-- `wasm-tools`, `wac`, and `wit-bindgen` must be in PATH
-- No version control - uses whatever is installed
+- Hermetic builds - no system dependencies
+- Version control with pinned releases
+- Works across all supported platforms
 
-### Strategy: `"download"`
+### Strategy: `"download"` (Explicit)
 
 Downloads prebuilt binaries from GitHub releases:
 
@@ -128,10 +130,11 @@ You can register multiple toolchains for different purposes:
 # MODULE.bazel
 wasm_toolchain = use_extension("@rules_wasm_component//wasm:extensions.bzl", "wasm_toolchain")
 
-# System tools for CI/development
+# Download tools for CI/development
 wasm_toolchain.register(
-    name = "system_tools",
-    strategy = "system",
+    name = "ci_tools",
+    strategy = "download",
+    version = "1.235.0",
 )
 
 # Pinned version for production
@@ -163,16 +166,12 @@ bazel build --extra_toolchains=@dev_tools_toolchains//:wasm_tools_toolchain //..
 
 ### GitHub Actions (Recommended)
 
-Uses system strategy with pre-installed tools:
+Uses download strategy for hermetic builds:
 
 ```yaml
 # .github/workflows/ci.yml
-- name: Install WASM tools
-  run: |
-    cargo install wasm-tools wac-cli wit-bindgen-cli
-
 - name: Build with Bazel
-  run: bazel build //... # Uses system tools automatically
+  run: bazel build //... # Downloads tools automatically for hermetic builds
 ```
 
 ### Docker Builds
@@ -211,7 +210,7 @@ wasm_toolchain.register(
 
 ## Migration Examples
 
-### From CI Script to System Strategy
+### From CI Script to Hermetic Downloads
 
 **Before:**
 
@@ -225,8 +224,7 @@ cargo install wasm-tools wac-cli wit-bindgen-cli
 
 ```yaml
 # .github/workflows/ci.yml
-- run: cargo install wasm-tools wac-cli wit-bindgen-cli
-- run: bazel build //... # Automatically uses system tools
+- run: bazel build //... # Automatically downloads tools for hermetic builds
 ```
 
 ### From Fixed Version to Flexible Strategy
@@ -245,14 +243,9 @@ wasm_toolchain.register(strategy = "download", version = "1.235.0")
 
 ## Troubleshooting
 
-### "Tool not found" with system strategy
-
-```bash
-# Install missing tools
-cargo install wasm-tools wac-cli wit-bindgen-cli
+### "Tool not found" errors
 
-# Or switch to download strategy
-```
+All tools are now downloaded automatically for hermetic builds. If you encounter issues, verify network connectivity and consider using custom URLs for corporate environments.
 
 ### "Download failed" with download strategy
 

examples/js_component/README.md

@@ -75,7 +75,7 @@ The jco toolchain can be configured using different strategies:
 ```starlark
 # MODULE.bazel
 jco = use_extension("@rules_wasm_component//wasm:extensions.bzl", "jco")
-jco.register(strategy = "system")
+jco.register(strategy = "npm")
 ```
 
 ### NPM Installation

platforms/defs.bzl

@@ -6,4 +6,4 @@
 # Standard platform definitions already exist in platforms/BUILD.bazel
 # This file can be used for any cross-workspace platform logic if needed
 
-# For now, this is a minimal file to satisfy load dependencies
+# For now, this is a minimal file to satisfy load dependencies

toolchains/jco_toolchain.bzl

@@ -106,51 +106,20 @@ def _jco_toolchain_repository_impl(repository_ctx):
     platform = _detect_host_platform(repository_ctx)
     version = repository_ctx.attr.version
 
-    if strategy == "system":
-        _setup_system_jco_tools(repository_ctx)
-    elif strategy == "download":
+    if strategy == "download":
         _setup_downloaded_jco_tools(repository_ctx, platform, version)
     elif strategy == "npm":
         _setup_npm_jco_tools(repository_ctx)
     else:
         fail(format_diagnostic_error(
             "E001",
             "Unknown jco strategy: {}".format(strategy),
-            "Must be 'system', 'download', or 'npm'",
+            "Must be 'download' or 'npm'",
         ))
 
     # Create BUILD files
     _create_jco_build_files(repository_ctx)
 
-def _setup_system_jco_tools(repository_ctx):
-    """Set up system-installed jco tools"""
-
-    # Validate system tools
-    tools = [("jco", "jco"), ("node", "node"), ("npm", "npm")]
-
-    for tool_name, binary_name in tools:
-        validation_result = validate_system_tool(repository_ctx, binary_name)
-
-        if not validation_result["valid"]:
-            fail(validation_result["error"])
-
-        if "warning" in validation_result:
-            print(validation_result["warning"])
-
-        # Create symlink to system tool (Bazel-native approach)
-        tool_path = validation_result.get("path", repository_ctx.which(binary_name))
-        if tool_path:
-            repository_ctx.symlink(tool_path, tool_name)
-        else:
-            # Fallback: use PATH resolution
-            repository_ctx.file(tool_name, binary_name, executable = True)
-
-        print("Using system {}: {} at {}".format(
-            tool_name,
-            binary_name,
-            validation_result.get("path", "system PATH"),
-        ))
-
 def _setup_downloaded_jco_tools(repository_ctx, platform, version):
     """Download prebuilt jco tools"""
 
@@ -371,9 +340,9 @@ jco_toolchain_repository = repository_rule(
     implementation = _jco_toolchain_repository_impl,
     attrs = {
         "strategy": attr.string(
-            doc = "Tool acquisition strategy: 'system', 'download', or 'npm'",
-            default = "system",
-            values = ["system", "download", "npm"],
+            doc = "Tool acquisition strategy: 'download' or 'npm'",
+            default = "npm",
+            values = ["download", "npm"],
         ),
         "version": attr.string(
             doc = "jco version to use",

toolchains/wasm_toolchain.bzl

@@ -134,9 +134,7 @@ def _wasm_toolchain_repository_impl(repository_ctx):
     for warning in compatibility_warnings:
         print("Warning: {}".format(warning))
 
-    if strategy == "system":
-        _setup_system_tools_enhanced(repository_ctx)
-    elif strategy == "download":
+    if strategy == "download":
         _setup_downloaded_tools(repository_ctx)  # Use simple method for stability
     elif strategy == "build":
         _setup_built_tools_enhanced(repository_ctx)
@@ -148,41 +146,12 @@ def _wasm_toolchain_repository_impl(repository_ctx):
         fail(format_diagnostic_error(
             "E001",
             "Unknown strategy: {}".format(strategy),
-            "Must be 'system', 'download', 'build', 'bazel', or 'hybrid'",
+            "Must be 'download', 'build', 'bazel', or 'hybrid'",
         ))
 
     # Create BUILD files for all strategies
     _create_build_files(repository_ctx)
 
-def _setup_system_tools_enhanced(repository_ctx):
-    """Set up system-installed tools from PATH with validation"""
-
-    tools = ["wasm-tools", "wac", "wit-bindgen", "wrpc", "wasmsign2"]
-
-    for tool_name in tools:
-        # Validate system tool
-        validation_result = validate_system_tool(repository_ctx, tool_name)
-
-        if not validation_result["valid"]:
-            fail(validation_result["error"])
-
-        if "warning" in validation_result:
-            print(validation_result["warning"])
-
-        # Create wrapper executable
-        repository_ctx.file(tool_name, """#!/bin/bash
-exec {} "$@"
-""".format(tool_name), executable = True)
-
-        print("Using system tool: {} at {}".format(
-            tool_name,
-            validation_result.get("path", "system PATH"),
-        ))
-
-def _setup_system_tools(repository_ctx):
-    """Set up system-installed tools from PATH (legacy)"""
-    _setup_system_tools_enhanced(repository_ctx)
-
 def _setup_downloaded_tools_enhanced(repository_ctx):
     """Download prebuilt tools with enhanced error handling and caching"""
 
@@ -817,8 +786,10 @@ def _setup_bazel_native_tools(repository_ctx):
 
     # Create placeholder wac (will be updated to rust_binary later)
     repository_ctx.file("wac", """#!/bin/bash
-echo "wac: using fallback to hermetic binary"
-exec @wac_hermetic//:wac "$@"
+echo "wac: Bazel-native rust_binary not yet implemented"
+echo "Using placeholder - switch to 'download' strategy in MODULE.bazel for full functionality"
+echo "To use wac, switch to 'download' strategy in MODULE.bazel"
+exit 1
 """, executable = True)
 
     # Create placeholder wit-bindgen (will be updated to rust_binary later)
@@ -1054,9 +1025,9 @@ wasm_toolchain_repository = repository_rule(
     implementation = _wasm_toolchain_repository_impl,
     attrs = {
         "strategy": attr.string(
-            doc = "Tool acquisition strategy: 'system', 'download', 'build', 'bazel', or 'hybrid'",
-            default = "system",
-            values = ["system", "download", "build", "bazel", "hybrid"],
+            doc = "Tool acquisition strategy: 'download', 'build', 'bazel', or 'hybrid'",
+            default = "hybrid",
+            values = ["download", "build", "bazel", "hybrid"],
         ),
         "version": attr.string(
             doc = "Version to use (for download/build strategies)",

toolchains/wasm_tools_repositories.bzl

@@ -55,4 +55,12 @@ def register_wasm_tool_repositories():
         build_file = "//toolchains:BUILD.wizer",
     )
 
+    # wasmsign2: WebAssembly component signing tool
+    git_repository(
+        name = "wasmsign2_src",
+        remote = "https://github.com/wasm-signatures/wasmsign2.git",
+        tag = "0.2.6",
+        build_file = "//toolchains:BUILD.wasmsign2",
+    )
+
     print("✅ Modernized WASM tool repositories registered - replaced all git clone operations")