Module improvements

.github/workflows/ci.yaml

@@ -78,16 +78,22 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        group: [1, 2, 3, 4, 5, 6, 7, 8]
+        group: [1, 2, 3, 4, 5, 6, 7, 8, 9]
     steps:
       - uses: actions/checkout@v4
         with:
           submodules: true
       - uses: ./.github/actions/setup
       - name: Enable Golem wasmtime fork
         run: bash .github/scripts/enable-wasmtime-fork.sh
-      - name: Runtime tests (group ${{ matrix.group }}/8)
+      - uses: actions/setup-node@v4
+        if: matrix.group == 9
+        with:
+          node-version: "22.14.0"
+      - name: Runtime tests (group ${{ matrix.group }}/9)
         run: cargo test --test runtime $CI_WASMTIME_FORK_FEATURES -- --report-time --format ctrf --logfile target/ctrf.json ':tag:group${{ matrix.group }}'
+        env:
+          NODE_MODULES_APP_STRICT_NODE_BASELINE: "1"
       - name: Publish Test Report
         uses: ctrf-io/github-test-reporter@v1
         if: always()

.nvmrc

@@ -0,0 +1 @@
+22.14.0

AGENTS.md

@@ -39,6 +39,22 @@ cargo build --release
 cargo test
 ```
 
+### Optional fast test caches
+
+The runtime and node compatibility test harness keeps all cache behavior off by default. For local iteration, enable the clean-state-preserving caches explicitly:
+
+```bash
+WASM_RQUICKJS_TEST_FAST=1 cargo test --test runtime --features use-golem-wasmtime -- module_resolution --report-time --test-threads 1
+```
+
+`WASM_RQUICKJS_TEST_FAST=1` enables:
+
+- `WASM_RQUICKJS_TEST_WASMTIME_CACHE=1` — uses Wasmtime's filesystem compilation cache.
+- `WASM_RQUICKJS_TEST_PREPARED_COMPONENT_CACHE=1` — reuses process-local `Engine`/`Linker`/`Component` values on the normal `TestInstance::new` path while still creating a fresh `Store`, component instance, WASI context, temp dir, and QuickJS runtime state per test. Node-compat tests that use `GolemPreparedComponent` do not currently use this cache layer.
+- `WASM_RQUICKJS_TEST_ARTIFACT_CACHE=1` — reuses wrapper build and optimized component artifacts when their source inputs are unchanged.
+
+Use `WASM_RQUICKJS_TEST_DROP_CACHE=1` with the artifact cache to force wrapper build and Wizer outputs to be refreshed. Do not use grouped tests to speed up module compatibility checks; these tests rely on clean runtime state per case.
+
 ### ⚠️ CRITICAL TEST RULES
 
 **DO NOT run `cargo test` without arguments** — it runs everything and takes too long. **ALWAYS filter** to a specific test harness and module. Load the `skeleton-development` skill for full test rules and examples.
@@ -149,6 +165,19 @@ The `tests/node_compat/` directory contains vendored Node.js test files used to
 
 Load the `fixing-node-compat-test` skill for the full workflow when making a test pass.
 
+## Node Modules App Tests
+
+The `tests/node_modules_apps/` directory contains CI-enforced runtime tests for unbundled npm apps installed with real `node_modules` and attached to the component filesystem as `/app`. This suite is separate from `tests/libraries/`, which documents Rollup-bundled package compatibility.
+
+Important rules:
+
+- `tests/node_modules_apps/config.jsonc` is the source of truth for node modules app tests. Runtime tests in `tests/runtime/node_modules_apps.rs` are generated from it.
+- Add app fixtures under `tests/node_modules_apps/apps/<app>/` with a `package.json`, `run-node.mjs`, and `test-*` files exporting `run()`.
+- Node modules app tests run `npm install --install-links --ignore-scripts --no-audit --no-fund`, verify the raw test with host Node.js, then run it through wasm-rquickjs from `/app`.
+- Keep this suite focused on real `node_modules` module loading, CJS/ESM interop, package maps, filesystem-backed package behavior, and high-value smoke tests. Do not use it for native `.node`, WASM artifact loading, subprocess-heavy, or live-network scenarios.
+- CI runs node modules app tests as runtime `group9`; regular runtime tests use `group1` through `group8`.
+- Before running node modules app runtime tests after skeleton changes, run `./cleanup-skeleton.sh`, then use `cargo test --test runtime --features use-golem-wasmtime -- ':tag:group9'` for the CI-like group, `cargo test --test runtime --features use-golem-wasmtime -- node_modules_app --nocapture` for the full node modules app suite, or a narrower node modules app filter.
+
 ### ⚠️ Keeping `node_compat` and `node_compat_report` in sync
 
 The `tests/node_compat.rs` test harness and the `tests/node_compat_report.rs` report generator are **two separate runners** with independent Host types, linker setups, and WASI context configurations. **Whenever you change the WASI context, linker setup, or Host configuration in `tests/common/mod.rs` (used by `node_compat`), you MUST apply the same change to `tests/node_compat_report.rs`** — otherwise the two runners will produce different results.

README.md

@@ -570,7 +570,8 @@ Compatibility stubs — no V8 inspector in WASM.
 <details>
 <summary><strong><code>node:module</code></strong></summary>
 
-- `require`, `createRequire`, `builtinModules`, `isBuiltin`, `runMain`, `_nodeModulePaths`
+- `require`, `require.resolve`, `createRequire`, `builtinModules`, `isBuiltin`, `runMain`, `_nodeModulePaths`
+- Package resolution supports `package.json` `main`, `exports` root/subpath maps, wildcard `exports` patterns, `imports` maps, and wildcard `imports` patterns. CJS resolution recognizes `golem`, `node`, `require`, `module-sync`, and `default` conditions; ESM resolution recognizes `golem`, `node`, `import`, `module-sync`, and `default`. Package `imports` can target relative files, external packages, and `node:` builtins.
 
 </details>
 
@@ -1452,6 +1453,22 @@ There are a few important things to keep in mind when working on the project:
   times and huge resulting binaries. Use the `cleanup-skeleton.sh` script to quickly remove the `target` directory from
   the `skeleton` crate.
 
+- Runtime and node compatibility tests that use the shared `CompiledTest` harness support opt-in local caches for faster
+  iteration:
+  `WASM_RQUICKJS_TEST_FAST=1 cargo test --test runtime --features use-golem-wasmtime -- module_resolution --report-time --test-threads 1`.
+  The caches are off by default and preserve a fresh Wasmtime `Store`, component instance, WASI context, temporary
+  directory, and QuickJS runtime state for each test. `WASM_RQUICKJS_TEST_FAST=1` enables the wrapper/optimized artifact
+  cache, prepared component cache, and Wasmtime compilation cache together. Use `WASM_RQUICKJS_TEST_ARTIFACT_CACHE=1`,
+  `WASM_RQUICKJS_TEST_PREPARED_COMPONENT_CACHE=1`, or `WASM_RQUICKJS_TEST_WASMTIME_CACHE=1` to enable only one layer, and
+  `WASM_RQUICKJS_TEST_DROP_CACHE=1` when generated wrapper or optimized component artifacts must be rebuilt; it forces
+  artifact cache freshness checks to miss, removes the central wrapper cache stamps, clears the in-process prepared
+  component cache, and bypasses the Wasmtime compilation cache for that run. `WASM_RQUICKJS_TEST_UNOPTIMIZED=1` skips
+  Wizer pre-initialization for `CompiledTest::new*` fixtures when a very short compile/test loop is more useful than
+  optimized-component startup behavior. The prepared component cache
+  currently applies to the normal `TestInstance::new` path; node-compat tests that instantiate through
+  `GolemPreparedComponent` still benefit from artifact and Wasmtime compilation caches, but do not use that prepared
+  component cache layer.
+
 ## Acknowledgements
 
 The builtin JS modules are based on the work of several other projects: