@capybara-hq/testing 0.1.0-rc.0 → 0.1.0-rc.2

package/README.md

@@ -14,7 +14,8 @@ npm install --save-dev @capybara-hq/testing
   platform), live in
   `fixtures/extensions/<name>` in the plugin pack layout; `packFixture(name, outDir)` packs one
   into a plugin tgz (needs the optional peer `@capybara-hq/plugin-tools` installed), `fakeExtensionEntry(name)` gives its
-  `src/index.ts` for loading by path in a workspace. A test that edits a fake before packing
+  `src/index.ts` for loading by path (in `createDualReplicaHarness` wherever this package is
+  installed; in an in-process kernel when vitest transforms the kernel). A test that edits a fake before packing
   (bump the version, add a migration) packs a copy of `fakeExtensionDir(name)` instead, e.g. with
   the kernel tests' `packPluginDir(fakeExtensionDir("fake-tools-ui"), edit)`, which copies the
   directory to a temp dir and runs `edit` on the copy.
@@ -24,6 +25,11 @@ npm install --save-dev @capybara-hq/testing
   `openSse`, `truncateTables`, `pidOwningLocalPort`, and the kernel's `createDb` / `kernelDb`. With
   these a plugin's tests import only the SDK and this package (plus model-fake, the scripted model
   provider, to drive agent runs).
+- `createDualReplicaHarness` starts each replica as a plain `node` child process. When an entry of
+  `extensions` is a TypeScript file (the plugin under test's `src/index.ts`, whose imports say
+  `./x.js`, or `fakeExtensionEntry(name)`), the replicas run under tsx, a dependency of this
+  package, resolved from it; no `NODE_OPTIONS` loader is needed. Packed plugins and package names
+  load in plain Node, as in production.
 - How extension tests are written: "Test template (dual-replica)" in
   [.agents/skills/writing-extensions](https://github.com/capybara-hq/core/tree/main/.agents/skills/writing-extensions).
 - The repository: [capybara-hq/core](https://github.com/capybara-hq/core).

package/dist/dual-replica.d.ts

@@ -1,21 +1,27 @@
 import type { BootstrapManifest } from "@capybara-hq/plugin-sdk";
 /** 双副本测试工具的选项。 */
 export interface DualReplicaOptions {
-    /** Extensions to load (absolute paths, file URLs, or package names resolved from `resolveFrom`). */
+    /**
+     * Extensions to load (absolute paths, file URLs, or package names resolved from `resolveFrom`).
+     * A TypeScript entry (the plugin under test's `src/index.ts`, `fakeExtensionEntry(...)`) makes
+     * the replicas run under tsx, which this package ships ({@link needsTypeScript}), also when
+     * this package is installed from npm; nothing needs to be set in `NODE_OPTIONS`.
+     */
     extensions: string[];
     /** 解析裸包名插件的目录，默认调用方的 `process.cwd()`（与 `createKernel` 的 resolveFrom 同义）。 */
     resolveFrom?: string;
     /** 部署级插件配置，按插件名索引。 */
     extensionConfig?: Record<string, unknown>;
     /**
-     * The bootstrap step (package ecosystem spec §7): every replica's kernel gets `bootstrapDir: dir`
+     * The bootstrap step (package ecosystem spec §7): every replica's kernel gets `bootstrap: { dir }`
      * and `bootstrapManifest: manifest`, so the replicas run it at start (once across them, under the
-     * advisory lock) before loading extensions, as a deployment without an init container does. `dir`
-     * holds the packages the manifest pins (`<name>-<version>.tgz`); build both with the kernel
-     * tests' `bootstrapFixture` helper (it packs plugin directories with `pnpm pack-plugin`).
+     * advisory lock) before loading extensions, as `capybara start` does. `dir` is the optional
+     * offline directory (its `*.tgz` files are matched to the entries by sha512); the other entries
+     * are downloaded from `packages.npmRegistry` (set it in `config`, e.g. to a
+     * `startFakeNpmRegistry`). Build both with the kernel tests' `bootstrapFixture` helper.
      */
     bootstrap?: {
-        dir: string;
+        dir?: string;
         manifest: BootstrapManifest;
     };
     /**
@@ -103,10 +109,26 @@ export interface Harness {
     stop(): Promise<void>;
 }
 /**
- * 子进程的 node 参数。`.ts` 的 runner（monorepo / 开发态）需要 tsx 与源码导出条件；
- * 编译后的 `.js` runner（发布态）直接用 node，不依赖 tsx。
+ * tsx's ESM loader, resolved from this package (tsx is one of its dependencies), as a URL for
+ * `--import`. Absolute, so it never depends on what the replica's cwd or the caller's repository
+ * has installed.
+ */
+export declare const TSX_LOADER: string;
+/**
+ * Whether a replica needs a TypeScript loader for `extensions`: true when one is a TypeScript file,
+ * such as the plugin under test by path (`plugins/<name>/src/index.ts`, whose imports say `./x.js`)
+ * or a fake extension of this package (`fakeExtensionEntry`). Plain Node strips types, but does
+ * not map `./x.js` to `./x.ts` and refuses to strip types under `node_modules`, where this package
+ * and its fakes live once installed from npm.
+ */
+export declare function needsTypeScript(extensions: readonly string[]): boolean;
+/**
+ * The replica's node arguments. A `.ts` runner (this repository, source) always runs under tsx
+ * with the source export condition. A compiled `.js` runner (installed from npm) gets tsx only when
+ * `typescript` is set ({@link needsTypeScript}): extensions loaded as packed plugins or by package
+ * name then run in plain Node, as in production, so a packaging bug is not hidden by the loader.
  */
-export declare function runnerArgv(runnerPath: string): string[];
+export declare function runnerArgv(runnerPath: string, typescript?: boolean): string[];
 /**
  * 子进程的环境变量。`.ts` 的 runner 额外设置 `TSX_TSCONFIG_PATH` 指向仓库的 tsconfig.base.json：
  * tsx 只认子进程 cwd 下（且 include 覆盖到的）tsconfig，否则内核源码丢掉 experimentalDecorators，

package/dist/dual-replica.js

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
+import { createRequire } from "node:module";
 import { extname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { createFreshDatabase, sharedPgAdminUrl, startPostgresContainer, startTestRedis, } from "./containers.js";
 /** 副本在响应头里标明自己的序号（runner 把 `http.replicaId` 设为 `"0"` / `"1"`）。 */
 export const REPLICA_HEADER = "x-capybara-replica";
@@ -22,13 +23,34 @@ const STDERR_TAIL = 4000;
 /** runner 与本文件同目录；源码下是 .ts，编译后是 .js。 */
 const runnerPath = fileURLToPath(new URL(`./replica-runner${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
 /**
- * 子进程的 node 参数。`.ts` 的 runner（monorepo / 开发态）需要 tsx 与源码导出条件；
- * 编译后的 `.js` runner（发布态）直接用 node，不依赖 tsx。
+ * tsx's ESM loader, resolved from this package (tsx is one of its dependencies), as a URL for
+ * `--import`. Absolute, so it never depends on what the replica's cwd or the caller's repository
+ * has installed.
  */
-export function runnerArgv(runnerPath) {
-    return runnerPath.endsWith(".ts")
-        ? ["--import", "tsx", "--conditions=@capybara-hq/source", runnerPath]
-        : [runnerPath];
+export const TSX_LOADER = pathToFileURL(createRequire(import.meta.url).resolve("tsx")).href;
+/** An extension entry that is a TypeScript file (a path or a file URL), as opposed to a package. */
+const TS_ENTRY = /\.[cm]?tsx?$/i;
+/**
+ * Whether a replica needs a TypeScript loader for `extensions`: true when one is a TypeScript file,
+ * such as the plugin under test by path (`plugins/<name>/src/index.ts`, whose imports say `./x.js`)
+ * or a fake extension of this package (`fakeExtensionEntry`). Plain Node strips types, but does
+ * not map `./x.js` to `./x.ts` and refuses to strip types under `node_modules`, where this package
+ * and its fakes live once installed from npm.
+ */
+export function needsTypeScript(extensions) {
+    return extensions.some((e) => TS_ENTRY.test(e));
+}
+/**
+ * The replica's node arguments. A `.ts` runner (this repository, source) always runs under tsx
+ * with the source export condition. A compiled `.js` runner (installed from npm) gets tsx only when
+ * `typescript` is set ({@link needsTypeScript}): extensions loaded as packed plugins or by package
+ * name then run in plain Node, as in production, so a packaging bug is not hidden by the loader.
+ */
+export function runnerArgv(runnerPath, typescript = false) {
+    if (runnerPath.endsWith(".ts")) {
+        return ["--import", TSX_LOADER, "--conditions=@capybara-hq/source", runnerPath];
+    }
+    return typescript ? ["--import", TSX_LOADER, runnerPath] : [runnerPath];
 }
 /** 仓库根的 tsconfig.base.json（仅 monorepo 源码态存在）。 */
 const REPO_TSCONFIG = fileURLToPath(new URL("../../../tsconfig.base.json", import.meta.url));
@@ -41,8 +63,8 @@ export function runnerEnv(runnerPath, env = process.env) {
     return runnerPath.endsWith(".ts") ? { ...env, TSX_TSCONFIG_PATH: REPO_TSCONFIG } : env;
 }
 /** 启动一个副本子进程，等它通过 IPC 报告 ready。失败时抛出带 输出尾部的错误（不含配置）。 */
-async function startReplica(config, index) {
-    const child = spawn(process.execPath, runnerArgv(runnerPath), {
+async function startReplica(config, index, typescript) {
+    const child = spawn(process.execPath, runnerArgv(runnerPath, typescript), {
         stdio: ["ignore", "pipe", "pipe", "ipc"],
         env: runnerEnv(runnerPath),
         cwd: fileURLToPath(new URL("..", import.meta.url)),
@@ -145,7 +167,9 @@ export async function createDualReplicaHarness(opts) {
             masterKey: randomBytes(32).toString("base64"),
             extensions: opts.extensions,
             ...(opts.bootstrap !== undefined && {
-                bootstrapDir: resolve(opts.bootstrap.dir),
+                bootstrap: {
+                    ...(opts.bootstrap.dir !== undefined && { dir: resolve(opts.bootstrap.dir) }),
+                },
                 bootstrapManifest: opts.bootstrap.manifest,
             }),
             // 副本进程的 cwd 不是调用方的 cwd，相对路径必须先按调用方 cwd 绝对化再经 IPC 传过去
@@ -154,7 +178,8 @@ export async function createDualReplicaHarness(opts) {
             overrides: opts.config ?? {},
         };
         const roles = opts.roles ?? [ALL_ROLES, ALL_ROLES];
-        const started = await Promise.allSettled(roles.map((r, i) => startReplica({ ...config, roles: [...r] }, i)));
+        const typescript = needsTypeScript(opts.extensions);
+        const started = await Promise.allSettled(roles.map((r, i) => startReplica({ ...config, roles: [...r] }, i, typescript)));
         for (const s of started)
             if (s.status === "fulfilled")
                 runners.push(s.value.runner);
@@ -210,7 +235,7 @@ export async function createDualReplicaHarness(opts) {
                     if (stopPromise)
                         throw new Error("harness is stopped");
                     const index = handles.length;
-                    const started = await startReplica({ ...config, roles: [...extraRoles] }, index);
+                    const started = await startReplica({ ...config, roles: [...extraRoles] }, index, typescript);
                     runners.push(started.runner);
                     // A stop() that began while this replica was starting must not leave it running
                     if (stopPromise) {

package/dist/fake-e2b.d.ts

@@ -1,5 +1,6 @@
 /**
- * 可编程的假 E2B（`plugins/sandbox-e2b` 测试用），协议按 `e2b` JS SDK 2.58.0 与 E2B 文档（2026-10-21 核实）：
+ * A programmable fake E2B (for the tests of the sandbox-e2b plugin in capybara-hq/plugins), following
+ * the `e2b` JS SDK 2.58.0 and the E2B docs (checked 2026-10-21):
  *
  * - **控制面 API**（请求头 `X-API-KEY`，不符 → 401 `{code, message}`）：
  *   `POST /v2/sandboxes`（建沙箱，回 201 `{sandboxID, templateID, envdVersion, envdAccessToken, domain}`）、

package/dist/fixtures.d.ts

@@ -25,9 +25,11 @@ export type FakeExtensionName = (typeof FAKE_EXTENSIONS)[number];
 export declare function fakeExtensionDir(name: FakeExtensionName): string;
 /**
  * The extension entry `src/index.ts` of a fake, for kernel configs that load extensions by path
- * (`extensions: [fakeExtensionEntry("fake-connector")]`). Loading TypeScript by path works in this
- * repository's tests; a consumer that installs this package from npm should pack the fake with
- * {@link packFixture} instead (Node does not strip types under node_modules).
+ * (`extensions: [fakeExtensionEntry("fake-connector")]`). `createDualReplicaHarness` loads it in
+ * its replicas wherever this package is installed (they run under tsx for TypeScript entries). An
+ * in-process kernel under vitest loads it when vitest transforms the kernel (in this repository, or
+ * with the core packages inlined: `server.deps.inline`); elsewhere, pack the fake with
+ * {@link packFixture} (Node does not strip types under node_modules).
  */
 export declare function fakeExtensionEntry(name: FakeExtensionName): string;
 /** The result of {@link packFixture}. */

package/dist/fixtures.js

@@ -42,9 +42,11 @@ export function fakeExtensionDir(name) {
 }
 /**
  * The extension entry `src/index.ts` of a fake, for kernel configs that load extensions by path
- * (`extensions: [fakeExtensionEntry("fake-connector")]`). Loading TypeScript by path works in this
- * repository's tests; a consumer that installs this package from npm should pack the fake with
- * {@link packFixture} instead (Node does not strip types under node_modules).
+ * (`extensions: [fakeExtensionEntry("fake-connector")]`). `createDualReplicaHarness` loads it in
+ * its replicas wherever this package is installed (they run under tsx for TypeScript entries). An
+ * in-process kernel under vitest loads it when vitest transforms the kernel (in this repository, or
+ * with the core packages inlined: `server.deps.inline`); elsewhere, pack the fake with
+ * {@link packFixture} (Node does not strip types under node_modules).
  */
 export function fakeExtensionEntry(name) {
     return join(FIXTURES_DIR, name, "src/index.ts");

package/dist/replica-runner.js

@@ -29,7 +29,7 @@ async function startKernel(c) {
     const config = KernelConfigSchema.parse(deepMerge(base, c.overrides));
     kernel = await createKernel(config, {
         resolveFrom: c.resolveFrom,
-        ...(c.bootstrapDir !== undefined && { bootstrapDir: c.bootstrapDir }),
+        ...(c.bootstrap !== undefined && { bootstrap: c.bootstrap }),
         ...(c.bootstrapManifest !== undefined && { bootstrapManifest: c.bootstrapManifest }),
     });
     await kernel.start();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/testing",
-  "version": "0.1.0-rc.0",
+  "version": "0.1.0-rc.2",
   "description": "Test helpers for Capybara: test containers, dual-replica harness and fake third-party servers",
   "license": "Apache-2.0",
   "repository": {
@@ -44,9 +44,10 @@
     "pg": "^8.23.1",
     "protobufjs": "^7.5.4",
     "testcontainers": "^12.2.1",
+    "tsx": "^4.23.15",
     "ws": "^8.22.0",
     "zod": "^4.6.7",
-    "@capybara-hq/kernel": "^0.1.0-rc.0"
+    "@capybara-hq/kernel": "^0.1.0-rc.1"
   },
   "devDependencies": {
     "@types/pg": "^8.23.1",
@@ -55,8 +56,8 @@
   },
   "peerDependencies": {
     "vitest": "^5.0.5",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0",
-    "@capybara-hq/plugin-tools": "^0.1.0-rc.0"
+    "@capybara-hq/plugin-tools": "^0.1.0-rc.2",
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.0"
   },
   "peerDependenciesMeta": {
     "@capybara-hq/plugin-tools": {