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

package/dist/dual-replica.d.ts

@@ -8,7 +8,10 @@ export interface DualReplicaOptions {
      * this package is installed from npm; nothing needs to be set in `NODE_OPTIONS`.
      */
     extensions: string[];
-    /** 解析裸包名插件的目录，默认调用方的 `process.cwd()`（与 `createKernel` 的 resolveFrom 同义）。 */
+    /**
+     * Where extensions named by package resolve from; default the caller's `process.cwd()` (the
+     * `resolveFrom` of `createKernelApp`).
+     */
     resolveFrom?: string;
     /** 部署级插件配置，按插件名索引。 */
     extensionConfig?: Record<string, unknown>;

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * package and the SDK: the database helpers and types, and model-visible texts, queue names and
  * keys the kernel owns (assert on them instead of copying their values).
  */
-export { type ConversationEvent, createDb, gatewayReplicasKey, type Kernel, type KernelConfig, type KernelDb, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
+export { type ConversationEvent, createDb, gatewayReplicasKey, type KernelConfig, type KernelSchemaDb, kernelDb, MAINTENANCE_QUEUE_NAME, runJobId, SANDBOX_LOCK_TTL_MS, SANDBOX_RECREATED_NOTICE, SANDBOX_STARTED_NOTICE, SANDBOX_SUSPEND_JOB, UNKNOWN_RESULT_TEXT, } from "@capybara-hq/kernel";
 export { createFreshDatabase, startTestPostgres, startTestRedis, startTestS3, TEST_S3_IMAGE, type TestContainer, type TestS3, } from "./containers.js";
 export { createDualReplicaHarness, type DualReplicaOptions, type ExtraReplicaHandle, type Harness, REPLICA_HEADER, type ReplicaHandle, type ReplicaResponse, replicaOf, } from "./dual-replica.js";
 export { assertExtensionSecretsReachable, extensionDeploymentSecretValues, } from "./extension-config.js";
@@ -19,7 +19,7 @@ export { type FakeOAuthClient, type FakeOAuthServer, type FakeOAuthServerOptions
 export { defaultFakeOpenApiSpec, type FakeOpenApiRequest, type FakeOpenApiServer, type FakeOpenApiServerOptions, type FakePet, startFakeOpenApiServer, } from "./fake-openapi-server.js";
 export { type FakeSlackAck, type FakeSlackCall, type FakeSlackFailure, type FakeSlackMessage, type FakeSlackOptions, type FakeSlackServer, type FakeSlackUser, findSlackButton, signSlackWebhook, slackBlockAction, slackDmEvent, slackEventCallback, slackInteractiveForm, slackMentionEvent, startFakeSlack, } from "./fake-slack.js";
 export { FAKE_EXTENSIONS, type FakeExtensionName, fakeExtensionDir, fakeExtensionEntry, type PackedFixture, packFixture, } from "./fixtures.js";
-export { cardRecorded, cookieRequest, createAgent, createConversation, createLocalAccount, createOrg, eventsOf, joinOrg, type KernelRequest, type KernelRequestOptions, type KernelResponse, login, pidOwningLocalPort, postMessage, sleep, startTestKernel, TEST_PASSWORD, testKernelConfig, truncateTables, waitFor, waitForEvent, waitForTerminal, } from "./kernel-helpers.js";
+export { cardRecorded, cookieRequest, createAgent, createConversation, createLocalAccount, createOrg, eventsOf, joinOrg, type KernelApp, type KernelRequest, type KernelRequestOptions, type KernelResponse, login, pidOwningLocalPort, postMessage, sleep, startTestKernel, TEST_PASSWORD, type TestKernel, testKernelConfig, truncateTables, waitFor, waitForEvent, waitForTerminal, } from "./kernel-helpers.js";
 export { isPngBase64, pdfBase64, pdfSampleWord, redPngBase64, solidPngBase64, } from "./media-samples.js";
 export { type ConformanceTarget, checkDeclaredParameters, describeModelProviderConformance, MEDIA_SAMPLES, thinkingReplayParams, } from "./model-conformance.js";
 export { openSse, type SseClient, type SseMessage } from "./sse.js";

package/dist/kernel-helpers.d.ts

@@ -1,4 +1,4 @@
-import { type ConversationEvent, type Kernel, type KernelConfig, type KernelDb, type KernelHttp, type LogLevel } from "@capybara-hq/kernel";
+import { type ConversationEvent, type KernelConfig, type KernelHttp, type KernelSchemaDb, type LogLevel, startKernelApp } from "@capybara-hq/kernel";
 import { type Kysely } from "kysely";
 /**
  * Helpers for extension tests that run a real kernel: in process (`startTestKernel` +
@@ -33,11 +33,32 @@ export declare function testKernelConfig(urls: {
  * it before creating anything.
  */
 export declare function assertOfflineOfficialMarketplace(config: KernelConfig, allow?: boolean): void;
+/** The kernel's Nest application (what `createKernelApp` / `startKernelApp` return). */
+export type KernelApp = Awaited<ReturnType<typeof startKernelApp>>;
+/** A running in-process kernel ({@link startTestKernel}). */
+export interface TestKernel {
+    /**
+     * The kernel's Nest application. Core's own tests reach a kernel service with `app.get(Class)`;
+     * a plugin test cannot import kernel classes (`plugin-test-imports`), so it drives the kernel
+     * through `http` and the helpers of this package.
+     */
+    readonly app: KernelApp;
+    /** In-process HTTP: `inject` requests, list the routes. */
+    readonly http: KernelHttp;
+    /**
+     * The port the kernel listens on (an ephemeral one with `http.port: 0`); undefined after
+     * `close()`.
+     */
+    readonly port: number | undefined;
+    /** Stops the kernel (the stop phases within their budgets, then Redis and the pool); idempotent. */
+    close(): Promise<void>;
+}
 /**
- * Creates and starts an in-process kernel. Logs are discarded unless `log` is given (JSON lines at
- * `log.level` and above go to `log.write`, e.g. to assert a secret never reaches the log).
- * Extensions named by package resolve from `resolveFrom` (default `process.cwd()`). Stop it with
- * `stop()`.
+ * Creates and starts an in-process kernel (`startKernelApp`; it listens on `config.http.port`).
+ * The kernel gets no process-wide signal handlers: a test stops it with `close()`. Logs are
+ * discarded unless `log` is given (JSON lines at `log.level` and above go to `log.write`, e.g. to
+ * assert a secret never reaches the log). Extensions named by package resolve from `resolveFrom`
+ * (default `process.cwd()`).
  */
 export declare function startTestKernel(config: KernelConfig, opts?: {
     resolveFrom?: string;
@@ -47,7 +68,7 @@ export declare function startTestKernel(config: KernelConfig, opts?: {
     };
     /** Only for a test about the real default: allow the official marketplace at its real URL. */
     allowOfficialMarketplace?: boolean;
-}): Promise<Kernel>;
+}): Promise<TestKernel>;
 /** Options of a {@link KernelRequest} call (`http.inject` options; `csrf: false` drops the header). */
 export type KernelRequestOptions = Parameters<KernelHttp["inject"]>[0] & {
     csrf?: boolean;
@@ -61,16 +82,16 @@ export type KernelRequest = (opts: KernelRequestOptions) => Promise<KernelRespon
 /** A request function with its own cookie jar (signed out until a response sets cookies). */
 export declare function cookieRequest(http: KernelHttp): KernelRequest;
 /** Creates a local account with {@link TEST_PASSWORD}; returns its id. */
-export declare function createLocalAccount(db: KernelDb, login: string, displayName?: string): Promise<string>;
+export declare function createLocalAccount(db: KernelSchemaDb, login: string, displayName?: string): Promise<string>;
 /** Signs in over HTTP and returns the user's request function. */
-export declare function login(k: Pick<Kernel, "http">, name: string, password?: string): Promise<KernelRequest>;
+export declare function login(k: Pick<TestKernel, "http">, name: string, password?: string): Promise<KernelRequest>;
 /** Creates an org as `req`'s user (who becomes its owner); returns its id. */
 export declare function createOrg(req: KernelRequest, name?: string): Promise<string>;
 /**
  * A new account joins the org through an invitation (created by `owner`, accepted with `login`
  * and {@link TEST_PASSWORD}); returns the account id and its signed-in request function.
  */
-export declare function joinOrg(k: Pick<Kernel, "http">, owner: KernelRequest, orgId: string, name: string, role?: "member" | "admin"): Promise<{
+export declare function joinOrg(k: Pick<TestKernel, "http">, owner: KernelRequest, orgId: string, name: string, role?: "member" | "admin"): Promise<{
     accountId: string;
     req: KernelRequest;
 }>;
@@ -90,17 +111,17 @@ export declare function createConversation(req: KernelRequest, orgId: string, ag
 /** Posts a user message; returns its event seq. */
 export declare function postMessage(req: KernelRequest, orgId: string, conversationId: string, text: string): Promise<number>;
 /** Every event of a conversation, in seq order (read from the database). */
-export declare function eventsOf(db: KernelDb, conversationId: string): Promise<ConversationEvent[]>;
+export declare function eventsOf(db: KernelSchemaDb, conversationId: string): Promise<ConversationEvent[]>;
 /** Waits for the first event matching `pred` and returns it. */
-export declare function waitForEvent(db: KernelDb, conversationId: string, pred: (e: ConversationEvent) => boolean, timeoutMs?: number, label?: string): Promise<ConversationEvent>;
+export declare function waitForEvent(db: KernelSchemaDb, conversationId: string, pred: (e: ConversationEvent) => boolean, timeoutMs?: number, label?: string): Promise<ConversationEvent>;
 /** Waits for the conversation's `n`-th terminal event (run_finished / run_failed / run_aborted). */
-export declare function waitForTerminal(db: KernelDb, conversationId: string, n?: number, timeoutMs?: number): Promise<ConversationEvent[]>;
+export declare function waitForTerminal(db: KernelSchemaDb, conversationId: string, n?: number, timeoutMs?: number): Promise<ConversationEvent[]>;
 /**
  * Waits until an IM card's message id is recorded (`channel_card_messages`). The kernel writes it in
  * the transaction after the card is sent; a click before that is treated as "not a card of this
  * conversation", so a test waits for this before it clicks, not only for the platform to get it.
  */
-export declare function cardRecorded(db: KernelDb, card: {
+export declare function cardRecorded(db: KernelSchemaDb, card: {
     messageId: string;
 } | {
     kind: "approval" | "question";

package/dist/kernel-helpers.js

@@ -1,7 +1,8 @@
 import { execFile } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { readdir, readFile, readlink } from "node:fs/promises";
 import { promisify } from "node:util";
-import { AccountsService, createKernel, createLogger, KernelConfigSchema, MARKETPLACE_OFFICIAL_URL_DEFAULT, } from "@capybara-hq/kernel";
+import { AccountsModule, AccountsService, closeKernelApp, createLogger, KernelConfigSchema, kernelAppHttp, kernelAppPort, MARKETPLACE_OFFICIAL_URL_DEFAULT, openKernelCliOverPool, startKernelApp, } from "@capybara-hq/kernel";
 import { sql } from "kysely";
 /**
  * Helpers for extension tests that run a real kernel: in process (`startTestKernel` +
@@ -60,20 +61,33 @@ export function assertOfflineOfficialMarketplace(config, allow = false) {
         "marketplaces.official.url at a fake, or build the config with testKernelConfig");
 }
 /**
- * Creates and starts an in-process kernel. Logs are discarded unless `log` is given (JSON lines at
- * `log.level` and above go to `log.write`, e.g. to assert a secret never reaches the log).
- * Extensions named by package resolve from `resolveFrom` (default `process.cwd()`). Stop it with
- * `stop()`.
+ * Creates and starts an in-process kernel (`startKernelApp`; it listens on `config.http.port`).
+ * The kernel gets no process-wide signal handlers: a test stops it with `close()`. Logs are
+ * discarded unless `log` is given (JSON lines at `log.level` and above go to `log.write`, e.g. to
+ * assert a secret never reaches the log). Extensions named by package resolve from `resolveFrom`
+ * (default `process.cwd()`).
  */
 export async function startTestKernel(config, opts = {}) {
     assertOfflineOfficialMarketplace(config, opts.allowOfficialMarketplace);
-    const k = await createKernel(config, {
+    const app = await startKernelApp(config, {
         env: {},
         logger: createLogger(opts.log?.level ?? "error", { write: opts.log?.write ?? (() => { }) }),
         ...(opts.resolveFrom !== undefined && { resolveFrom: opts.resolveFrom }),
-    });
-    await k.start();
-    return k;
+    }, 
+    // A signal source of its own: a test kernel never handles the process's SIGTERM / SIGINT
+    { signals: new EventEmitter() });
+    return testKernelOf(app);
+}
+/** The {@link TestKernel} view of a started kernel application. */
+function testKernelOf(app) {
+    return {
+        app,
+        http: kernelAppHttp(app),
+        get port() {
+            return kernelAppPort(app);
+        },
+        close: () => closeKernelApp(app),
+    };
 }
 /** A request function with its own cookie jar (signed out until a response sets cookies). */
 export function cookieRequest(http) {
@@ -110,7 +124,21 @@ function expectStatus(res, status, what) {
 }
 /** Creates a local account with {@link TEST_PASSWORD}; returns its id. */
 export async function createLocalAccount(db, login, displayName = login) {
-    return (await new AccountsService(db).createLocal({ login, password: TEST_PASSWORD, displayName })).id;
+    // the accounts module over the caller's Kysely; closing the context leaves it open
+    const app = await openKernelCliOverPool(db, {
+        logger: createLogger("error"),
+        modules: [AccountsModule],
+    });
+    try {
+        return (await app.get(AccountsService).createLocal({
+            login,
+            password: TEST_PASSWORD,
+            displayName,
+        })).id;
+    }
+    finally {
+        await app.close();
+    }
 }
 /** Signs in over HTTP and returns the user's request function. */
 export async function login(k, name, password = TEST_PASSWORD) {

package/dist/replica-runner.js

@@ -1,5 +1,10 @@
-import { createKernel, KernelConfigSchema } from "@capybara-hq/kernel";
-let kernel;
+import { EventEmitter } from "node:events";
+import { KernelConfigSchema, kernelAppPort, startKernelApp } from "@capybara-hq/kernel";
+/**
+ * The replica's signal source: the stop message (or the parent going away) raises SIGTERM on it, so
+ * the kernel stops through the same shutdown path as `capybara start` — also while it is starting.
+ */
+const signals = new EventEmitter();
 const isPlainObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** 深合并：普通对象逐键递归，其余（含数组）由 `over` 整体替换。 */
 function deepMerge(base, over) {
@@ -27,22 +32,25 @@ async function startKernel(c) {
         log: { level: "error" },
     };
     const config = KernelConfigSchema.parse(deepMerge(base, c.overrides));
-    kernel = await createKernel(config, {
+    const app = await startKernelApp(config, {
         resolveFrom: c.resolveFrom,
         ...(c.bootstrap !== undefined && { bootstrap: c.bootstrap }),
         ...(c.bootstrapManifest !== undefined && { bootstrapManifest: c.bootstrapManifest }),
-    });
-    await kernel.start();
-    process.send?.({ type: "ready", port: kernel.port });
+    }, { signals, exit: (code) => process.exit(code) });
+    process.send?.({ type: "ready", port: kernelAppPort(app) });
 }
 let exiting = false;
-/** 停内核后退出；内核停机卡住时 10 秒后强制退出。 */
+/** Stops the kernel, then exits; a stop stuck for 10 s exits with 1. */
 function shutdown() {
     if (exiting)
         return;
     exiting = true;
     setTimeout(() => process.exit(1), 10_000).unref();
-    (kernel?.stop() ?? Promise.resolve()).finally(() => process.exit(0));
+    // No kernel handlers yet (still building) or any more (the start failed): nothing to stop
+    if (signals.listenerCount("SIGTERM") === 0)
+        process.exit(0);
+    else
+        signals.emit("SIGTERM", "SIGTERM");
 }
 // 父进程（含被 SIGKILL）消失后 IPC 通道断开，副本自行退出，不留孤儿
 process.on("disconnect", shutdown);

package/package.json

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