@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/client/dev-server.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A dev server for a test runner, started in-process and isolated (#640).
+ *
+ * The same server `sdk dev --isolated` runs: no lock file, so it starts beside
+ * the developer's own and no CLI command finds it by accident; configuration
+ * from the package alone; uploads in a temporary directory removed at stop.
+ * For Playwright's `globalSetup`, a recording script, or anything else that
+ * would otherwise spawn `sdk dev`, wait for a port and parse its output.
+ */
+import type { SignatureCallbacks } from '@seriousgaming/sdk';
+import type { Clock } from '../core/clock';
+import type { ParticipantCounts } from '../core/session';
+export interface DevServerOptions {
+    /** The package to serve: the directory holding `seriousgaming.sdk.json`. */
+    packagePath: string;
+    /** Where to look for a port, stepping up past any in use. Any free port by default. */
+    port?: number;
+    /** Teams to start with. The manifest's bounds still apply. */
+    teams?: number;
+    /** Participants each team is seeded with: one count for all, or one per team. */
+    participants?: ParticipantCounts;
+    /** Scenario to activate; `null` opts out of the game's default. */
+    scenarioId?: string | null;
+    locale?: string;
+    /** A clock the test moves, such as a {@link FakeClock}, for timed ticks. */
+    clock?: Clock;
+    /** Replace callbacks logic receives, such as `generateText`. */
+    callbacks?: Partial<SignatureCallbacks>;
+    /** Re-initialise on every edit that applies only at initialisation. */
+    reinitOnChange?: boolean;
+}
+export interface DevServer {
+    /** The console and API, such as `http://localhost:53712`. */
+    url: string;
+    /** Where game surfaces and the files they read are served from. */
+    assetUrl: string;
+    /** Stop the server and remove its temporary files. */
+    stop(): Promise<void>;
+}
+/**
+ * Start an isolated dev server for the package and resolve once it answers.
+ *
+ * Platform credentials come from the environment and the package's `.env`, as
+ * `sdk dev` reads them. Always call `stop()`: the server holds ports and a
+ * file watcher open until it is told to let go.
+ *
+ * @example
+ * ```ts
+ * // playwright.global-setup.ts
+ * import { startDevServer } from '@seriousgaming/sdk-tools/client';
+ *
+ * export default async function globalSetup() {
+ *     const server = await startDevServer({ packagePath: process.cwd() });
+ *     process.env.BASE_URL = server.url;
+ *     return () => server.stop();
+ * }
+ * ```
+ */
+export declare function startDevServer(options: DevServerOptions): Promise<DevServer>;

package/dist/client/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Programmatic API for testing a game in-process.
+ *
+ * `createTestSession` runs the session the dev server runs (hooks, validators,
+ * endpoints, participants, undo, per-team ticks and timers) with no server
+ * around it. `startDevServer` runs the server too, isolated from any dev
+ * server already running for the package, for browser tests and recordings.
+ *
+ * @example
+ * ```ts
+ * import { createTestSession } from '@seriousgaming/sdk-tools/client';
+ * import { fileURLToPath } from 'url';
+ *
+ * const session = await createTestSession({
+ *     packagePath: fileURLToPath(new URL('../..', import.meta.url)),
+ * });
+ *
+ * await session.send({ type: 'tick' });
+ * ```
+ */
+export type { SignatureCallbacks } from '@seriousgaming/sdk';
+export { createTestSession, type ContextPatch, type DeletePath, type SetDataOptions, type SetSharedDataOptions, type TestSession, type TestSessionOptions, type TestSessionState, type TestSessionTeam, type UntypedContext, } from './test-session';
+export { startDevServer, type DevServer, type DevServerOptions } from './dev-server';
+export { createStubServices, stubGenerateText, type TestServices } from './stub-services';
+export { FakeClock, type Clock } from '../core/clock';
+export type { Command, MutationCommand, QueryCommand, QueryResult } from '../core/protocol';
+export type { ParticipantCounts } from '../core/session';
+export type { MutationResult, StateProjection } from '@seriousgaming/sdk/projection';

package/dist/client/stub-services.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The service callbacks a test session offers by default: deterministic,
+ * offline stand-ins for the platform's.
+ *
+ * A test that reaches the platform fails without a network, without a key and
+ * in a sandbox, and passes or fails on what a model happened to say. These
+ * answer from the request alone, so the same request always gets the same
+ * answer and a test can assert on it.
+ *
+ * The stubs themselves are the SDK's (`@seriousgaming/sdk/testing`), which a
+ * unit test calling logic directly uses too, so both answer alike. Only the
+ * speech clip differs in where it goes: here, into the session's blob store.
+ */
+import type { SignatureCallbacks } from '@seriousgaming/sdk';
+import { stubGenerateText } from '@seriousgaming/sdk/testing';
+export { stubGenerateText };
+/** Where a test session's service callbacks go (`TestSessionOptions.services`). */
+export type TestServices = 'stub' | 'platform';
+/**
+ * The stubbed service callbacks: `generateText`, `generateSpeech` and
+ * `extractText`. Blob storage stays real, because it is local.
+ *
+ * - `generateText` answers `[stub <hash>] <excerpt>`: an eight-digit hex hash
+ *   of the whole request, then the first 60 characters of its prompt (the
+ *   `prompt`, or the last `user` message's text) with whitespace collapsed,
+ *   ending in `...` when it was cut. A request with a `jsonSchema` is
+ *   answered with JSON that satisfies it.
+ * - `generateSpeech` stores 100ms of silence as a WAV blob and returns its
+ *   `blob:` reference, so `readAsset` resolves it like real audio.
+ * - `extractText` answers `[stub] text of <reference>`, without reading the file.
+ */
+export declare function createStubServices(packagePath: string): Required<Pick<SignatureCallbacks, 'generateText' | 'generateSpeech' | 'extractText'>>;

package/dist/client/test-session.d.ts

@@ -0,0 +1,195 @@
+/**
+ * A session to test against, in this process.
+ *
+ * A game is more than its engine. Hooks fire when somebody joins, validators
+ * refuse a decision, endpoints answer a surface, a timer ticks the round,
+ * independent teams tick one at a time, and undo puts a round back. None of
+ * that is reachable by calling `Init` and `Run`.
+ *
+ * This is the session `sdk dev` runs, with no server around it. Every command
+ * the console, the CLI or a surface can send, it can send, and it answers the
+ * same way.
+ */
+import type { SignatureCallbacks } from '@seriousgaming/sdk';
+import type { MutationResult, ProjectedTeam, StateProjection } from '@seriousgaming/sdk/projection';
+import type { Clock } from '../core/clock';
+import type { Command, MutationCommand, QueryCommand, QueryResult } from '../core/protocol';
+import { type ParticipantCounts } from '../core/session';
+import { type TestServices } from './stub-services';
+export interface TestSessionOptions {
+    /** Absolute path to the package, where `seriousgaming.sdk.json` lives. */
+    packagePath: string;
+    /** Teams to start with. The game's bounds still apply. */
+    teams?: number;
+    /**
+     * Participants to seed each team with: one count, or one per team.
+     * Defaults to one each, or the game's `perTeam.minParticipants`. Zero is
+     * allowed.
+     */
+    participants?: ParticipantCounts;
+    /**
+     * A scenario to start on. Omit for the game's default scenario, or pass
+     * `null` to run on the settings defaults.
+     */
+    scenarioId?: string | null;
+    locale?: string;
+    /**
+     * Replace callbacks logic receives. Anything not named keeps its default:
+     * a stub, or the platform's with `services: 'platform'`.
+     */
+    callbacks?: Partial<SignatureCallbacks>;
+    /**
+     * Where the service callbacks (`generateText`, `generateSpeech`,
+     * `extractText`) go. `'stub'`, the default, answers deterministically and
+     * offline (see `createStubServices`), so a test needs no network and no
+     * key. `'platform'` sends them to the Serious Gaming platform, with
+     * `platform` or the environment's credentials.
+     */
+    services?: TestServices;
+    /**
+     * The clock timers run on. Pass a `FakeClock` and move it with
+     * `advanceClock` to test automatic ticking without waiting.
+     */
+    clock?: Clock;
+    /**
+     * Press Play on a game with a configuration step (§8.3). Default `true`;
+     * pass `false` to test the step itself.
+     */
+    play?: boolean;
+    /** Serious Gaming platform access, used with `services: 'platform'`. */
+    platform?: {
+        apiKey?: string;
+        apiHost?: string;
+    };
+}
+/** A capability context as the projection carries it, before a game's types narrow it. */
+export type UntypedContext = Record<string, Record<string, unknown>>;
+/** One team as {@link TestSession.state} reports it, its context typed. */
+export interface TestSessionTeam<Context = UntypedContext> extends Omit<ProjectedTeam, 'context'> {
+    /** The composed view: the team's own context plus the shared store (§7.5). */
+    context: Context;
+}
+/** The session's observable state, with each team's context and the shared store typed. */
+export type TestSessionState<Context = UntypedContext, Shared = UntypedContext> = Omit<StateProjection, 'teams' | 'shared'> & {
+    teams: TestSessionTeam<Context>[];
+    shared: Shared;
+};
+/**
+ * A write to some of a context's capabilities, each merged one level deep as
+ * a surface's `setData` is (§9.5): name the variables that change.
+ */
+export type ContextPatch<Context> = {
+    [K in keyof Context]?: Partial<Context[K]>;
+};
+/** A path to remove, as a surface's `deletes` names one (§9.5). */
+export type DeletePath = string | string[];
+export interface SetDataOptions {
+    /** Paths to remove once the patch has merged. */
+    deletes?: DeletePath[];
+    /**
+     * Who writes. `'participant'`, the default, writes as a player surface
+     * does: as the team's first participant (or `participantId`), held to the
+     * surface's `writes` and put to the validators. `'system'` writes as the
+     * CLI does, trusted, ungated and unchecked: for arranging a board a test
+     * then plays on.
+     */
+    as?: 'participant' | 'system';
+    /** The participant to write as. Defaults to the team's first. */
+    participantId?: string;
+    /** The player surface the participant writes through. Defaults to `ui`. */
+    ui?: string;
+}
+export interface SetSharedDataOptions {
+    deletes?: DeletePath[];
+    /**
+     * The session surface the facilitator writes through, which holds the
+     * write to that surface's `writes`. Omit to write as the CLI does,
+     * trusted and unchecked.
+     */
+    ui?: string;
+}
+/**
+ * A session to test against.
+ *
+ * `Context` and `Shared` type what {@link state}, {@link team} and
+ * {@link shared} return, and what {@link setData} and {@link setSharedData}
+ * accept. Pass the engine's generated `Context` and `SharedContext`; nothing
+ * checks them against the running package, any more than a cast would.
+ */
+export interface TestSession<Context = UntypedContext, Shared = UntypedContext> {
+    /**
+     * Run a command, exactly as the dev server would: a mutation settles as
+     * `{ ok: true }` or `{ ok: false, outcome }`, and a read answers with its
+     * result. A refusal is an answer, not a throw.
+     */
+    send(command: MutationCommand): Promise<MutationResult>;
+    send(command: QueryCommand): Promise<QueryResult>;
+    send(command: Command): Promise<MutationResult | QueryResult>;
+    /** The whole session now: teams, contexts, rosters, the store, the timer. */
+    state(): TestSessionState<Context, Shared>;
+    /**
+     * One team now, by its stable index (§5.6), not its array position. Throws
+     * when no team has that index.
+     */
+    team(index: number): TestSessionTeam<Context>;
+    /**
+     * The shared store now (§7.5), under `context` as a session surface's
+     * `sessionData.shared` carries it, so an assertion reads the same in a
+     * test and in the surface. The context is empty outside shared-state mode.
+     */
+    readonly shared: {
+        readonly context: Shared;
+    };
+    /**
+     * Tick as the facilitator does: never gated by a validator. `team` ticks
+     * that one team in independent mode; omit it to tick every team.
+     */
+    tick(options?: {
+        team?: number;
+    }): Promise<MutationResult>;
+    /**
+     * Ask for the next tick as a participant's surface does, so the
+     * validators' `RequestTick` gates judge it. Asks as the team's first
+     * participant unless `participantId` is given.
+     */
+    requestTick(team: number, options?: {
+        participantId?: string;
+    }): Promise<MutationResult>;
+    /**
+     * Write to one team's context, by stable index. As a participant through
+     * `ui` unless `as: 'system'` (see {@link SetDataOptions}).
+     */
+    setData(team: number, patch: ContextPatch<Context>, options?: SetDataOptions): Promise<MutationResult>;
+    /** Write to the shared store, as the facilitator does. */
+    setSharedData(patch: ContextPatch<Shared>, options?: SetSharedDataOptions): Promise<MutationResult>;
+    /**
+     * Resolves once everything queued has run, including a tick a timer set
+     * off. `advanceClock` already waits; this is for a timer moved by hand.
+     */
+    settled(): Promise<void>;
+    /** Stop the session's timers. Call it in `afterEach`. */
+    close(): Promise<void>;
+}
+/**
+ * Start a session on a package.
+ *
+ * Nothing is read from or written to `.seriousgaming-sdk/` but blobs, so a
+ * test does not depend on what somebody last ran `sdk configure` with. Service
+ * callbacks are stubbed unless `services: 'platform'` is passed, so a test
+ * runs offline.
+ *
+ * Pass the engine's generated `Context` and `SharedContext` to type what it
+ * reads back and what it writes.
+ *
+ * @example
+ * ```ts
+ * import type { Context, SharedContext } from '../../engine/types';
+ *
+ * const session = await createTestSession<Context, SharedContext>({ packagePath, teams: 2 });
+ * expect((await session.setData(0, { price: { Price: 12 } })).ok).toBe(true);
+ * expect((await session.tick()).ok).toBe(true);
+ * expect(session.team(0).context.sales.Sales).toBeGreaterThan(0);
+ * await session.close();
+ * ```
+ */
+export declare function createTestSession<Context = UntypedContext, Shared = UntypedContext>(options: TestSessionOptions): Promise<TestSession<Context, Shared>>;