@zhin.js/testing 0.0.0-stage → 1.0.2

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@zhin.js/testing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.2",
+  "description": "Real Plugin Runtime integration fixtures with synthetic IM endpoints",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@zhin.js/adapter": "1.1.19",
+    "@zhin.js/command": "1.1.7",
+    "@zhin.js/core": "1.1.44",
+    "@zhin.js/feature-kit": "1.1.5",
+    "@zhin.js/handler": "1.1.5",
+    "@zhin.js/middleware": "1.1.6",
+    "@zhin.js/im-contract": "1.1.4",
+    "@zhin.js/plugin-runtime": "1.1.14",
+    "@zhin.js/runtime": "1.1.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/toolkit/testing"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/toolkit/testing/tests"
+  }
 }

package/src/delivery-capture.ts

@@ -0,0 +1,48 @@
+import { Stream } from 'node:stream';
+
+/** Streams are transport-owned handles: record their identity without draining or freezing them. */
+export function captureDeliveryValue<T>(value: T): T {
+  return capture(value, new WeakMap()) as T;
+}
+
+function capture(value: unknown, seen: WeakMap<object, unknown>): unknown {
+  if (value instanceof Stream || (typeof ReadableStream !== 'undefined' && value instanceof ReadableStream)) return value;
+  if (!value || typeof value !== 'object') return structuredClone(value);
+  if (seen.has(value)) return seen.get(value);
+  if (Buffer.isBuffer(value) || ArrayBuffer.isView(value)) {
+    const copy = Buffer.isBuffer(value) ? Buffer.from(value) : structuredClone(value);
+    seen.set(value, copy);
+    return copy;
+  }
+  if (Array.isArray(value)) {
+    const copy: unknown[] = [];
+    seen.set(value, copy);
+    for (const item of value) copy.push(capture(item, seen));
+    return Object.freeze(copy);
+  }
+  if (value instanceof Map) {
+    const copy = new Map();
+    seen.set(value, copy);
+    for (const [key, item] of value) copy.set(capture(key, seen), capture(item, seen));
+    return Object.freeze(copy);
+  }
+  if (value instanceof Set) {
+    const copy = new Set();
+    seen.set(value, copy);
+    for (const item of value) copy.add(capture(item, seen));
+    return Object.freeze(copy);
+  }
+  // Native built-ins retain structuredClone semantics. SDK DTO classes use
+  // their enumerable data, just as structuredClone does, but may contain streams.
+  if (Object.prototype.toString.call(value) !== '[object Object]') {
+    const copy = Object.freeze(structuredClone(value));
+    seen.set(value, copy);
+    return copy;
+  }
+  const copy: Record<string, unknown> = {};
+  seen.set(value, copy);
+  for (const [key, item] of Object.entries(value)) Object.defineProperty(copy, key, {
+    value: capture(item, seen), enumerable: true, writable: true, configurable: true,
+  });
+  return Object.freeze(copy);
+}

package/src/fake-clock.ts

@@ -0,0 +1,116 @@
+import type { PluginId, ScheduleHost, ScheduleJobRegistration } from '@zhin.js/plugin-runtime';
+
+/** Controllable wall clock. It never touches the real `Date` or timers. */
+export class FakeClock {
+  #now: number;
+  readonly #listeners = new Set<(from: number, to: number) => Promise<void>>();
+
+  constructor(start: number | Date = Date.UTC(2026, 0, 1, 0, 0, 0)) {
+    this.#now = typeof start === 'number' ? start : start.getTime();
+  }
+
+  now(): number { return this.#now; }
+  date(): Date { return new Date(this.#now); }
+
+  /** Jump without firing anything (like setting the system time). */
+  set(time: number | Date): void { this.#now = typeof time === 'number' ? time : time.getTime(); }
+
+  /** Move forward and run every cron job that became due, in time order. */
+  async advance(ms: number): Promise<void> {
+    if (!(ms >= 0)) throw new RangeError('FakeClock.advance requires a non-negative duration');
+    const from = this.#now;
+    const to = from + ms;
+    for (const listener of [...this.#listeners]) await listener(from, to);
+    this.#now = to;
+  }
+
+  /** @internal */
+  onAdvance(listener: (from: number, to: number) => Promise<void>): () => void {
+    this.#listeners.add(listener);
+    return () => { this.#listeners.delete(listener); };
+  }
+}
+
+type Field = ReadonlySet<number>;
+
+function parseField(text: string, min: number, max: number): Field {
+  const values = new Set<number>();
+  for (const part of text.split(',')) {
+    const [range = '', stepText] = part.split('/');
+    const step = stepText === undefined ? 1 : Number(stepText);
+    if (!Number.isInteger(step) || step < 1) throw new TypeError(`Invalid cron step: ${part}`);
+    let lo = min;
+    let hi = max;
+    if (range !== '*') {
+      const [a, b] = range.split('-');
+      lo = Number(a);
+      hi = b === undefined ? (stepText === undefined ? lo : max) : Number(b);
+    }
+    if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo < min || hi > max || lo > hi) {
+      throw new TypeError(`Invalid cron field: ${text}`);
+    }
+    for (let v = lo; v <= hi; v += step) values.add(v);
+  }
+  return values;
+}
+
+/** Six-field cron (`sec min hour day month weekday`, Sunday = 0) evaluated in local time. */
+export function parseCron(cron: string): (date: Date) => boolean {
+  const parts = cron.trim().split(/\s+/);
+  if (parts.length !== 6) throw new TypeError(`Cron must have six fields: ${cron}`);
+  const sec = parseField(parts[0]!, 0, 59);
+  const min = parseField(parts[1]!, 0, 59);
+  const hour = parseField(parts[2]!, 0, 23);
+  const day = parseField(parts[3]!, 1, 31);
+  const month = parseField(parts[4]!, 1, 12);
+  const week = parseField(parts[5]!, 0, 7);
+  return (d) => sec.has(d.getSeconds()) && min.has(d.getMinutes()) && hour.has(d.getHours())
+    && day.has(d.getDate()) && month.has(d.getMonth() + 1)
+    && (week.has(d.getDay()) || (d.getDay() === 0 && week.has(7)));
+}
+
+export interface FakeScheduledJob {
+  readonly id: string;
+  readonly cron: string;
+  readonly description?: string;
+  readonly owner?: PluginId;
+}
+
+interface Entry extends ScheduleJobRegistration { readonly matches: (d: Date) => boolean }
+
+/**
+ * In-memory process Schedule Host driven by a {@link FakeClock}. The harness wraps it with the real
+ * `PluginScheduleHost` to get the exact facade plugins see.
+ */
+export class FakeScheduleRootHost implements ScheduleHost {
+  readonly #jobs = new Set<Entry>();
+
+  constructor(readonly clock: FakeClock) {
+    clock.onAdvance(async (from, to) => {
+      for (let t = Math.floor(from / 1000) * 1000 + 1000; t <= to; t += 1000) {
+        const date = new Date(t);
+        for (const job of [...this.#jobs]) {
+          if (this.#jobs.has(job) && job.isActive?.() !== false && job.matches(date)) await job.execute();
+        }
+      }
+    });
+  }
+
+  register(job: ScheduleJobRegistration): () => void {
+    const entry: Entry = Object.freeze({ ...job, matches: parseCron(job.cron) });
+    this.#jobs.add(entry);
+    return () => { this.#jobs.delete(entry); };
+  }
+
+  list(): readonly FakeScheduledJob[] {
+    return [...this.#jobs].map(({ id, cron, description, owner }) =>
+      ({ id, cron, ...(description === undefined ? {} : { description }), ...(owner === undefined ? {} : { owner }) }));
+  }
+
+  /** Run a registered job now, by its qualified id; rejects if it is not registered. */
+  async trigger(id: string): Promise<void> {
+    const job = [...this.#jobs].find(item => item.id === id);
+    if (!job) throw new Error(`No scheduled job: ${id}`);
+    await job.execute();
+  }
+}

package/src/fake-hosts.ts

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import type {
+  DatabaseHost, DatabaseHostModel, DatabaseHostSelection, DeliveryTarget, JsonValue,
+  OutboundEditInput, OutboundReactionInput, OutboundRecallInput, OutboundRootHost, OutboundSendInput,
+  OutboundTypingInput, PersistentStatePort, PluginId, StateRecord, StateScope,
+} from '@zhin.js/plugin-runtime';
+
+type Row = Record<string, unknown>;
+const matches = (row: Row, query: Row): boolean => Object.entries(query).every(([k, v]) => row[k] === v);
+
+class MemoryModel implements DatabaseHostModel {
+  readonly rows: Row[] = [];
+
+  select<Fields extends string[]>(...fields: Fields): DatabaseHostSelection {
+    let query: Row = {};
+    let order: { field: string; direction: 'ASC' | 'DESC' } | undefined;
+    let max = Infinity;
+    const run = (): Row[] => {
+      let out = this.rows.filter(row => matches(row, query));
+      if (order) {
+        const { field, direction } = order;
+        out = [...out].sort((a, b) => ((a[field] as never) < (b[field] as never) ? -1
+          : (a[field] as never) > (b[field] as never) ? 1 : 0) * (direction === 'DESC' ? -1 : 1));
+      }
+      return out.slice(0, max).map(row => fields.length === 0 ? { ...row }
+        : Object.fromEntries(fields.map(f => [f, row[f]])));
+    };
+    const selection: DatabaseHostSelection = {
+      where: (q) => { query = { ...query, ...q }; return selection; },
+      orderBy: (field, direction = 'ASC') => { order = { field, direction }; return selection; },
+      limit: (count) => { max = count; return selection; },
+      then: (ok, bad) => Promise.resolve().then(run).then(ok, bad),
+    };
+    return selection;
+  }
+
+  async insert(row: Row): Promise<unknown> { this.rows.push({ ...row }); return undefined; }
+  delete(): { where(query: Row): Promise<unknown> } {
+    return { where: async (query: Row) => {
+      for (let i = this.rows.length - 1; i >= 0; i--) if (matches(this.rows[i]!, query)) this.rows.splice(i, 1);
+    } };
+  }
+  update(patch: Row): { where(query: Row): Promise<unknown> } {
+    return { where: async (query: Row) => { for (const row of this.rows) if (matches(row, query)) Object.assign(row, patch); } };
+  }
+  async count(where: Row = {}): Promise<number> { return this.rows.filter(row => matches(row, where)).length; }
+}
+
+class MemoryState implements PersistentStatePort {
+  readonly #entries = new Map<string, StateRecord>();
+  static key(owner: PluginId, scope: StateScope, key: string): string { return JSON.stringify([owner, scope, key]); }
+
+  async read(owner: PluginId, scope: StateScope, key: string): Promise<StateRecord | undefined> {
+    return this.#entries.get(MemoryState.key(owner, scope, key));
+  }
+  async compareExchange(owner: PluginId, scope: StateScope, key: string, revision: string | undefined,
+    value: JsonValue | undefined, expiresAt: number | null): Promise<boolean> {
+    const id = MemoryState.key(owner, scope, key);
+    if (this.#entries.get(id)?.revision !== revision) return false;
+    if (value === undefined) this.#entries.delete(id);
+    else this.#entries.set(id, { revision: randomUUID(), value: JSON.parse(JSON.stringify(value)) as JsonValue, expiresAt });
+    return true;
+  }
+}
+
+/**
+ * Process-wide in-memory Database Host. Tables appear on `define()` (plugins define in `setup`);
+ * `where` is equality-only, there are no SQL semantics. `state` is a real compare-exchange port, so
+ * `PluginStateStore` behaves as in production (TTL uses the real `Date.now()`).
+ */
+export class FakeDatabaseRootHost implements DatabaseHost {
+  readonly dialect = 'memory';
+  started = true;
+  readonly state: PersistentStatePort = new MemoryState();
+  readonly #models = new Map<string, MemoryModel>();
+  readonly models = { get: (name: string): DatabaseHostModel | undefined => this.#models.get(name) };
+
+  define(name: string, _definition: Record<string, unknown>): void {
+    if (!this.#models.has(name)) this.#models.set(name, new MemoryModel());
+  }
+  tables(): readonly string[] { return [...this.#models.keys()]; }
+  getRawDatabase(): undefined { return undefined; }
+  async start(): Promise<void> { this.started = true; }
+  async stop(): Promise<void> { this.started = false; }
+  /** Rows by physical (owner-qualified) table name. */
+  rowsOf(physical: string): readonly Row[] { return this.#models.get(physical)?.rows ?? []; }
+}
+
+export interface FakeOutboundCall {
+  readonly kind: 'send' | 'sendTarget' | 'addReaction' | 'removeReaction' | 'recall' | 'edit' | 'typing';
+  readonly input: unknown;
+  /** Present for `sendTarget`: the sending plugin, as bound by the real facade. */
+  readonly requester?: PluginId;
+  readonly id: string | null;
+}
+
+/**
+ * Records proactive sends. It stands in for the Root outbound port, so the real `PluginOutboundHost`
+ * facade (owner binding) still wraps it. It does NOT run the renderer/middleware chain; for that use
+ * `PluginTestKit` with a synthetic endpoint.
+ */
+export class FakeOutboundRootHost implements OutboundRootHost {
+  readonly calls: FakeOutboundCall[] = [];
+  #failure: unknown;
+  #nextId = 1;
+
+  /** Make the next outbound operation reject once. */
+  failNext(error: unknown = new Error('fake outbound failure')): void { this.#failure = error; }
+
+  #record(kind: FakeOutboundCall['kind'], input: unknown, requester?: PluginId, hasId = true): Promise<string | null> {
+    if (this.#failure !== undefined) {
+      const error = this.#failure;
+      this.#failure = undefined;
+      return Promise.reject(error);
+    }
+    const id = hasId ? `fake-${this.#nextId++}` : null;
+    this.calls.push(Object.freeze({ kind, input, ...(requester === undefined ? {} : { requester }), id }));
+    return Promise.resolve(id);
+  }
+
+  send(input: OutboundSendInput): Promise<string | null> { return this.#record('send', input); }
+  sendTarget(target: DeliveryTarget, content: unknown, requester: PluginId): Promise<string | null> {
+    return this.#record('sendTarget', { target, content }, requester);
+  }
+  addReaction(input: OutboundReactionInput): Promise<string | null> { return this.#record('addReaction', input); }
+  async removeReaction(input: unknown): Promise<void> { await this.#record('removeReaction', input, undefined, false); }
+  async recall(input: OutboundRecallInput): Promise<void> { await this.#record('recall', input, undefined, false); }
+  edit(input: OutboundEditInput): Promise<string | null> { return this.#record('edit', input); }
+  async typing(input: OutboundTypingInput): Promise<void> { await this.#record('typing', input, undefined, false); }
+  runWithView<T>(operation: () => Promise<T>): Promise<T> { return operation(); }
+}

package/src/fake-plugin.ts

@@ -0,0 +1,171 @@
+import {
+  DisposeStack, GenerationHandoffStack, PluginDatabaseHost, PluginOutboundHost, PluginScheduleHost,
+  Scope, databaseHostToken, outboundHostToken, qualifyPluginResourceName, rootPluginId, scheduleHostToken,
+  type Dispose, type FeatureId, type PluginDefinition, type PluginId, type PluginNodeSnapshot,
+  type PluginSetupContext, type Token,
+} from '@zhin.js/plugin-runtime';
+import type { CapabilityContext } from '@zhin.js/feature-kit';
+import { FakeClock, FakeScheduleRootHost } from './fake-clock.js';
+import { FakeDatabaseRootHost, FakeOutboundRootHost, type FakeOutboundCall } from './fake-hosts.js';
+
+/** A typed `token -> value` binding; create with {@link fakeResource}. */
+export interface FakeResource { readonly token: Token<unknown>; readonly value: unknown }
+
+/** Bind a value to a token with the token's own type, so tests need no cast. */
+export function fakeResource<T>(token: Token<T>, value: T): FakeResource {
+  return { token: token as Token<unknown>, value };
+}
+
+export interface FakePluginOptions<TConfig = unknown> {
+  /** Plugin name (also the instance key). Default `test-plugin`. */
+  readonly name?: string;
+  /** Value returned by `context.config.get()`. Default `{}`. */
+  readonly config?: TConfig;
+  /** Extra resources to `provide()` on the Scope, e.g. a hand-written fake for a custom token. */
+  readonly resources?: readonly FakeResource[];
+  /** Install the fake Database / Schedule / Outbound hosts (default: all `true`). */
+  readonly hosts?: { readonly database?: boolean; readonly schedule?: boolean; readonly outbound?: boolean };
+  /** Start time or an existing clock shared by several fakes. */
+  readonly clock?: FakeClock | number | Date;
+  /** Feature projections returned by `capabilityContext().project()`. */
+  readonly projections?: ReadonlyMap<FeatureId, unknown>;
+  readonly generation?: number;
+}
+
+/** A capability registered through `context.addFeature` / `context.addCommand` / `context.addXxx`. */
+export interface FakeRegisteredFeature {
+  readonly kind: string;
+  readonly localName: string;
+  readonly definition: unknown;
+}
+
+/**
+ * Typed fake of one plugin's runtime surface. Built from the real `Scope`, `DisposeStack`,
+ * `GenerationHandoffStack` and the real owner-bound `PluginDatabaseHost` / `PluginScheduleHost` /
+ * `PluginOutboundHost` facades, over in-memory process hosts. No `as never` needed in tests.
+ */
+export class FakePlugin<TConfig = unknown> {
+  readonly id: PluginId = rootPluginId();
+  readonly name: string;
+  readonly config: TConfig;
+  readonly resources: Scope;
+  readonly lifecycle = new DisposeStack();
+  readonly handoff = new GenerationHandoffStack();
+  readonly clock: FakeClock;
+  readonly generation: number;
+  readonly projections: ReadonlyMap<FeatureId, unknown>;
+  /** Features registered by `setup()` through `addFeature` / `addCommand` / `addMiddleware` ... */
+  readonly features: FakeRegisteredFeature[] = [];
+  /** Process-level fakes behind the facades. */
+  readonly databaseHost = new FakeDatabaseRootHost();
+  readonly outboundHost = new FakeOutboundRootHost();
+  readonly scheduleHost: FakeScheduleRootHost;
+  /** Facades exactly as `resources.use(token)` returns them. */
+  readonly database: PluginDatabaseHost;
+  readonly schedule: PluginScheduleHost;
+  readonly outbound: PluginOutboundHost;
+  readonly #abort = new AbortController();
+  readonly #context: PluginSetupContext<TConfig>;
+
+  constructor(options: FakePluginOptions<TConfig> = {}) {
+    this.name = options.name ?? 'test-plugin';
+    this.config = (options.config ?? {}) as TConfig;
+    this.generation = options.generation ?? 1;
+    this.projections = options.projections ?? new Map();
+    this.clock = options.clock instanceof FakeClock ? options.clock : new FakeClock(options.clock);
+    this.scheduleHost = new FakeScheduleRootHost(this.clock);
+    this.resources = new Scope(this.id, undefined, this.lifecycle);
+    this.database = new PluginDatabaseHost(this.id, this.databaseHost);
+    this.schedule = new PluginScheduleHost(this.id, this.scheduleHost);
+    this.outbound = new PluginOutboundHost(this.id, this.outboundHost);
+    const hosts = options.hosts ?? {};
+    if (hosts.database !== false) this.resources.provide(databaseHostToken, this.database);
+    if (hosts.schedule !== false) this.resources.provide(scheduleHostToken, this.schedule);
+    if (hosts.outbound !== false) this.resources.provide(outboundHostToken, this.outbound);
+    for (const { token, value } of options.resources ?? []) this.resources.provide(token, value);
+    this.#context = this.#createSetupContext();
+  }
+
+  /** The `context` argument `setup()` receives. */
+  get context(): PluginSetupContext<TConfig> { return this.#context; }
+  get signal(): AbortSignal { return this.#abort.signal; }
+
+  /** Messages recorded by the fake outbound host (every kind of call). */
+  get sent(): readonly FakeOutboundCall[] { return this.outboundHost.calls; }
+
+  /** Rows of a table the plugin created with `database.define(name, ...)`. */
+  rows(name: string): readonly Record<string, unknown>[] {
+    return this.databaseHost.rowsOf(qualifyPluginResourceName(this.id, name));
+  }
+
+  /** Run `definition.setup()` against this fake; a returned disposer joins `lifecycle`. */
+  async setup(definition: PluginDefinition<TConfig>): Promise<void> {
+    const dispose: void | Dispose = await definition.setup?.(this.#context);
+    if (dispose) this.lifecycle.add(dispose);
+  }
+
+  /** Tokens declared in `requires` that this fake did not provide. */
+  missingRequirements(definition: PluginDefinition<TConfig>): readonly Token<unknown>[] {
+    return (definition.requires ?? []).filter(token => !this.resources.has(token));
+  }
+
+  /** A `CapabilityContext` for running commands / middleware / handlers against this fake. */
+  capabilityContext(): CapabilityContext<TConfig> {
+    const owner: PluginNodeSnapshot = Object.freeze({
+      id: this.id, instanceKey: this.name, packageName: this.name, packageRoot: '/fake', children: [],
+    });
+    return Object.freeze({
+      signal: this.signal, owner, generation: this.generation,
+      config: this.config as Readonly<TConfig>,
+      use: <T>(token: Token<T>): T => this.resources.use(token),
+      project: <T>(feature: FeatureId): T => {
+        if (!this.projections.has(feature)) throw new Error(`Missing Feature projection ${feature}`);
+        return this.projections.get(feature) as T;
+      },
+    });
+  }
+
+  /** Abort `signal` and run every disposer (reverse order). */
+  async dispose(): Promise<void> {
+    this.#abort.abort();
+    await this.lifecycle.dispose();
+  }
+
+  #createSetupContext(): PluginSetupContext<TConfig> {
+    const base = {
+      signal: this.signal,
+      plugin: Object.freeze({ id: this.id, instanceKey: this.name, root: this.id, role: 'root' as const }),
+      config: Object.freeze({ get: () => this.config as Readonly<TConfig> }),
+      resources: this.resources,
+      lifecycle: this.lifecycle,
+      handoff: this.handoff,
+      addFeature: (feature: FeatureId | string, localName: string, definition: unknown) => {
+        this.features.push({ kind: String(feature), localName, definition });
+      },
+    };
+    // Feature packages augment the setup context with `addCommand` / `addMiddleware` / ...; record them all.
+    return new Proxy(base, {
+      get: (target, key, receiver) => {
+        if (Reflect.has(target, key) || typeof key !== 'string' || !/^add[A-Z]/.test(key)) {
+          return Reflect.get(target, key, receiver);
+        }
+        const kind = key.slice(3).toLowerCase();
+        return (localName: string, definition: unknown) => { this.features.push({ kind, localName, definition }); };
+      },
+    }) as unknown as PluginSetupContext<TConfig>;
+  }
+}
+
+export function createFakePlugin<TConfig = unknown>(options?: FakePluginOptions<TConfig>): FakePlugin<TConfig> {
+  return new FakePlugin(options);
+}
+
+/** Create a fake and run `definition.setup()` in one step. Call `dispose()` when done. */
+export async function runPluginSetup<TConfig = unknown>(
+  definition: PluginDefinition<TConfig>,
+  options?: Omit<FakePluginOptions<TConfig>, 'name'>,
+): Promise<FakePlugin<TConfig>> {
+  const fake = new FakePlugin<TConfig>({ ...options, name: definition.name });
+  await fake.setup(definition);
+  return fake;
+}

package/src/fake-runners.ts

@@ -0,0 +1,117 @@
+import type {
+  CommandContext, CommandDefinition, CommandMessage, CommandParameterValue,
+} from '@zhin.js/command';
+import type { HandlerContext, HandlerDefinition } from '@zhin.js/handler';
+import type {
+  MiddlewareContext, MiddlewareDefinition, MiddlewareNext,
+} from '@zhin.js/middleware';
+import type { FakePlugin } from './fake-plugin.js';
+
+/** Inbound message with recorded replies. */
+export interface FakeMessage extends CommandMessage {
+  /** Everything passed to `$reply`, in order. */
+  readonly replies: unknown[];
+}
+
+export interface FakeMessageInit {
+  readonly content?: string;
+  readonly sender?: { readonly id: string; readonly name?: string; readonly roles?: readonly string[] };
+  readonly conversation?: Partial<CommandMessage['conversation']>;
+  readonly id?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly $client?: unknown;
+}
+
+export function createFakeMessage(init: FakeMessageInit = {}): FakeMessage {
+  const replies: unknown[] = [];
+  const conversation: CommandMessage['conversation'] = {
+    endpoint: { id: 'test', adapter: 'test' }, kind: 'group', id: 'test-group', ...init.conversation,
+  };
+  return {
+    conversation, content: init.content ?? '',
+    sender: init.sender ?? { id: 'test-user', name: 'Tester', roles: [] },
+    ...(init.id === undefined ? {} : { id: init.id }),
+    ...(init.metadata === undefined ? {} : { metadata: init.metadata }),
+    ...(init.$client === undefined ? {} : { $client: init.$client }),
+    replies,
+    async $reply(content: unknown) { replies.push(content); return `reply-${replies.length}`; },
+  };
+}
+
+export interface RunCommandOptions<TInput extends CommandMessage = FakeMessage> {
+  readonly input?: TInput;
+  readonly args?: readonly string[];
+  readonly params?: Readonly<Record<string, CommandParameterValue>>;
+  readonly options?: Readonly<Record<string, CommandParameterValue>>;
+  readonly segments?: CommandContext['segments'];
+  readonly interaction?: CommandContext['interaction'];
+}
+
+/** Build the context a command receives from the fake plugin; usable for direct `execute()` calls. */
+export function createCommandContext<TConfig, TInput extends CommandMessage = FakeMessage>(
+  fake: FakePlugin<TConfig>,
+  options: RunCommandOptions<TInput> = {},
+): CommandContext<TConfig, TInput, string | undefined> {
+  const input = (options.input ?? createFakeMessage()) as TInput;
+  const conversation = input.conversation;
+  const sender = input.sender;
+  return {
+    ...fake.capabilityContext(),
+    args: options.args ?? [],
+    params: options.params ?? {},
+    options: options.options ?? {},
+    segments: options.segments ?? [],
+    input,
+    $client: input.$client as never,
+    interaction: options.interaction,
+    adapter: conversation.endpoint.adapter,
+    endpoint: conversation.endpoint.id,
+    scene: input.scene ?? { id: conversation.id, type: conversation.kind },
+    ...(sender ? { sender: { id: sender.id, name: sender.name, role: sender.roles ?? [] } } : {}),
+  };
+}
+
+/**
+ * Execute a command definition against the fake. This calls `execute()` directly: it does NOT run
+ * route matching, parameter parsing, `permit`, or admission. Use `PluginTestKit` for those.
+ */
+export async function runCommand<TConfig, TResult, TInput extends CommandMessage = FakeMessage>(
+  fake: FakePlugin<TConfig>,
+  definition: CommandDefinition<TConfig, TResult, TInput, string | undefined>,
+  options?: RunCommandOptions<TInput>,
+): Promise<TResult> {
+  return definition.execute(createCommandContext(fake, options));
+}
+
+export interface RunMiddlewareResult {
+  /** `true` when the middleware called `next()`. */
+  readonly continued: boolean;
+  readonly result: unknown;
+}
+
+/** Execute an inbound or outbound middleware's `handle()`; `next` records whether it was called. */
+export async function runMiddleware<TConfig, TInput = FakeMessage>(
+  fake: FakePlugin<TConfig>,
+  definition: MiddlewareDefinition<TInput, TConfig, string | undefined>,
+  input: TInput = createFakeMessage() as TInput,
+): Promise<RunMiddlewareResult> {
+  let continued = false;
+  const context: MiddlewareContext<TInput, TConfig, string | undefined> = {
+    ...fake.capabilityContext(),
+    input,
+    $client: (input as { $client?: unknown } | undefined)?.$client as never,
+  };
+  const next = (async () => { continued = true; return undefined; }) as unknown as MiddlewareNext;
+  const result = await definition.handle(context, next as never);
+  return { continued, result };
+}
+
+/** Execute a handler's `handle()` with `this` bound to a capability context. */
+export async function runHandler<TConfig>(
+  fake: FakePlugin<TConfig>,
+  definition: HandlerDefinition,
+  ...args: unknown[]
+): Promise<void> {
+  const context: HandlerContext<TConfig> = fake.capabilityContext();
+  await definition.handle.call(context as HandlerContext, ...args);
+}