Merge pull request #47 from rivet-dev/ralph/nodejs-conformance-tests

feat: Node.js conformance test suite integration

Author: NathanFlurry

.github/workflows/conformance.yml

@@ -0,0 +1,55 @@
+name: Node.js Conformance Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 8.15.6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Import upstream Node.js tests
+        run: pnpm tsx packages/secure-exec/tests/node-conformance/scripts/import-tests.ts --node-version 22.14.0
+
+      - name: Validate expectations
+        run: pnpm tsx packages/secure-exec/tests/node-conformance/scripts/validate-expectations.ts
+
+      - name: Run conformance tests
+        run: pnpm vitest run packages/secure-exec/tests/node-conformance/runner.test.ts
+
+      - name: Generate conformance report
+        run: pnpm tsx packages/secure-exec/tests/node-conformance/scripts/generate-report.ts
+
+      - name: Upload conformance artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: conformance-report
+          path: |
+            packages/secure-exec/tests/node-conformance/conformance-report.json
+            docs/conformance-report.mdx

CLAUDE.md

@@ -93,6 +93,15 @@
 - read `docs-internal/arch/overview.md` for the component map (NodeRuntime, RuntimeDriver, NodeDriver, NodeExecutionDriver, ModuleAccessFileSystem, Permissions)
 - keep it up to date when adding, removing, or significantly changing components
 
+## Code Transformation Policy
+
+- NEVER use regex-based source code transformation for JavaScript/TypeScript (e.g., converting ESM to CJS, rewriting imports, extracting exports)
+- regex transformers break on multi-line syntax, code inside strings/comments/template literals, and edge cases like `import X, { a } from 'Y'` — these bugs are subtle and hard to catch
+- instead, use proper tooling: `es-module-lexer` / `cjs-module-lexer` (the same WASM-based lexers Node.js uses), or run the transformation inside the V8 isolate where the JS engine handles parsing correctly
+- if a source transformation is needed at the bridge/host level, prefer a battle-tested library over hand-rolled regex
+- the V8 runtime already has dual-mode execution (`execute_script` for CJS, `execute_module` for ESM) — lean on V8's native module system rather than pre-transforming source on the host side
+- existing regex-based transforms (e.g., `convertEsmToCjs`, `transformDynamicImport`, `isESM`) are known technical debt and should be replaced
+
 ## Contracts (CRITICAL)
 
 - `.agent/contracts/` contains behavioral contracts — these are the authoritative source of truth for runtime, bridge, permissions, stdlib, and governance requirements
@@ -173,6 +182,12 @@ Follow the style in `packages/secure-exec/src/index.ts`.
 - when adding new work, add it to todo.md
 - when completing work, mark items done in todo.md
 
+## Ralph (Autonomous Agent)
+
+- Ralph's working directory is `scripts/ralph/` — this contains `prd.json`, `progress.txt`, `ralph.sh`, `CLAUDE.md`, and the `archive/` folder
+- do NOT create a `.ralph/` directory at the repo root; `scripts/ralph/` is the canonical location
+- when creating or converting PRDs for Ralph, write to `scripts/ralph/prd.json`
+
 ## Skills
 
 - create project skills in `.claude/skills/`