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

package/dist/dev/console/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Serious Gaming</title>
+      <script type="module" crossorigin src="/assets/index-DgFglsnA.js"></script>
+    </head>
+    <body>
+        <div id="root"></div>
+    </body>
+</html>

package/dist/dev/console-path.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where the built console is, from wherever the shell is running.
+ *
+ * One mode, not three. The old dev server could serve its UI from source
+ * through a second Vite, from a build, or from a build forced by `SG_E2E=1`,
+ * and the three disagreed: source mode duplicated React across the linked SDK
+ * boundary and died on its first hook, so the tests forced the built bundle and
+ * therefore never exercised what a developer saw. The console is always the
+ * build, so there is nothing to diverge.
+ */
+export interface ConsoleLocation {
+    /** Directory holding `index.html` and its assets. */
+    path: string;
+    /** False when nothing has been built yet. */
+    built: boolean;
+}
+export declare function resolveConsolePath(dirname: string, filename: string, fileExists?: (path: string) => boolean): ConsoleLocation;
+/** What to tell someone whose console has not been built. */
+export declare const MISSING_CONSOLE_MESSAGE: string;

package/dist/dev/lockfile.d.ts

@@ -0,0 +1,124 @@
+/**
+ * How a CLI command finds the running session.
+ *
+ * A lock file, not a state file. It is written once at startup and removed at
+ * shutdown, never mutated while the server runs, and nothing watches it. That
+ * distinction is the whole point: `state.json` was two processes sharing a
+ * session through a mutable file, which is a shared-memory channel with no
+ * lock, and the own-write guards and debounced writers in the old dev server
+ * were patches over having two writers. Here the server owns the session and
+ * every other process is a client of it, so the only thing on disk is an
+ * address, and enough about who wrote it to tell whether it still holds.
+ */
+/**
+ * Where runtime state goes instead of the package's `.seriousgaming-sdk/`.
+ *
+ * A lock is runtime state, not project content: a container restored from a
+ * snapshot brings back the package directory, and with it a lock naming a
+ * process from before the snapshot (#640).
+ */
+export declare const DEV_STATE_DIR_ENV_VAR = "SERIOUSGAMING_DEV_STATE_DIR";
+export interface SessionLock {
+    /** Process holding the session. */
+    pid: number;
+    port: number;
+    /** ISO-8601, for a human reading a stale file. */
+    startedAt: string;
+    /** The tools version that started the server. */
+    toolsVersion: string;
+    /** The real path of the CLI entry point that started the server. */
+    toolsPath: string;
+    /** The machine the server runs on: a pid means nothing on another. */
+    hostname: string;
+    /** Answered by the server's `/api/session`, so a reused port is not taken for it. */
+    instanceId: string;
+    /** True when a CLI command started the server, rather than a person in a terminal. */
+    background: boolean;
+}
+/** Why a lock on disk does not name a running session. */
+export type StaleReason = 'unreadable' | 'process-gone' | 'this-process' | 'other-host' | 'not-answering' | 'other-instance';
+export type LockInspection = {
+    status: 'none';
+} | {
+    status: 'live';
+    lock: SessionLock;
+} | {
+    status: 'unresponsive';
+    lock: SessionLock;
+} | {
+    status: 'stale';
+    reason: StaleReason;
+};
+/**
+ * What a port answered when asked who it is: the instance id it reported,
+ * `null` for a server that answered without one, `'refused'` when nothing is
+ * listening, and `'unknown'` when it did not answer in time.
+ */
+export type ProbeAnswer = string | null | 'refused' | 'unknown';
+export interface ReadLockOptions {
+    /** How to ask a port who it is. A real request to `/api/session` by default. */
+    probe?: (port: number) => Promise<ProbeAnswer>;
+    /**
+     * What to do with a server that holds the lock but does not answer:
+     * `'throw'` (the default) refuses with `DEV_SERVER_UNRESPONSIVE`, and
+     * `'accept'` returns its lock, for a caller that means to stop it or is
+     * waiting for it to come up.
+     */
+    unresponsive?: 'throw' | 'accept';
+}
+export declare function lockFilePath(packagePath: string, env?: NodeJS.ProcessEnv): string;
+export declare function writeLockFile(packagePath: string, details: {
+    port: number;
+    instanceId: string;
+    background?: boolean;
+}): Promise<void>;
+export declare function removeLockFile(packagePath: string, instanceId?: string): Promise<void>;
+/** A fresh id for a server to write into its lock and answer with. */
+export declare function newInstanceId(): string;
+/**
+ * The running session, or null.
+ *
+ * A lock that names no running session is removed, so the next `sdk dev`
+ * starts rather than reporting a server that is not there: see
+ * {@link inspectLockFile} for what counts.
+ */
+export declare function readLockFile(packagePath: string, options?: ReadLockOptions): Promise<SessionLock | null>;
+/**
+ * Whether the lock on disk names a running session, and if not, why not.
+ *
+ * A pid that exists is not enough. A server killed with SIGKILL never removed
+ * its file, and in a container restored from a snapshot the pid it names is
+ * often reused, frequently by the new dev server itself, which then reported
+ * itself as already running and exited (#640). So the lock is stale when:
+ *
+ * - its process is gone;
+ * - its pid is this process, and this process did not write it;
+ * - it was written on another machine;
+ * - its port refuses the connection, or answers as another instance.
+ *
+ * A port that accepts but does not answer in time is `unresponsive`, neither
+ * live nor stale. The probe is answered without waiting for the session's
+ * queue, so a server busy in a long tick still answers it; one that does not
+ * has its event loop blocked, almost always by logic stuck in synchronous
+ * code. Attaching to it would hang the command, and removing its lock would
+ * leave the next one starting a second server beside it, so the lock is kept
+ * for `sdk dev stop`.
+ */
+export declare function inspectLockFile(packagePath: string, options?: ReadLockOptions): Promise<LockInspection>;
+/** Ask the server on `port` which instance it is. */
+export declare function probeInstance(port: number, options?: {
+    timeoutMs?: number;
+}): Promise<ProbeAnswer>;
+/**
+ * The lock on disk as written, without asking whether it still holds: for a
+ * caller waiting on a particular server to let go of it.
+ */
+export declare function lockOnDisk(packagePath: string): Promise<SessionLock | null>;
+/**
+ * Whether a process exists, without signalling it.
+ *
+ * `kill(pid, 0)` performs the permission checks and reports whether the target
+ * exists, and sends nothing. `EPERM` means it exists and belongs to somebody
+ * else, which still counts as alive.
+ */
+export declare function isAlive(pid: number): boolean;

package/dist/dev/package-watcher.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Watches a package for the edits a running session has to pick up.
+ *
+ * UI source is Vite's business and is hot-replaced there. What is left is the
+ * logic the executor caches and the bundle files configuration is resolved
+ * from, and neither reloads on its own.
+ */
+export type PackageChange = 'logic' | 'bundles' | 'manifest';
+/** What an edit to `path` means for a running session, or null for nothing. */
+export declare function classifyChange(packagePath: string, path: string): PackageChange | null;
+/** Whether a new directory at `path` may hold something a session runs. */
+export declare function classifyDirectory(packagePath: string, path: string): boolean;
+export interface PackageWatcher {
+    close(): Promise<void>;
+}
+/**
+ * Watch `packagePath`, calling `onChange` once per kind of change after a burst
+ * of writes settles. Resolves once the watches are delivering events, so an
+ * edit made after it is always seen.
+ */
+export declare function watchPackage(packagePath: string, onChange: (change: PackageChange) => void, debounceMs?: number): Promise<PackageWatcher>;

package/dist/dev/routes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The HTTP surface: a state read, a command write, and the files a game needs.
+ *
+ * The server this replaces had 38 routes, most of which were one slice of
+ * session state each (`/api/context`, `/api/teams`, `/api/history`,
+ * `/api/locale`, `/api/configuration`, …) and each of which a client had to
+ * fetch and reassemble. There is one state route here, answering the §20
+ * projection, and one command route. What is left is genuinely files: bundles,
+ * blobs, scenario assets, shared assets, and guide content.
+ */
+import type { RunKind } from '@seriousgaming/sdk';
+import type { MutationResult } from '@seriousgaming/sdk/projection';
+import express from 'express';
+import type { Command } from '../core/protocol';
+import type { Session } from '../core/session';
+export interface RouteDeps {
+    session: Session;
+    /**
+     * The run a request named, started if it is the walkthrough (§5.7).
+     *
+     * Only the run-scoped routes go through this. Everything about the
+     * *package* — its surfaces, scenarios, locales, guide and assets — is the
+     * same whichever run is asking, and reads `session` directly.
+     */
+    runFor: (run: RunKind) => Promise<Session>;
+    /** Throw the walkthrough away and start it again at tick 0 (§5.7). */
+    resetWalkthrough: () => Promise<Session>;
+    /** A command that rebuilds the walkthrough, settled as a mutation (§12.5). */
+    settleWalkthroughReset: (command: Command) => Promise<MutationResult>;
+    packagePath: string;
+    vitePort: () => number;
+    /** The origin bundles are served from, as seen by a client that reached `host`. */
+    assetOrigin: (host: string | undefined) => string;
+    /** This server, as its lock names it, so a reused port is not taken for it. */
+    instanceId: string;
+    /** What the server could not apply live to a run, for the CLI to say (#640). */
+    notices: (run: Session) => Array<{
+        code: string;
+        message: string;
+    }>;
+}
+export declare function registerRoutes(app: express.Application, deps: RouteDeps): void;
+/** Where the reads a frame makes are mounted, on one origin or the other. */
+declare const ASSET_PATHS: {
+    readonly '/api': {
+        readonly blob: "/api/blobs/:blobId";
+        readonly scenario: "/api/scenario/assets/*path";
+        readonly shared: "/api/shared/assets/*path";
+        readonly redeem: "/api/asset-auth/redeem";
+    };
+    readonly '/assets': {
+        readonly blob: "/assets/blobs/:blobId";
+        readonly scenario: "/assets/scenario/*path";
+        readonly shared: "/assets/shared/*path";
+        readonly redeem: "/assets/auth/redeem";
+    };
+};
+/**
+ * The reads a frame makes directly: blobs, scenario assets, shared assets,
+ * and the §16.4 redeem.
+ *
+ * Mounted on the asset origin, beside the bundles, so a frame reaches them as
+ * its own origin under `connect-src 'self'` (§16.5). The same routes stay on
+ * the console's origin under `/api` for the CLI and for the console itself.
+ */
+export declare function registerAssetRoutes(app: express.Application, deps: Pick<RouteDeps, 'session' | 'packagePath'>, prefix: keyof typeof ASSET_PATHS): void;
+export {};

package/dist/dev/shell.d.ts

@@ -0,0 +1,260 @@
+/**
+ * The transport around a {@link Session}, and no state of its own.
+ *
+ * Two origins. The console's serves the console, the API and two sockets: the
+ * operator feed, which carries the whole projection, and the viewer feed,
+ * which carries only what one person's page is owed. The asset origin serves
+ * game UI bundles, through Vite in middleware mode, and the files a frame
+ * reads. Keeping the bundles off the console's origin is what stops a game's
+ * own code from calling the API the console calls: `connect-src 'self'` would
+ * otherwise admit it, and a same-origin frame can reach into the page besides.
+ *
+ * Everything here is translation. A command arrives as JSON, goes to the
+ * session, and its result goes back; the session's events are broadcast as
+ * they come. Nothing in this file decides anything about a game, which is what
+ * makes the thing it wraps testable without it.
+ */
+import type { RunKind } from '@seriousgaming/sdk';
+import type { MutationResult } from '@seriousgaming/sdk/projection';
+import type { Command } from '../core/protocol';
+import { Session, type SessionOptions } from '../core/session';
+export interface ShellOptions extends SessionOptions {
+    port?: number;
+    /** Port the Vite HMR socket binds to. Defaults to `port + 1`. */
+    vitePort?: number;
+    /**
+     * Port of the asset origin, which serves bundles and the files a frame
+     * reads. Defaults to the next free port after the HMR socket's.
+     */
+    assetPort?: number;
+    /**
+     * Skip the lock file: neither refuse to start beside a running server nor
+     * become the one CLI commands find. For tests, and `sdk dev --isolated`.
+     */
+    anonymous?: boolean;
+    /** Recorded in the lock: a CLI command started this server, not a person. */
+    background?: boolean;
+    /**
+     * Run beside the developer's own server without touching anything of
+     * theirs: no lock (`anonymous`), configuration from the package alone
+     * (`inMemory`), and blobs in a temporary directory removed at stop. For
+     * test runs and recordings (#640).
+     */
+    isolated?: boolean;
+    /**
+     * Listen on every interface, so a phone or tablet can open a surface.
+     * Loopback only otherwise: on a shared network, anyone on it could reach
+     * the session, its API and the package's files.
+     */
+    lan?: boolean;
+}
+/**
+ * Something the server could not apply live, kept until it no longer holds so
+ * the next CLI command can say it (#640). A log line alone was lost whenever
+ * nobody was reading the server's output, which for a server a command
+ * started in the background is always.
+ */
+export interface DevNotice {
+    /**
+     * `SETTINGS_STALE`, `RELOAD_FAILED` or `CAPABILITY_SEEDED`, or the code of
+     * an error `sdk build` would refuse the package for.
+     */
+    code: string;
+    message: string;
+    /** Set on an error `sdk build` would refuse the package for. */
+    build?: true;
+}
+export declare class DevShell {
+    private readonly app;
+    /** The asset origin: bundles, and the files a frame reads (§16.4). */
+    private readonly assetApp;
+    private readonly session;
+    /**
+     * The walkthrough run (§5.7), built the first time somebody opens one.
+     *
+     * Lazy because a second `Session` builds a second `GameExecutor`, which
+     * loads the package again: a dev server nobody points at a walkthrough
+     * should not pay for one. The URL is always there regardless, which is what
+     * `/walkthrough` being addressable means.
+     */
+    private walkthrough;
+    /** Serialises concurrent first opens so they share one run, not two. */
+    private walkthroughStarting;
+    /** The walkthrough's surface storage key, kept across a reset (§12.2). */
+    private walkthroughKey;
+    /** Which run each socket is watching, so an event reaches only its own. */
+    private readonly socketRuns;
+    /** The participant an operator page says it is showing, where it shows one. */
+    private readonly socketPresence;
+    private readonly options;
+    private server;
+    private assetServer;
+    private sockets;
+    /** One socket per viewer page, each carrying only what that page is owed. */
+    private viewSockets;
+    private readonly views;
+    /** Teams processing a round, per run (§12.4.4); `-1` is the cohort. */
+    private readonly processing;
+    private vite;
+    private watcher;
+    /** Why surfaces cannot be served, when Vite could not start. */
+    private viteFailure;
+    /** Serialises the first requests for a surface so they share one Vite. */
+    private viteStarting;
+    private port;
+    private vitePort;
+    private assetPort;
+    /** Written into the lock and answered by `/api/session`, so a reused port is not taken for this server. */
+    readonly instanceId: string;
+    /** Why the last edit could not be loaded, until an edit loads. */
+    private reloadFailure;
+    /** Capabilities adopted live with their schema defaults, until Init next runs. */
+    private readonly seeded;
+    /** The errors `sdk build` would refuse the package for, as it last stood on disk. */
+    private buildErrors;
+    /** Which validation is the latest, so an older one finishing late is dropped. */
+    private validations;
+    /** Where an isolated server keeps blobs, and how to stop doing so. */
+    private isolatedBlobs;
+    constructor(options: ShellOptions);
+    start(): Promise<void>;
+    private releaseIsolatedBlobs;
+    private listen;
+    stop(): Promise<void>;
+    /**
+     * Pick up an edit. The manifest is one more file the package is resolved
+     * from, so it reloads as a bundle does: what a running session can adopt
+     * it adopts, and the rest waits for a re-initialisation (#640).
+     */
+    private onPackageChange;
+    private applyChange;
+    /**
+     * Run the static validation `sdk build --validate-only` runs, and say so
+     * when its errors change.
+     *
+     * A package `build` refuses still runs here: the session checks at run
+     * time what it cannot run correctly, and refusing play over the rest, an
+     * unresolved read or a missing entrypoint, would stop an author part way
+     * through an edit that spans several files. What it must not do is run
+     * silently, so the errors are printed, kept as notices every CLI command
+     * repeats, and shown on the console.
+     */
+    private validate;
+    /** Keep what a reload could not apply, for the next command to be told. */
+    private record;
+    /**
+     * Everything this server could not apply live to `run`, as it stands now:
+     * edits waiting for a re-initialisation, an edit that did not load, and
+     * capabilities Init has not run for. Pending edits are the run's own; the
+     * other two are about the package, so only the session reports them.
+     */
+    notices(run?: Session): DevNotice[];
+    /** Every interface with `lan`, loopback otherwise, as listen options. */
+    private get bindHost();
+    /** Whether other machines on the network can reach this server. */
+    get reachableFromNetwork(): boolean;
+    /** Where the console is, once listening. */
+    get url(): string;
+    /** Where bundles are served from, once listening. */
+    get assetUrl(): string;
+    /**
+     * The asset origin as a client that reached `host` must name it: the same
+     * host, the asset port. A browser on another machine reached us by an
+     * address `localhost` would not resolve to on its side.
+     */
+    assetOrigin(host: string | undefined): string;
+    /** The console's own origin, as a client that reached `host` names it. */
+    private consoleOrigin;
+    /** The session this shell wraps, for tests and for the CLI in-process path. */
+    get runtime(): Session;
+    /**
+     * The walkthrough run, started on first use.
+     *
+     * One team and tick 0 are the walkthrough's shape (§5.7), not a default the
+     * caller may vary, so they are fixed here rather than taken from options.
+     */
+    walkthroughRun(): Promise<Session>;
+    /**
+     * A command that rebuilds the walkthrough, as a settled mutation.
+     *
+     * The host owns it rather than a session, because it replaces the run a
+     * session command would have been addressed to. A `resetWalkthrough` with
+     * no walkthrough yet is denied rather than creating one (§12.5): opening
+     * the link is what creates the run, and a reset has nothing to rewind.
+     */
+    settleWalkthroughReset(command: Command): Promise<MutationResult>;
+    /** The run a request or socket named, started if it is the walkthrough. */
+    runFor(run: RunKind): Promise<Session>;
+    /**
+     * Throw the walkthrough away and start a fresh one.
+     *
+     * A walkthrough always begins at tick 0 (§5.7), so replacing the run *is*
+     * the reset: there is no earlier state to rewind to and nothing to unpick.
+     */
+    resetWalkthrough(): Promise<Session>;
+    private configure;
+    /**
+     * The asset origin: game bundles, through Vite, and the files a frame
+     * reads, all under the bundle policy and nothing under `/api`.
+     */
+    private configureAssets;
+    /**
+     * Vite, started the first time something asks for a surface (#320).
+     *
+     * Not at start-up: a session a CLI command started in the background, and
+     * most of the servers the test suites start, never serve a surface, and a
+     * Vite server each was both the start-up cost and most of the exposure to
+     * rolldown's native crash.
+     */
+    private ensureVite;
+    private createVite;
+    private attachSockets;
+    private receive;
+    /** What one viewer page is owed, now. */
+    private viewOf;
+    /**
+     * Send a viewer its page, unless it is exactly what the page already has.
+     *
+     * Most events change nothing a given page is owed: a write by one team, a
+     * round another team is processing, a tick's start and end on a page that
+     * shows neither. Re-sending the whole batch each time was most of the
+     * traffic, and every byte of it was discarded by the frame.
+     */
+    private sendView;
+    /**
+     * Pass a session event on to the viewer pages it concerns, and no further.
+     *
+     * A viewer is never sent an operator error, a refusal meant for another
+     * team, or a round another team is processing (§12.4.4, §15).
+     */
+    /**
+     * Tell a run who has a surface open (§13.2).
+     *
+     * A participant is connected while any page bound to them is: a viewer page
+     * the server resolved to them, or an operator page that said it shows them.
+     * Only a run that exists is told, since asking for the walkthrough is what
+     * builds it.
+     */
+    private syncPresence;
+    private updateViews;
+    /**
+     * Act on a frame's request from a viewer page.
+     *
+     * The page forwards what its frame sent, unmapped, and the host maps it
+     * against its own resolution of who the page is for, so no page can name
+     * somebody else, another surface, or a command its surface may not send.
+     */
+    private receiveView;
+    private broadcast;
+    /**
+     * Say what went wrong where the author is actually looking.
+     *
+     * Session errors used to reach the WebSocket and nothing else, so a refused
+     * tick left the console's drawer badge as the only sign: the clock did not
+     * move, the browser console was clean, and the message naming the cause sat
+     * behind a keystroke nobody had a reason to press. An undeclared write cost
+     * a reported hour of bisection for a one-line fix, and the message that
+     * would have ended it in a minute already existed.
+     */
+    private report;
+}

package/dist/dev/surfaces.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What the host knows about each surface it can mount.
+ *
+ * A table rather than a component per kind. The old dev server had four
+ * near-identical preview components and a route each; the difference between
+ * them is which bundle they mount, which declarations gate them, and which
+ * messages they are entitled to, all of which are data.
+ */
+import type { ResolvedPackageManifest } from '@seriousgaming/sdk';
+import type { SurfaceKind } from '../host';
+/** A bundle the host can serve, resolved from what the package declares. */
+export interface MountableSurface {
+    kind: SurfaceKind;
+    /** Identifier of the bundle, which is the slot for a singular resource. */
+    identifier: string;
+    /** URL the iframe loads, relative to {@link MountableSurface.origin}. */
+    src: string;
+    /**
+     * Origin the bundle is served from. Set by the route that answers a
+     * client, since it depends on the host the client reached; absent, the
+     * bundle is on the page's own origin.
+     */
+    origin?: string;
+    /** Capabilities the bundle reads, for the §7.4 projection. */
+    reads: string[];
+    /** Capabilities it writes. */
+    writes: string[];
+    /** Endpoints it may invoke (§6.12). */
+    endpoints: string[];
+    /** Capabilities it reads from every team, not only its own (§6.2, §12.4.1). */
+    crossTeamReads: string[];
+    /** Whether it may ask for every team's roster (§6.3, §12.5). */
+    crossTeamParticipants: boolean;
+    /**
+     * Settings resources it is sent (§8): those it lists in `settings`, or for
+     * the setup UI and the scenario editor, those it `configures`.
+     */
+    settings: string[];
+}
+/** Every surface this package can mount: one per slot it fills. */
+export declare function mountableSurfaces(config: ResolvedPackageManifest | null): MountableSurface[];

package/dist/dev/tools-identity.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Which build of the tools this process is, so a CLI command can tell a dev
+ * server started by another build from one started by its own (#640).
+ *
+ * A server outlives the tools that started it: an upgrade, a rebuild of a
+ * linked checkout or a switch of branch leaves it running code the CLI no
+ * longer is, and its answers drift from what the files on disk say without
+ * either side noticing. The version alone cannot tell two builds of one
+ * checkout apart, so the entry point's real path is recorded beside it.
+ */
+export interface ToolsIdentity {
+    /** `version` from the tools' own package.json. */
+    version: string;
+    /** The real path of the CLI entry point: `dist/cli.js`, or `cli/cli.ts` from source. */
+    path: string;
+}
+export declare function toolsIdentity(): ToolsIdentity;
+/**
+ * From source this module sits at `cli/dev/`, two levels below the package
+ * root. Bundled, it is inlined into a file directly inside `dist/`, beside
+ * `cli.js`, with the package root one level up.
+ */
+export declare function readIdentity(filename: string): ToolsIdentity;