@vitronai/themis 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+## 1.3.0 - 2026-05-03
+
+### Added
+
+- **`themis migrate node` codemod.** New third migration source converts test files written with `node:test` + `node:assert/strict` (default-import or named-import shapes) to Themis-native primitives. Handles `assert.equal`/`strictEqual` → `expect().toBe()`, `deepEqual`/`deepStrictEqual` → `toEqual()`, `ok` → `toBeTruthy()`, `match(str, /re/)` → `toMatch()`, `rejects(...)` → async try/catch wrapper, and `test.after`/`test.afterEach` → `afterAll`/`afterEach`. Also strips the optional 3rd-arg options object from `test(name, options, fn)` calls. Uses a balanced-paren scanner with regex-literal awareness so escaped slashes inside regex args don't trip the parser.
+- **`toMatch(string | RegExp)` matcher** in core `expect`. Jest-compatible. Matches strings against a substring or regex; throws if `received` is not a string.
+- **`--isolation process` mode.** Spawns a fresh Node child process (`child_process.fork`) per test file, mirroring `node --test`'s isolation model. Use this when tests mutate `process.env`, `process.cwd()`, or other process-level state at module-load time and depend on the SUT picking up those mutations — the worker-thread model freezes `os.homedir()` and shares the ESM module cache across files in `in-process` mode.
+- **`npm run verify:dogfood`** — runs the migrator + Themis test pass against `alethia-mcp`'s `bridge-tests/*.mjs` (set `ALETHIA_MCP_REPO` to override path). Currently 57/57 green.
+- ESM runtime support (`.mjs`, `.cjs`, `.js` in `type:module` packages) via dynamic `import()` in `src/module-loader.js`. Backed by 5 fixtures in `tests/fixtures/esm/` and `npm run proof:esm`. Mock-via-`mock(...)` is not supported for ESM imports (CJS only); document if encountered.
+- `node:test` / `node:assert` residual-import detection in `MIGRATION_ASSIST_PATTERNS` so post-migration leftovers surface as warnings.
+
+### Changed
+
+- Default `testRegex` now matches `.mjs` and `.cjs` test files in addition to `.js/.jsx/.ts/.tsx`.
+- Migration report `summary` gains `nodeTest` and `nodeAssert` counters; `source` enum extended to `['jest', 'vitest', 'node']`. Schema bumped in-place under `themis.migration.report.v1`.
+
+### Notes
+
+- `themis migrate node` silently drops `assert.equal`'s optional 3rd-arg message string (same posture as the existing jest/vitest codemods). Failure messages still surface via Themis assertion output.
+- TS files inside `type:module` packages still transpile to CJS and crash in ESM scope — out of scope for this release; defer until a partner pulls.
+
+
 ## 1.2.1 - 2026-04-09
 
 - Added `init --cursor` flag to install a `.cursorrules` file with Themis conventions. Composable with `--agents` and `--claude-code`.

package/README.md

@@ -13,8 +13,8 @@ Drop-in alternative to Jest and Vitest. Agents write tests, get structured failu
 
 - **Faster** — 68.59% faster than Vitest, 130.26% faster than Jest on the same benchmark ([proof](#performance))
 - **Agent-native** — `--agent` JSON with failure clusters and structured repair hints
-- **One-command migration** — `npx themis migrate jest` or `vitest` with codemods
-- **Modern by default** — `.ts`, `.tsx`, `.js`, `.jsx`, ESM, React Testing Library, no config gymnastics
+- **One-command migration** — `npx themis migrate jest`, `vitest`, or `node` (for `node:test` suites) with codemods
+- **Modern by default** — `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, ESM, React Testing Library, no config gymnastics
 - **Discoverable** — ships `AGENTS.md`, `themis.ai.json`, and a [Tessl tile](tessl/tile.json) so agents find and adopt it automatically
 
 ---
@@ -110,13 +110,22 @@ npx themis test --fix
 ### Migration
 
 ```bash
-npx themis migrate jest
-npx themis migrate vitest
+npx themis migrate jest      # Jest suites
+npx themis migrate vitest    # Vitest suites
+npx themis migrate node      # node:test + node:assert/strict suites
 npx themis test
 ```
 
 One command scaffolds a compatibility bridge. Add `--rewrite-imports` to rewrite import paths, `--convert` for codemods. See the [migration guide](docs/migration.md).
 
+For tests that mutate `process.env` or other process-level state at module load (and import the SUT after), pair with per-file process isolation:
+
+```bash
+npx themis test --isolation process
+```
+
+This spawns a fresh Node child process per test file (mirroring `node --test`), so `os.homedir()`, the ESM module cache, and other process-state are not shared across files.
+
 ---
 
 ## Config

package/docs/api.md

@@ -28,7 +28,7 @@ For machine-readable agent adoption metadata, see [`themis.ai.json`](../themis.a
 themis test [options]
 themis init [--agents]
 themis generate [path]
-themis migrate <jest|vitest>
+themis migrate <jest|vitest|node>
 ```
 
 ## `themis init`
@@ -203,7 +203,7 @@ Migration options:
 | `--reporter spec\|next\|json\|agent\|html` | string | Explicit reporter override. |
 | `--workers <N>` | positive integer | Override worker count. Invalid values fail fast. |
 | `--environment node\|jsdom` | string | Override the configured test environment. |
-| `--isolation worker\|in-process` | string | Select worker isolation or a zero IPC in-process execution mode. |
+| `--isolation worker\|in-process\|process` | string | Select isolation model. `worker` (default) = worker thread per file. `in-process` = sequential in the parent (fastest reruns; shares ESM cache + process state across files). `process` = `child_process.fork` per file, mirroring `node --test` (use when tests mutate `process.env`/`process.cwd()` at module load). |
 | `--cache` | flag | Enable file-level result caching for in-process local loops. |
 | `--update-contracts` | flag | Accept updated `captureContract(...)` baselines for the selected tests. |
 | `-w`, `--watch` | flag | Rerun the selected suite when watched project files change. |
@@ -219,7 +219,7 @@ Migration compatibility:
 - imports from `@jest/globals` are supported at runtime
 - imports from `vitest` are supported at runtime
 - imports from `@testing-library/react` are supported via Themis `render`, `screen`, `fireEvent`, `waitFor`, `cleanup`, and `act`
-- `themis migrate <jest|vitest>` also emits `.themis/migration/migration-report.json` with detected files, migration mode details, assistant findings, and recommended next actions
+- `themis migrate <jest|vitest|node>` also emits `.themis/migration/migration-report.json` with detected files, migration mode details, assistant findings, and recommended next actions
 
 Additional option:
 
@@ -229,6 +229,7 @@ Execution note:
 
 - `--watch --isolation in-process --cache` is the fastest local rerun mode
 - `--isolation worker` remains the safer mode for CI and global-heavy suites
+- `--isolation process` is required for tests that mutate `process.env`/`process.cwd()` at module load (matches `node --test`'s isolation model)
 - `--watch` is intended for short edit-run-review loops for both humans and AI agents
 
 Snapshot note:

package/docs/migration.md

@@ -1,4 +1,4 @@
-# Migrating From Jest And Vitest
+# Migrating From Jest, Vitest, And node:test
 
 Themis is designed for incremental migration. Start by running existing suites under the Themis runtime, then convert touched tests toward native contracts and `intent(...)` flows as you work.
 
@@ -12,14 +12,42 @@ npx themis migrate jest --assist
 npx themis test
 ```
 
-Use `vitest` instead of `jest` for Vitest suites.
+Use `vitest` for Vitest suites or `node` for `node:test` suites in place of `jest`.
 
 ## Migration modes
 
-- `themis migrate <jest|vitest>`: scaffold config, setup, compat bridge, and migration report.
-- `--rewrite-imports`: point framework imports at `themis.compat.js`.
-- `--convert`: remove common Jest/Vitest imports and rewrite common matcher/test patterns into Themis-native forms.
-- `--assist`: run the safe rewrite and conversion passes together, then report leftover Jest/Vitest-only helpers that still need manual follow-up.
+- `themis migrate <jest|vitest|node>`: scaffold config and migration report. For `jest`/`vitest`, also writes a setup file and a compat bridge; `node` skips both (Themis provides the same globals natively).
+- `--rewrite-imports`: point framework imports at `themis.compat.js` (jest/vitest only — `node` source has no compat shim, conversion is direct).
+- `--convert`: remove common framework imports and rewrite matcher/test patterns into Themis-native forms.
+- `--assist`: run the safe rewrite and conversion passes together, then report leftover framework-specific helpers that still need manual follow-up.
+
+## node:test specifics
+
+`themis migrate node` handles the following transforms:
+
+| Input (node:test + node:assert/strict) | Output (Themis) |
+| --- | --- |
+| `import test from 'node:test'` | dropped (`test` is a Themis global) |
+| `import assert from 'node:assert/strict'` | dropped (`expect` replaces all asserts) |
+| `assert.equal(a, b)` / `strictEqual` | `expect(a).toBe(b)` |
+| `assert.deepEqual(a, b)` / `deepStrictEqual` | `expect(a).toEqual(b)` |
+| `assert.ok(v)` | `expect(v).toBeTruthy()` |
+| `assert.match(s, /re/)` | `expect(s).toMatch(/re/)` |
+| `await assert.rejects(fn, /re/)` | async try/catch wrapper + `toMatch` on the error message |
+| `test.after(fn)` / `test.afterEach(fn)` | `afterAll(fn)` / `afterEach(fn)` |
+| `test(name, { timeout }, fn)` | `test(name, fn)` (options arg silently dropped) |
+
+Not supported in this pass: `t.test()` subtests, `t.context`, `test.only`, `describe`/`it` exported from `node:test` (use Themis globals instead), `assert.throws`/`notEqual`/`fail`/`doesNotReject`, source-map line preservation. The optional 3rd-arg message string on `assert.equal`-family calls is silently dropped.
+
+## Process-state isolation
+
+`node:test` runs each test file in its own child process. If your suite mutates `process.env`, `process.cwd()`, or other process-level state at module load (e.g. `process.env.HOME = mkdtempSync(...)` before `await import('../dist/index.js')`), pair `themis test` with per-file process isolation:
+
+```bash
+npx themis test --isolation process
+```
+
+This spawns a fresh Node child process per test file via `child_process.fork`, mirroring `node --test`'s isolation model. The default `worker` mode shares process-state (especially `os.homedir()` cached at worker startup) across files and will surface as cross-file leakage for state-mutating tests.
 
 ## Before And After
 

package/docs/schemas/migration-report.v1.json

@@ -12,7 +12,7 @@
     },
     "source": {
       "type": "string",
-      "enum": ["jest", "vitest"]
+      "enum": ["jest", "vitest", "node"]
     },
     "createdAt": {
       "type": "string"
@@ -35,6 +35,8 @@
         "jestGlobals",
         "vitest",
         "testingLibraryReact",
+        "nodeTest",
+        "nodeAssert",
         "rewrittenFiles",
         "rewrittenImports",
         "convertedFiles",
@@ -50,6 +52,8 @@
         "jestGlobals": { "type": "number" },
         "vitest": { "type": "number" },
         "testingLibraryReact": { "type": "number" },
+        "nodeTest": { "type": "number" },
+        "nodeAssert": { "type": "number" },
         "rewrittenFiles": { "type": "number" },
         "rewrittenImports": { "type": "number" },
         "convertedFiles": { "type": "number" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/themis",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "A Node.js and TypeScript unit test framework designed for AI coding agents. Drop-in alternative to Jest and Vitest with machine-readable failure output, structured repair hints, and one-command migration.",
   "license": "MIT",
   "author": "Vitron AI",
@@ -97,6 +97,8 @@
     "benchmark:first-try": "node scripts/benchmark-first-try.js",
     "benchmark:gate": "node scripts/benchmark-gate.js",
     "proof:migration": "node scripts/verify-migration-fixtures.js",
+    "proof:esm": "node scripts/verify-esm-fixtures.js",
+    "verify:dogfood": "node scripts/verify-alethia-bridge-dogfood.js",
     "pack:check": "npm pack --dry-run",
     "prepublishOnly": "npm run lint && npm test && npm run typecheck"
   },

package/src/cli.js

@@ -147,7 +147,11 @@ async function main(argv) {
       }
       console.log(`Report: ${formatCliPath(cwd, result.reportPath)}`);
     }
-    console.log('Runtime compatibility is enabled for @jest/globals, vitest, and @testing-library/react imports.');
+    if (result.source === 'node') {
+      console.log('node:test and node:assert imports are dropped during conversion; Themis provides test/expect/afterAll/afterEach as globals.');
+    } else {
+      console.log('Runtime compatibility is enabled for @jest/globals, vitest, and @testing-library/react imports.');
+    }
     console.log('Next: run npx themis test or npm run test:themis');
     return;
   }
@@ -778,10 +782,10 @@ function validateWorkerCount(flagValue, configValue) {
 }
 
 function validateIsolation(value) {
-  if (value === 'worker' || value === 'in-process') {
+  if (value === 'worker' || value === 'in-process' || value === 'process') {
     return;
   }
-  throw new Error(`Unsupported --isolation value: ${value}. Use one of: worker, in-process.`);
+  throw new Error(`Unsupported --isolation value: ${value}. Use one of: worker, in-process, process.`);
 }
 
 function resolveWorkerCount(flagValue, configValue) {
@@ -814,8 +818,8 @@ function printUsage() {
   console.log('  generate [path]         Scan source files and generate Themis contract tests');
   console.log('                         Options: [--json] [--plan] [--output path] [--files a,b] [--match-source regex] [--match-export regex] [--scenario name] [--min-confidence level] [--require-confidence level] [--include regex] [--exclude regex] [--review] [--update] [--clean] [--changed] [--force] [--strict] [--write-hints] [--fail-on-skips] [--fail-on-conflicts]');
   console.log('  scan [path]             Alias for generate');
-  console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert] [--assist]   Scaffold an incremental migration bridge for existing suites');
-  console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process] [--cache] [--update-contracts] [--fix] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
+  console.log('  migrate <jest|vitest|node> [--rewrite-imports] [--convert] [--assist]   Scaffold an incremental migration bridge for existing suites');
+  console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process|process] [--cache] [--update-contracts] [--fix] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
 }
 
 function printGenerateSummary(summary, cwd) {

package/src/config.js

@@ -5,7 +5,7 @@ const os = require('os');
 const DEFAULT_CONFIG = {
   testDir: 'tests',
   generatedTestsDir: path.join('__themis__', 'tests'),
-  testRegex: '\\.(test|spec)\\.(js|jsx|ts|tsx)$',
+  testRegex: '\\.(test|spec)\\.(js|jsx|ts|tsx|mjs|cjs)$',
   maxWorkers: Math.max(1, os.cpus().length - 1),
   reporter: 'next',
   environment: 'node',

package/src/expect.js

@@ -70,6 +70,24 @@ function createExpect(_context = {}) {
 
         throw new Error('toContain only supports strings and arrays');
       },
+      toMatch(expected) {
+        if (typeof received !== 'string') {
+          throw new Error(`toMatch expects a string, received ${format(received)}`);
+        }
+        if (typeof expected === 'string') {
+          if (!received.includes(expected)) {
+            throw new Error(`Expected ${format(received)} to match substring ${format(expected)}`);
+          }
+          return;
+        }
+        if (expected instanceof RegExp) {
+          if (!expected.test(received)) {
+            throw new Error(`Expected ${format(received)} to match ${String(expected)}`);
+          }
+          return;
+        }
+        throw new Error('toMatch expects a string or RegExp');
+      },
       toThrow(match) {
         if (typeof received !== 'function') {
           throw new Error('toThrow expects a function');

package/src/migrate.js

@@ -4,7 +4,7 @@ const { DEFAULT_CONFIG, loadConfig } = require('./config');
 const { ARTIFACT_RELATIVE_PATHS } = require('./artifact-paths');
 const { ensureGitignoreEntries } = require('./gitignore');
 
-const SUPPORTED_MIGRATION_SOURCES = new Set(['jest', 'vitest']);
+const SUPPORTED_MIGRATION_SOURCES = new Set(['jest', 'vitest', 'node']);
 const THEMIS_SETUP_FILE = path.join('tests', 'setup.themis.js');
 const THEMIS_COMPAT_FILE = 'themis.compat.js';
 const MIGRATION_REPORT_FILE = ARTIFACT_RELATIVE_PATHS.migrationReport;
@@ -19,6 +19,14 @@ const MIGRATION_ASSIST_PATTERNS = Object.freeze([
     message: 'Framework-specific imports are still present after migration scaffolding.',
     suggestion: 'Rewrite or remove remaining framework imports so the suite only depends on Themis-compatible entry points.'
   },
+  {
+    id: 'remaining-node-test-import',
+    category: 'remaining-framework-import',
+    severity: 'warning',
+    pattern: /(?:import\s+[^;]*?from\s+['"]node:(?:test|assert(?:\/strict)?)['"]|import\s*\(\s*['"]node:(?:test|assert(?:\/strict)?)['"]\s*\)|require\(\s*['"]node:(?:test|assert(?:\/strict)?)['"]\s*\))/,
+    message: 'node:test or node:assert imports remain after migration; rerun with --convert or rewrite manually.',
+    suggestion: 'Themis provides test/expect/afterAll/afterEach as globals. Drop node:test and node:assert imports and use the Themis equivalents.'
+  },
   {
     id: 'unsupported-helper',
     category: 'unsupported-helper',
@@ -48,7 +56,7 @@ const MIGRATION_ASSIST_PATTERNS = Object.freeze([
 function runMigrate(cwd, framework, options = {}) {
   const source = String(framework || '').trim().toLowerCase();
   if (!SUPPORTED_MIGRATION_SOURCES.has(source)) {
-    throw new Error(`Unsupported migrate source: ${String(framework)}. Use "jest" or "vitest".`);
+    throw new Error(`Unsupported migrate source: ${String(framework)}. Use "jest", "vitest", or "node".`);
   }
 
   const projectRoot = path.resolve(cwd || process.cwd());
@@ -60,7 +68,7 @@ function runMigrate(cwd, framework, options = {}) {
 
   const existingConfig = fs.existsSync(configPath) ? loadConfig(projectRoot) : { ...DEFAULT_CONFIG, setupFiles: [], testIgnore: [] };
   const nextSetupFiles = Array.isArray(existingConfig.setupFiles) ? [...existingConfig.setupFiles] : [];
-  if (!nextSetupFiles.includes(THEMIS_SETUP_FILE)) {
+  if (source !== 'node' && !nextSetupFiles.includes(THEMIS_SETUP_FILE)) {
     nextSetupFiles.push(THEMIS_SETUP_FILE);
   }
 
@@ -69,13 +77,15 @@ function runMigrate(cwd, framework, options = {}) {
     setupFiles: nextSetupFiles
   };
 
-  fs.mkdirSync(path.dirname(setupPath), { recursive: true });
-  if (!fs.existsSync(setupPath)) {
-    fs.writeFileSync(setupPath, buildMigrationSetupSource(source), 'utf8');
-  }
+  if (source !== 'node') {
+    fs.mkdirSync(path.dirname(setupPath), { recursive: true });
+    if (!fs.existsSync(setupPath)) {
+      fs.writeFileSync(setupPath, buildMigrationSetupSource(source), 'utf8');
+    }
 
-  if (!fs.existsSync(compatPath)) {
-    fs.writeFileSync(compatPath, buildMigrationCompatSource(), 'utf8');
+    if (!fs.existsSync(compatPath)) {
+      fs.writeFileSync(compatPath, buildMigrationCompatSource(), 'utf8');
+    }
   }
 
   fs.writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, 'utf8');
@@ -98,7 +108,7 @@ function runMigrate(cwd, framework, options = {}) {
     ? rewriteMigrationImports(projectRoot, scan.matches, compatPath)
     : { rewrittenFiles: [], rewrittenImports: 0 };
   const conversionSummary = options.convert
-    ? convertMigrationFiles(projectRoot, scan.matches)
+    ? convertMigrationFiles(projectRoot, scan.matches, source)
     : { convertedFiles: [], convertedAssertions: 0, removedImports: 0 };
   const assistSummary = analyzeMigrationAssist(projectRoot, scan.matches, {
     enabled: Boolean(options.assist)
@@ -232,6 +242,8 @@ function buildMigrationReport(
       jestGlobals: matches.filter((entry) => entry.imports.includes('@jest/globals')).length,
       vitest: matches.filter((entry) => entry.imports.includes('vitest')).length,
       testingLibraryReact: matches.filter((entry) => entry.imports.includes('@testing-library/react')).length,
+      nodeTest: matches.filter((entry) => entry.imports.includes('node:test')).length,
+      nodeAssert: matches.filter((entry) => entry.imports.includes('node:assert')).length,
       rewrittenFiles: Array.isArray(rewriteSummary.rewrittenFiles) ? rewriteSummary.rewrittenFiles.length : 0,
       rewrittenImports: Number(rewriteSummary.rewrittenImports || 0),
       convertedFiles: Array.isArray(conversionSummary.convertedFiles) ? conversionSummary.convertedFiles.length : 0,
@@ -324,7 +336,7 @@ function normalizeAssistSummary(summary, enabled) {
   };
 }
 
-function convertMigrationFiles(projectRoot, matches) {
+function convertMigrationFiles(projectRoot, matches, source) {
   const convertedFiles = [];
   let convertedAssertions = 0;
   let removedImports = 0;
@@ -332,7 +344,9 @@ function convertMigrationFiles(projectRoot, matches) {
   for (const match of matches) {
     const absoluteFile = path.join(projectRoot, match.file);
     const original = fs.readFileSync(absoluteFile, 'utf8');
-    const converted = convertMigrationSourceText(original);
+    const converted = source === 'node'
+      ? convertNodeTestSourceText(original)
+      : convertMigrationSourceText(original);
     if (converted.source !== original) {
       fs.writeFileSync(absoluteFile, converted.source, 'utf8');
       convertedFiles.push(match.file);
@@ -419,6 +433,363 @@ function convertMigrationSourceText(sourceText) {
   };
 }
 
+function convertNodeTestSourceText(sourceText) {
+  let source = sourceText;
+  let removedImports = 0;
+  let convertedAssertions = 0;
+
+  source = source.replace(
+    /^\s*import\s+test(?:\s*,\s*\{[^}]*\})?\s+from\s+['"]node:test['"];?\s*\n?/gm,
+    () => {
+      removedImports += 1;
+      return '';
+    }
+  );
+
+  source = source.replace(
+    /^\s*import\s+\{[^}]*\}\s+from\s+['"]node:test['"];?\s*\n?/gm,
+    () => {
+      removedImports += 1;
+      return '';
+    }
+  );
+
+  source = source.replace(
+    /^\s*import\s+assert(?:\s*,\s*\{[^}]*\})?\s+from\s+['"]node:assert(?:\/strict)?['"];?\s*\n?/gm,
+    () => {
+      removedImports += 1;
+      return '';
+    }
+  );
+
+  source = source.replace(
+    /^\s*import\s+\{[^}]*\}\s+from\s+['"]node:assert(?:\/strict)?['"];?\s*\n?/gm,
+    () => {
+      removedImports += 1;
+      return '';
+    }
+  );
+
+  const renames = [
+    { pattern: /\btest\.afterEach\s*\(/g, replacement: 'afterEach(' },
+    { pattern: /\btest\.after\s*\(/g, replacement: 'afterAll(' },
+    { pattern: /\btest\.beforeEach\s*\(/g, replacement: 'beforeEach(' },
+    { pattern: /\btest\.before\s*\(/g, replacement: 'beforeAll(' }
+  ];
+  for (const entry of renames) {
+    source = source.replace(entry.pattern, () => {
+      convertedAssertions += 1;
+      return entry.replacement;
+    });
+  }
+
+  const testResult = stripNodeTestOptions(source);
+  source = testResult.source;
+  convertedAssertions += testResult.convertedAssertions;
+
+  const assertResult = rewriteAssertCalls(source);
+  source = assertResult.source;
+  convertedAssertions += assertResult.convertedAssertions;
+
+  source = source.replace(/\n{3,}/g, '\n\n');
+
+  return {
+    source,
+    convertedAssertions,
+    removedImports
+  };
+}
+
+const NODE_ASSERT_REWRITERS = {
+  equal: (args) => `expect(${args[0]}).toBe(${args[1]})`,
+  strictEqual: (args) => `expect(${args[0]}).toBe(${args[1]})`,
+  deepEqual: (args) => `expect(${args[0]}).toEqual(${args[1]})`,
+  deepStrictEqual: (args) => `expect(${args[0]}).toEqual(${args[1]})`,
+  ok: (args) => `expect(${args[0]}).toBeTruthy()`,
+  match: (args) => `expect(${args[0]}).toMatch(${args[1]})`,
+  rejects: (args) => {
+    const subject = args[0];
+    const matcher = args[1];
+    const subjectExpr = `typeof (${subject}) === 'function' ? (${subject})() : (${subject})`;
+    const matcherLine = matcher
+      ? `; expect(String(__themisError && __themisError.message || __themisError)).toMatch(${matcher})`
+      : '';
+    return `(async () => { let __themisError = null; try { await (${subjectExpr}); } catch (__e) { __themisError = __e; } expect(__themisError).toBeTruthy()${matcherLine}; })()`;
+  }
+};
+
+function stripNodeTestOptions(source) {
+  let out = '';
+  let i = 0;
+  let convertedAssertions = 0;
+  const callRegex = /\btest\s*\(/;
+
+  while (i < source.length) {
+    const remaining = source.slice(i);
+    const match = callRegex.exec(remaining);
+    if (!match) {
+      out += remaining;
+      break;
+    }
+
+    const callStart = i + match.index;
+    out += source.slice(i, callStart);
+
+    const prevChar = callStart === 0 ? '' : source[callStart - 1];
+    if (prevChar && /[A-Za-z0-9_$.]/.test(prevChar)) {
+      out += match[0];
+      i = callStart + match[0].length;
+      continue;
+    }
+
+    const openParen = callStart + match[0].length - 1;
+    const closeParen = findCallEnd(source, openParen);
+    if (closeParen === -1) {
+      out += match[0];
+      i = openParen + 1;
+      continue;
+    }
+
+    const body = source.slice(openParen + 1, closeParen);
+    const args = splitTopLevelArgs(body);
+    if (args.length === 3 && args[1].startsWith('{')) {
+      out += `test(${args[0]}, ${args[2]})`;
+      convertedAssertions += 1;
+      i = closeParen + 1;
+      continue;
+    }
+
+    out += source.slice(callStart, closeParen + 1);
+    i = closeParen + 1;
+  }
+
+  return { source: out, convertedAssertions };
+}
+
+function rewriteAssertCalls(source) {
+  let out = '';
+  let i = 0;
+  let convertedAssertions = 0;
+  const callRegex = /assert\.([a-zA-Z]+)\s*\(/;
+
+  while (i < source.length) {
+    const remaining = source.slice(i);
+    const match = callRegex.exec(remaining);
+    if (!match) {
+      out += remaining;
+      break;
+    }
+
+    const callStart = i + match.index;
+    out += source.slice(i, callStart);
+
+    const prevChar = callStart === 0 ? '' : source[callStart - 1];
+    if (prevChar && /[A-Za-z0-9_$]/.test(prevChar)) {
+      out += match[0];
+      i = callStart + match[0].length;
+      continue;
+    }
+
+    const helper = match[1];
+    const rewriter = NODE_ASSERT_REWRITERS[helper];
+    const openParen = callStart + match[0].length - 1;
+
+    if (!rewriter) {
+      out += match[0];
+      i = openParen + 1;
+      continue;
+    }
+
+    const closeParen = findCallEnd(source, openParen);
+    if (closeParen === -1) {
+      out += match[0];
+      i = openParen + 1;
+      continue;
+    }
+
+    const body = source.slice(openParen + 1, closeParen);
+    const args = splitTopLevelArgs(body);
+    if (args.length < 1) {
+      out += match[0] + body + ')';
+      i = closeParen + 1;
+      continue;
+    }
+
+    out += rewriter(args);
+    convertedAssertions += 1;
+    i = closeParen + 1;
+  }
+
+  return { source: out, convertedAssertions };
+}
+
+const REGEX_START_PREV_CHARS = new Set([
+  '(', ',', ';', '{', '}', '[', '=', '!', '&', '|', '+', '-', '*', '/', '%',
+  '<', '>', '?', ':', '^', '~', '\n'
+]);
+
+function shouldStartRegex(source, slashIndex) {
+  for (let k = slashIndex - 1; k >= 0; k -= 1) {
+    const c = source[k];
+    if (c === ' ' || c === '\t') continue;
+    if (c === '\n') return true;
+    if (REGEX_START_PREV_CHARS.has(c)) return true;
+    const wordEnd = k;
+    let wordStart = k;
+    while (wordStart > 0 && /[A-Za-z0-9_$]/.test(source[wordStart - 1])) {
+      wordStart -= 1;
+    }
+    const word = source.slice(wordStart, wordEnd + 1);
+    if (/^(return|typeof|in|of|instanceof|new|throw|delete|void|yield|await|do|else)$/.test(word)) {
+      return true;
+    }
+    return false;
+  }
+  return true;
+}
+
+function findCallEnd(source, openIndex) {
+  let depth = 0;
+  let i = openIndex;
+  let mode = 'code';
+  while (i < source.length) {
+    const ch = source[i];
+    const next = source[i + 1];
+    if (mode === 'code') {
+      if (ch === '/' && next === '/') { mode = 'lc'; i += 2; continue; }
+      if (ch === '/' && next === '*') { mode = 'bc'; i += 2; continue; }
+      if (ch === '/' && shouldStartRegex(source, i)) { mode = 're'; i += 1; continue; }
+      if (ch === "'") { mode = 'sq'; i += 1; continue; }
+      if (ch === '"') { mode = 'dq'; i += 1; continue; }
+      if (ch === '`') { mode = 'tpl'; i += 1; continue; }
+      if (ch === '(') { depth += 1; i += 1; continue; }
+      if (ch === ')') {
+        depth -= 1;
+        if (depth === 0) return i;
+        i += 1; continue;
+      }
+      i += 1; continue;
+    }
+    if (mode === 'sq') {
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === "'") { mode = 'code'; }
+      i += 1; continue;
+    }
+    if (mode === 'dq') {
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === '"') { mode = 'code'; }
+      i += 1; continue;
+    }
+    if (mode === 'tpl') {
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === '`') { mode = 'code'; }
+      i += 1; continue;
+    }
+    if (mode === 're') {
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === '[') { mode = 'rec'; i += 1; continue; }
+      if (ch === '/') {
+        mode = 'code';
+        i += 1;
+        while (i < source.length && /[a-z]/.test(source[i])) i += 1;
+        continue;
+      }
+      i += 1; continue;
+    }
+    if (mode === 'rec') {
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === ']') { mode = 're'; }
+      i += 1; continue;
+    }
+    if (mode === 'lc') {
+      if (ch === '\n') { mode = 'code'; }
+      i += 1; continue;
+    }
+    if (mode === 'bc') {
+      if (ch === '*' && next === '/') { mode = 'code'; i += 2; continue; }
+      i += 1; continue;
+    }
+  }
+  return -1;
+}
+
+function splitTopLevelArgs(body) {
+  const args = [];
+  let depth = 0;
+  let bracket = 0;
+  let brace = 0;
+  let mode = 'code';
+  let start = 0;
+  for (let i = 0; i < body.length; i += 1) {
+    const ch = body[i];
+    const next = body[i + 1];
+    if (mode === 'code') {
+      if (ch === '/' && next === '/') { mode = 'lc'; i += 1; continue; }
+      if (ch === '/' && next === '*') { mode = 'bc'; i += 1; continue; }
+      if (ch === '/' && shouldStartRegex(body, i)) { mode = 're'; continue; }
+      if (ch === "'") { mode = 'sq'; continue; }
+      if (ch === '"') { mode = 'dq'; continue; }
+      if (ch === '`') { mode = 'tpl'; continue; }
+      if (ch === '(') { depth += 1; continue; }
+      if (ch === ')') { depth -= 1; continue; }
+      if (ch === '[') { bracket += 1; continue; }
+      if (ch === ']') { bracket -= 1; continue; }
+      if (ch === '{') { brace += 1; continue; }
+      if (ch === '}') { brace -= 1; continue; }
+      if (ch === ',' && depth === 0 && bracket === 0 && brace === 0) {
+        args.push(body.slice(start, i));
+        start = i + 1;
+      }
+      continue;
+    }
+    if (mode === 'sq') {
+      if (ch === '\\') { i += 1; continue; }
+      if (ch === "'") { mode = 'code'; }
+      continue;
+    }
+    if (mode === 'dq') {
+      if (ch === '\\') { i += 1; continue; }
+      if (ch === '"') { mode = 'code'; }
+      continue;
+    }
+    if (mode === 'tpl') {
+      if (ch === '\\') { i += 1; continue; }
+      if (ch === '`') { mode = 'code'; }
+      continue;
+    }
+    if (mode === 're') {
+      if (ch === '\\') { i += 1; continue; }
+      if (ch === '[') { mode = 'rec'; continue; }
+      if (ch === '/') {
+        mode = 'code';
+        let k = i + 1;
+        while (k < body.length && /[a-z]/.test(body[k])) k += 1;
+        i = k - 1;
+        continue;
+      }
+      continue;
+    }
+    if (mode === 'rec') {
+      if (ch === '\\') { i += 1; continue; }
+      if (ch === ']') { mode = 're'; }
+      continue;
+    }
+    if (mode === 'lc') {
+      if (ch === '\n') { mode = 'code'; }
+      continue;
+    }
+    if (mode === 'bc') {
+      if (ch === '*' && next === '/') { mode = 'code'; i += 1; }
+      continue;
+    }
+  }
+  const tail = body.slice(start);
+  if (tail.trim().length > 0 || args.length > 0) {
+    args.push(tail);
+  }
+  return args.map((arg) => arg.trim()).filter((arg) => arg.length > 0);
+}
+
 function rewriteMigrationImports(projectRoot, matches, compatPath) {
   const rewrittenFiles = [];
   let rewrittenImports = 0;
@@ -498,6 +869,12 @@ function detectMigrationImports(sourceText) {
   if (hasModuleReference(sourceText, '@testing-library/react')) {
     matches.push('@testing-library/react');
   }
+  if (hasModuleReference(sourceText, 'node:test')) {
+    matches.push('node:test');
+  }
+  if (hasModuleReference(sourceText, 'node:assert/strict') || hasModuleReference(sourceText, 'node:assert')) {
+    matches.push('node:assert');
+  }
   return matches;
 }
 

package/src/module-loader.js

@@ -1,8 +1,11 @@
 const fs = require('fs');
 const path = require('path');
 const Module = require('module');
+const { pathToFileURL } = require('url');
 
 const SUPPORTED_SOURCE_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx'];
+const ESM_LOAD_EXTENSIONS = new Set(['.mjs']);
+const SUPPORTED_TEST_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'];
 const RESOLVABLE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.json'];
 const STYLE_IMPORT_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less', '.styl', '.pcss']);
 const ASSET_IMPORT_EXTENSIONS = new Set([
@@ -145,11 +148,17 @@ function createModuleLoader(options = {}) {
   };
 
   return {
-    loadFile(filePath) {
+    async loadFile(filePath) {
       const resolvedPath = path.resolve(filePath);
       const realPath = safeRealpath(resolvedPath);
       delete require.cache[resolvedPath];
       delete require.cache[realPath];
+
+      if (shouldLoadAsEsm(realPath, projectRoot, packageTypeCache)) {
+        const url = `${pathToFileURL(realPath).href}?themis=${Date.now()}`;
+        return import(url);
+      }
+
       return require(realPath);
     },
     restore() {
@@ -289,6 +298,20 @@ function shouldTranspileFile(filename, projectRoot, packageTypeCache) {
   return findNearestPackageType(filename, projectRoot, packageTypeCache) === 'module';
 }
 
+function shouldLoadAsEsm(filename, projectRoot, packageTypeCache) {
+  const extension = path.extname(filename).toLowerCase();
+
+  if (ESM_LOAD_EXTENSIONS.has(extension)) {
+    return true;
+  }
+
+  if (extension !== '.js') {
+    return false;
+  }
+
+  return findNearestPackageType(filename, projectRoot, packageTypeCache) === 'module';
+}
+
 function delegateToOriginalLoader(originalLoaders, extension, testModule, filename) {
   const loader = originalLoaders.get(extension) || originalLoaders.get('.js');
   if (!loader) {
@@ -539,7 +562,7 @@ function shouldRejectUnsupportedProjectImport(resolvedRequest, projectRoot) {
     return false;
   }
 
-  return !SUPPORTED_SOURCE_EXTENSIONS.includes(extension)
+  return !SUPPORTED_TEST_EXTENSIONS.includes(extension)
     && extension !== '.json'
     && !STYLE_IMPORT_EXTENSIONS.has(extension)
     && !ASSET_IMPORT_EXTENSIONS.has(extension);

package/src/process-child.js

@@ -0,0 +1,25 @@
+const { collectAndRun } = require('./runtime');
+
+process.once('message', async (workerData) => {
+  try {
+    const result = await collectAndRun(workerData.file, {
+      match: workerData.match,
+      allowedFullNames: workerData.allowedFullNames,
+      noMemes: workerData.noMemes,
+      updateContracts: workerData.updateContracts,
+      cwd: workerData.cwd,
+      environment: workerData.environment,
+      setupFiles: workerData.setupFiles,
+      tsconfigPath: workerData.tsconfigPath
+    });
+    process.send({ ok: true, result }, () => process.exit(0));
+  } catch (error) {
+    process.send({
+      ok: false,
+      error: {
+        message: String((error && error.message) || error),
+        stack: String((error && error.stack) || error)
+      }
+    }, () => process.exit(0));
+  }
+});

package/src/runner.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { Worker } = require('worker_threads');
+const { fork } = require('child_process');
 const { performance } = require('perf_hooks');
 const { collectAndRun } = require('./runtime');
 
@@ -13,7 +14,9 @@ async function runTests(files, options = {}) {
   const maxWorkers = isolation === 'in-process' ? 1 : resolveMaxWorkers(options.maxWorkers);
   const fileResults = isolation === 'in-process'
     ? await runFilesInProcess(files, options)
-    : await runFilesInWorkers(files, options);
+    : isolation === 'process'
+      ? await runFilesInChildProcesses(files, options)
+      : await runFilesInWorkers(files, options);
 
   fileResults.sort((a, b) => a.file.localeCompare(b.file));
 
@@ -72,6 +75,111 @@ async function runNext(queue, fileResults, options) {
   }
 }
 
+async function runFilesInChildProcesses(files, options) {
+  const queue = [...files];
+  const lanes = [];
+  const fileResults = [];
+
+  for (let i = 0; i < Math.min(resolveMaxWorkers(options.maxWorkers), files.length); i += 1) {
+    lanes.push(runNextChildProcess(queue, fileResults, options));
+  }
+
+  await Promise.all(lanes);
+  return fileResults;
+}
+
+async function runNextChildProcess(queue, fileResults, options) {
+  while (queue.length > 0) {
+    const file = queue.shift();
+    if (!file) {
+      return;
+    }
+    const result = await runFileInChildProcess(file, options);
+    fileResults.push(result);
+  }
+}
+
+function runFileInChildProcess(file, options = {}) {
+  return new Promise((resolve) => {
+    const child = fork(path.join(__dirname, 'process-child.js'), [], {
+      cwd: options.cwd || process.cwd(),
+      stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+      env: { ...process.env }
+    });
+
+    let settled = false;
+
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      try { child.kill(); } catch { /* already exited */ }
+      resolve(result);
+    };
+
+    child.once('message', (payload) => {
+      if (payload && payload.ok) {
+        settle(payload.result);
+      } else {
+        settle({
+          file,
+          tests: [{
+            name: 'process',
+            fullName: `${file} process`,
+            status: 'failed',
+            durationMs: 0,
+            error: (payload && payload.error) || { message: 'process child returned no result', stack: '' }
+          }]
+        });
+      }
+    });
+
+    child.once('error', (error) => {
+      settle({
+        file,
+        tests: [{
+          name: 'process',
+          fullName: `${file} process`,
+          status: 'failed',
+          durationMs: 0,
+          error: {
+            message: String(error.message || error),
+            stack: String(error.stack || error)
+          }
+        }]
+      });
+    });
+
+    child.once('exit', (code) => {
+      if (settled) return;
+      const message = code === 0
+        ? 'Child process exited before reporting test results'
+        : `Child process exited with code ${code} before reporting test results`;
+      settle({
+        file,
+        tests: [{
+          name: 'process',
+          fullName: `${file} process`,
+          status: 'failed',
+          durationMs: 0,
+          error: { message, stack: message }
+        }]
+      });
+    });
+
+    child.send({
+      file,
+      match: options.match || null,
+      allowedFullNames: Array.isArray(options.allowedFullNames) ? options.allowedFullNames : null,
+      noMemes: Boolean(options.noMemes),
+      updateContracts: Boolean(options.updateContracts),
+      cwd: options.cwd || process.cwd(),
+      environment: options.environment || 'node',
+      setupFiles: Array.isArray(options.setupFiles) ? options.setupFiles : [],
+      tsconfigPath: options.tsconfigPath === undefined ? undefined : options.tsconfigPath
+    });
+  });
+}
+
 function runFileInWorker(file, options = {}) {
   return new Promise((resolve) => {
     const worker = new Worker(path.join(__dirname, 'worker.js'), {
@@ -214,7 +322,9 @@ function clearRunCache() {
 }
 
 function resolveIsolationMode(options = {}) {
-  return options.isolation === 'in-process' ? 'in-process' : 'worker';
+  if (options.isolation === 'in-process') return 'in-process';
+  if (options.isolation === 'process') return 'process';
+  return 'worker';
 }
 
 function resolveMaxWorkers(value) {

package/src/runtime.js

@@ -36,7 +36,7 @@ function createSuite(name, parent = null) {
   };
 }
 
-function collectAndRun(filePath, options = {}) {
+async function collectAndRun(filePath, options = {}) {
   const root = createSuite('__root__', null);
   let currentSuite = root;
   const projectRoot = path.resolve(options.cwd || process.cwd());
@@ -92,9 +92,9 @@ function collectAndRun(filePath, options = {}) {
   let loadError = null;
   try {
     for (const setupFile of setupFiles) {
-      moduleLoader.loadFile(setupFile);
+      await moduleLoader.loadFile(setupFile);
     }
-    moduleLoader.loadFile(filePath);
+    await moduleLoader.loadFile(filePath);
   } catch (error) {
     loadError = normalizeError(error);
   }

package/templates/AGENTS.themis.md

@@ -16,8 +16,10 @@ Use `@vitronai/themis` as this repository's unit test framework.
 
 - If this repo currently uses Jest, migrate with `npx themis migrate jest`.
 - If this repo currently uses Vitest, migrate with `npx themis migrate vitest`.
-- Use `--rewrite-imports` to point compatible imports at `themis.compat.js`.
-- Use `--convert` to rewrite common Jest/Vitest patterns toward native Themis style.
+- If this repo currently uses `node:test` + `node:assert`, migrate with `npx themis migrate node --convert`.
+- Use `--rewrite-imports` to point compatible imports at `themis.compat.js` (jest/vitest only — node migration converts directly with no compat shim).
+- Use `--convert` to rewrite common framework patterns toward native Themis style.
+- For migrated `node:test` suites that mutate `process.env`/`process.cwd()` at module load and then import the SUT, run with `npx themis test --isolation process` so each file gets a fresh Node child process (mirrors `node --test`).
 
 ## Test Authoring
 

package/templates/CLAUDE.themis.md

@@ -12,6 +12,8 @@ This repository uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitrona
 - Re-run only failed tests: `npx themis test --rerun-failed`
 - Migrate from Jest: `npx themis migrate jest` then `--rewrite-imports` then `--convert`
 - Migrate from Vitest: `npx themis migrate vitest` then `--rewrite-imports` then `--convert`
+- Migrate from `node:test`: `npx themis migrate node --convert`
+- Run with per-file process isolation (mirrors `node --test`): `npx themis test --isolation process`
 
 ## When You Are Asked To Add Or Fix Tests
 
@@ -20,13 +22,14 @@ This repository uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitrona
 3. Run `npx themis test --reporter agent` and read the JSON output. Failure clusters and repair hints are structured — use them to drive your fix loop instead of re-reading raw stack traces.
 4. After fixing, re-run only the failing tests with `npx themis test --rerun-failed` before running the full suite.
 
-## When You Are Asked To Migrate From Jest Or Vitest
+## When You Are Asked To Migrate From Jest, Vitest, Or node:test
 
-1. Run `npx themis migrate jest` (or `vitest`) — this scaffolds compatibility, no rewrites yet.
-2. Run `npx themis migrate jest --rewrite-imports` to point imports at `themis.compat.js`.
-3. Run `npx themis migrate jest --convert` to apply codemods toward native Themis style.
-4. Run `npx themis migrate jest --assist` to get a structured findings report of files that still need manual follow-up. The report path is printed at the end of the command — read it before guessing what to fix.
+1. Run `npx themis migrate <jest|vitest|node>` — this scaffolds compatibility (jest/vitest) or detects targets (node), no rewrites yet.
+2. Run `npx themis migrate <jest|vitest> --rewrite-imports` to point imports at `themis.compat.js`. Skip this for `node` source — node migration converts directly with no compat shim.
+3. Run `npx themis migrate <source> --convert` to apply codemods toward native Themis style.
+4. Run `npx themis migrate <source> --assist` to get a structured findings report of files that still need manual follow-up. The report path is printed at the end of the command — read it before guessing what to fix.
 5. Run `npx themis test` after each step. Migration is incremental on purpose; do not try to convert the whole suite in one pass.
+6. For migrated `node:test` suites that mutate `process.env`/`process.cwd()` at module load (a common pattern when redirecting `os.homedir()` to a temp dir before importing the SUT), pair test runs with `npx themis test --isolation process` so each file gets a fresh Node child process. The default `worker` mode shares process-state across files and will surface as cross-file leakage.
 
 ## Things To Avoid
 

package/templates/claude-commands/themis-migrate.md

@@ -1,10 +1,12 @@
 ---
-description: Migrate this repo from Jest or Vitest to Themis
+description: Migrate this repo from Jest, Vitest, or node:test to Themis
 ---
 
-Migrate this repository from Jest or Vitest to Themis. If the user did not say which, detect it: check `package.json` devDependencies for `jest` or `vitest`.
+Migrate this repository from Jest, Vitest, or `node:test` to Themis. If the user did not say which, detect it:
+- `node:test`: grep `bridge-tests/`, `tests/`, or `test/` for `import .* from 'node:test'`. If matches, source is `node`.
+- Otherwise check `package.json` devDependencies for `jest` or `vitest`.
 
-Run the four steps in order, and run `npx themis test` between each step to confirm the suite is still green:
+For Jest or Vitest, run the four steps in order, and run `npx themis test` between each:
 
 ```bash
 npx themis migrate <jest|vitest>                    # 1. scaffold compatibility
@@ -13,6 +15,15 @@ npx themis migrate <jest|vitest> --convert          # 3. codemod to native style
 npx themis migrate <jest|vitest> --assist           # 4. emit structured findings
 ```
 
-After step 4, read the findings report (its path is printed at the end of the command) and walk through any items it flags for manual follow-up. Do not guess at fixes — the report tells you what needs human attention and why.
+For `node:test`, the codemod converts directly with no compat shim. Run `--convert` then `--assist` (no `--rewrite-imports`):
+
+```bash
+npx themis migrate node --convert                   # 1. drop node:test/node:assert imports + rewrite asserts
+npx themis migrate node --assist                    # 2. emit structured findings
+```
+
+If the migrated `node:test` suite mutates `process.env` or `process.cwd()` at module load (a common pattern for redirecting `os.homedir()` to a temp dir before importing the SUT), run tests with per-file process isolation: `npx themis test --isolation process`. This spawns a fresh Node child process per file (mirrors `node --test`); the default `worker` mode freezes `os.homedir()` and shares the ESM module cache across files.
+
+After the assist step, read the findings report (its path is printed at the end of the command) and walk through any items it flags for manual follow-up. Do not guess at fixes — the report tells you what needs human attention and why.
 
 If the user passed extra arguments, forward them: $ARGUMENTS

package/templates/claude-skill/SKILL.md

@@ -64,7 +64,7 @@ npx themis generate src/auth    # narrower target
 
 Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX sources) or `.generated.test.js` (JS/JSX sources). Treat them as Themis-managed — extend rather than rewrite.
 
-## How To Migrate From Jest Or Vitest
+## How To Migrate From Jest, Vitest, Or node:test
 
 Migration is incremental on purpose. Run the steps in order and `npx themis test` between each:
 
@@ -75,7 +75,11 @@ npx themis migrate jest --convert              # 3. apply codemods to native The
 npx themis migrate jest --assist               # 4. emit structured findings JSON for manual follow-ups
 ```
 
-Same flags work for `vitest`. **Read the `--assist` findings report before guessing what to fix manually** — its path is printed at the end of the command and the schema is at `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`.
+Same flags work for `vitest`. For `node:test` + `node:assert/strict` suites, use `npx themis migrate node --convert` (the node source has no compat shim — conversion is direct, so step 2 is skipped). **Read the `--assist` findings report before guessing what to fix manually** — its path is printed at the end of the command and the schema is at `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`.
+
+## When To Use --isolation process
+
+Default isolation is `worker` (worker thread per file). For migrated `node:test` suites — or any suite that mutates `process.env`/`process.cwd()` at module load and then imports the SUT — use `npx themis test --isolation process`. This spawns a fresh Node child process per file (mirrors `node --test`). Worker mode freezes `os.homedir()` at worker startup and shares the ESM module cache across files; `--isolation process` fixes both.
 
 ## Things To Avoid
 

package/templates/cursorrules.themis.md

@@ -12,6 +12,8 @@ This repository uses `@vitronai/themis` as its unit test framework. Themis is a
 - Re-run only failed tests: `npx themis test --rerun-failed`
 - Migrate from Jest: `npx themis migrate jest` then `--rewrite-imports` then `--convert`
 - Migrate from Vitest: `npx themis migrate vitest` then `--rewrite-imports` then `--convert`
+- Migrate from `node:test`: `npx themis migrate node --convert`
+- Run with per-file process isolation (mirrors `node --test`, needed when tests mutate `process.env` at module load): `npx themis test --isolation process`
 
 ## When Adding Or Fixing Tests
 

package/themis.ai.json

@@ -10,7 +10,13 @@
   "testAgent": "npx themis test --reporter agent",
   "migrate": {
     "jest": "npx themis migrate jest --rewrite-imports --convert",
-    "vitest": "npx themis migrate vitest --rewrite-imports --convert"
+    "vitest": "npx themis migrate vitest --rewrite-imports --convert",
+    "node": "npx themis migrate node --convert"
+  },
+  "isolation": {
+    "worker": "Default. One worker thread per file. Fast. Tests must not depend on per-file process isolation.",
+    "in-process": "All files in the parent process, sequential. Fastest reruns; shares ESM module cache and process state across files.",
+    "process": "child_process.fork per file (mirrors `node --test`). Use when tests mutate process.env, process.cwd, or rely on os.homedir() reflecting test setup."
   },
   "agentIntegrations": {
     "claudeCode": {
@@ -28,6 +34,8 @@
     "Treat Themis as the repo's unit test framework for Node.js and TypeScript projects.",
     "Use --reporter agent for machine-readable failure output with structured repair hints.",
     "Do not default to Jest or Vitest when Themis is already selected.",
-    "Do not create ad hoc tests/*.cjs setup files for common asset or style imports."
+    "Do not create ad hoc tests/*.cjs setup files for common asset or style imports.",
+    "ESM test files (.mjs, .cjs, .js in type:module packages) are supported natively via dynamic import().",
+    "If a test mutates process.env/process.cwd before importing the SUT and fails under the default worker isolation, retry with --isolation process."
   ]
 }