@tui-sandbox/library 2.0.2 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.2.0](https://github.com/mikavilpas/tui-sandbox/compare/library-v2.1.0...library-v2.2.0) (2024-11-03)
+
+
+### Features
+
+* check that neovim is available before starting the server ([#107](https://github.com/mikavilpas/tui-sandbox/issues/107)) ([bcc817f](https://github.com/mikavilpas/tui-sandbox/commit/bcc817fe25a9811cdd7b1832f6811fa4f92974bd))
+
+## [2.1.0](https://github.com/mikavilpas/tui-sandbox/compare/library-v2.0.2...library-v2.1.0) (2024-11-02)
+
+
+### Features
+
+* client connects to server using server-sent events ([e07765e](https://github.com/mikavilpas/tui-sandbox/commit/e07765e20dba6394538cf29b1b16463b62ba4b7a))
+
 ## [2.0.2](https://github.com/mikavilpas/tui-sandbox/compare/library-v2.0.1...library-v2.0.2) (2024-10-20)
 
 

package/dist/src/client/neovim-client.d.ts

@@ -1,4 +1,5 @@
 import "@xterm/xterm/css/xterm.css";
+import type { Except } from "type-fest";
 import type { StartNeovimGenericArguments } from "../server/neovim/NeovimApplication.ts";
 import type { TestDirectory } from "../server/types.ts";
 import "./style.css";
@@ -8,5 +9,5 @@ export declare class NeovimClient {
     private readonly terminal;
     private readonly trpc;
     constructor(app: HTMLElement);
-    startNeovim(args: StartNeovimGenericArguments): Promise<TestDirectory>;
+    startNeovim(args: Except<StartNeovimGenericArguments, "terminalDimensions">): Promise<TestDirectory>;
 }

package/dist/src/client/neovim-client.js

@@ -1,4 +1,4 @@
-import { createTRPCClient, createWSClient, wsLink } from "@trpc/client";
+import { createTRPCClient, httpBatchLink, splitLink, unstable_httpSubscriptionLink } from "@trpc/client";
 import "@xterm/xterm/css/xterm.css";
 import "./style.css";
 import { getTabId, startTerminal } from "./websocket-client.js";
@@ -8,9 +8,18 @@ export class NeovimClient {
     terminal;
     trpc;
     constructor(app) {
-        const wsClient = createWSClient({ url: `ws://localhost:3000`, WebSocket });
         const trpc = createTRPCClient({
-            links: [wsLink({ client: wsClient })],
+            links: [
+                splitLink({
+                    condition: operation => operation.type === "subscription",
+                    true: unstable_httpSubscriptionLink({
+                        url: "http://localhost:3000",
+                    }),
+                    false: httpBatchLink({
+                        url: "http://localhost:3000",
+                    }),
+                }),
+            ],
         });
         this.trpc = trpc;
         this.tabId = getTabId();

package/dist/src/server/TestServer.d.ts

@@ -4,5 +4,5 @@ import type { TestServerConfig } from "./updateTestdirectorySchemaFile";
 export declare class TestServer {
     private readonly port;
     constructor(port: number);
-    startAndRun<TRouter extends AnyTRPCRouter>(appRouter: TRouter, config: TestServerConfig): Promise<void>;
+    startAndRun(appRouter: AnyTRPCRouter, config: TestServerConfig): Promise<void>;
 }

package/dist/src/server/TestServer.js

@@ -1,48 +1,39 @@
-import { applyWSSHandler } from "@trpc/server/adapters/ws";
+import { createHTTPServer } from "@trpc/server/adapters/standalone";
 import "core-js/proposals/async-explicit-resource-management";
+import cors from "cors";
 import { once } from "events";
-import { WebSocketServer } from "ws";
-import { createContext } from "./connection/trpc";
 import { updateTestdirectorySchemaFile } from "./updateTestdirectorySchemaFile";
 export class TestServer {
     port;
     constructor(port) {
         this.port = port;
     }
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
     async startAndRun(appRouter, config) {
         console.log("🚀 Server starting");
         await updateTestdirectorySchemaFile(config);
-        const wss = new WebSocketServer({ port: this.port });
-        const handler = applyWSSHandler({
-            wss,
+        const server = createHTTPServer({
             router: appRouter,
-            createContext,
-            // Enable heartbeat messages to keep connection open (disabled by default)
-            keepAlive: {
-                enabled: true,
-                // server ping message interval in milliseconds
-                pingMs: 30_000,
-                // connection is terminated if pong message is not received in this many milliseconds
-                pongWaitMs: 5000,
-            },
+            createContext: () => ({}),
+            middleware: cors({
+                origin: "*",
+            }),
         });
-        wss.on("connection", socket => {
-            console.log(`➕➕ Connection (${wss.clients.size})`);
+        server.listen(this.port);
+        server.on("connection", socket => {
+            console.log(`➕➕ Connection`);
             socket.once("close", () => {
-                console.log(`➖➖ Connection (${wss.clients.size})`);
+                console.log(`➖➖ Connection`);
             });
         });
-        console.log(`✅ WebSocket Server listening on ws://localhost:${this.port}`);
+        console.log(`✅ Server listening on ws://localhost:${this.port}`);
         await Promise.race([once(process, "SIGTERM"), once(process, "SIGINT")]);
         console.log("Shutting down...");
-        handler.broadcastReconnectNotification();
-        wss.close(error => {
+        server.close(error => {
             if (error) {
-                console.error("Error closing WebSocket server", error);
+                console.error("Error closing server", error);
                 process.exit(1);
             }
-            console.log("WebSocket server closed");
+            console.log("Server closed");
             process.exit(0);
         });
     }

package/dist/src/server/connection/trpc.d.ts

@@ -1,29 +1,21 @@
-import type { CreateWSSContextFnOptions } from "@trpc/server/adapters/ws";
-import type { Socket } from "net";
-import type { WebSocket } from "ws";
-export type Connection = {
-    clientId: WebSocket;
-    socket: Socket;
-};
-export declare function createContext(opts: CreateWSSContextFnOptions): Connection;
 export declare const trpc: {
     _config: import("@trpc/server/unstable-core-do-not-import").RootConfig<{
-        ctx: Connection;
+        ctx: object;
         meta: object;
         errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
         transformer: false;
     }>;
-    procedure: import("@trpc/server/unstable-core-do-not-import").ProcedureBuilder<Connection, object, object, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, false>;
-    middleware: <$ContextOverrides>(fn: import("@trpc/server/unstable-core-do-not-import").MiddlewareFunction<Connection, object, object, $ContextOverrides, unknown>) => import("@trpc/server/unstable-core-do-not-import").MiddlewareBuilder<Connection, object, $ContextOverrides, unknown>;
+    procedure: import("@trpc/server/unstable-core-do-not-import").ProcedureBuilder<object, object, object, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, typeof import("@trpc/server/unstable-core-do-not-import").unsetMarker, false>;
+    middleware: <$ContextOverrides>(fn: import("@trpc/server/unstable-core-do-not-import").MiddlewareFunction<object, object, object, $ContextOverrides, unknown>) => import("@trpc/server/unstable-core-do-not-import").MiddlewareBuilder<object, object, $ContextOverrides, unknown>;
     router: {
         <TInput extends import("@trpc/server").RouterRecord>(input: TInput): import("@trpc/server/unstable-core-do-not-import").BuiltRouter<{
-            ctx: Connection;
+            ctx: object;
             meta: object;
             errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
             transformer: false;
         }, TInput>;
         <TInput extends import("@trpc/server/unstable-core-do-not-import").CreateRouterOptions>(input: TInput): import("@trpc/server/unstable-core-do-not-import").BuiltRouter<{
-            ctx: Connection;
+            ctx: object;
             meta: object;
             errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
             transformer: false;
@@ -31,12 +23,12 @@ export declare const trpc: {
     };
     mergeRouters: typeof import("@trpc/server/unstable-core-do-not-import").mergeRouters;
     createCallerFactory: <TRecord extends import("@trpc/server").RouterRecord>(router: Pick<import("@trpc/server/unstable-core-do-not-import").Router<{
-        ctx: Connection;
+        ctx: object;
         meta: object;
         errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
         transformer: false;
     }, TRecord>, "_def">) => import("@trpc/server/unstable-core-do-not-import").RouterCaller<{
-        ctx: Connection;
+        ctx: object;
         meta: object;
         errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
         transformer: false;

package/dist/src/server/connection/trpc.js

@@ -1,5 +1,2 @@
 import { initTRPC } from "@trpc/server";
-export function createContext(opts) {
-    return { clientId: opts.res, socket: opts.req.socket };
-}
 export const trpc = initTRPC.context().create();

package/dist/src/server/neovim/NeovimApplication.d.ts

@@ -12,11 +12,12 @@ export type StartNeovimGenericArguments = {
     };
     startupScriptModifications?: string[];
 };
-export declare class NeovimApplication extends DisposableSingleApplication {
+export declare class NeovimApplication {
     private readonly testEnvironmentPath;
+    readonly application: DisposableSingleApplication;
     private testDirectory;
     readonly events: EventEmitter;
-    constructor(testEnvironmentPath: string);
+    constructor(testEnvironmentPath: string, application?: DisposableSingleApplication);
     /**
      * Kill the current application and start a new one with the given arguments.
      */

package/dist/src/server/neovim/NeovimApplication.js

@@ -1,16 +1,18 @@
+import assert from "assert";
 import { exec } from "child_process";
 import EventEmitter from "events";
 import { existsSync } from "fs";
 import path from "path";
 import { DisposableSingleApplication } from "../utilities/DisposableSingleApplication";
 import { TerminalApplication } from "../utilities/TerminalApplication";
-export class NeovimApplication extends DisposableSingleApplication {
+export class NeovimApplication {
     testEnvironmentPath;
+    application;
     testDirectory;
     events;
-    constructor(testEnvironmentPath) {
-        super();
+    constructor(testEnvironmentPath, application = new DisposableSingleApplication()) {
         this.testEnvironmentPath = testEnvironmentPath;
+        this.application = application;
         this.events = new EventEmitter();
     }
     /**
@@ -42,19 +44,25 @@ export class NeovimApplication extends DisposableSingleApplication {
             }
         }
         const stdout = this.events;
-        this.application = TerminalApplication.start({
-            command: "nvim",
-            args: neovimArguments,
-            cwd: this.testEnvironmentPath,
-            env: process.env,
-            dimensions: startArgs.terminalDimensions,
-            onStdoutOrStderr(data) {
-                stdout.emit("stdout", data);
-            },
+        await this.application.startNextAndKillCurrent(async () => {
+            return TerminalApplication.start({
+                command: "nvim",
+                args: neovimArguments,
+                cwd: this.testEnvironmentPath,
+                env: process.env,
+                dimensions: startArgs.terminalDimensions,
+                onStdoutOrStderr(data) {
+                    data;
+                    stdout.emit("stdout", data);
+                },
+            });
         });
+        const processId = this.application.processId();
+        assert(processId !== undefined, "Neovim was started without a process ID. This is a bug - please open an issue.");
+        console.log(`🚀 Started Neovim instance ${processId}`);
     }
     async [Symbol.asyncDispose]() {
-        await super.killCurrent();
+        await this.application[Symbol.asyncDispose]();
         if (this.testDirectory) {
             exec(`rm -rf ${this.testDirectory.rootPathAbsolute}`);
         }

package/dist/src/server/neovim/environment/createTempDir.test.js

@@ -2,6 +2,7 @@ import fs, { rmdirSync } from "fs";
 import nodePath from "path";
 import { expect, it } from "vitest";
 import { createTempDir } from "./createTempDir";
+vi.spyOn(console, "log").mockImplementation(vi.fn());
 class TempDirectory {
     path;
     constructor(path) {

package/dist/src/server/neovim/index.d.ts

@@ -1,11 +1,10 @@
-import type { Observable } from "@trpc/server/observable";
 import type { TestDirectory } from "../types";
 import type { TestServerConfig } from "../updateTestdirectorySchemaFile";
 import type { TabId } from "../utilities/tabId";
 import type { StartNeovimGenericArguments } from "./NeovimApplication";
 export declare function onStdout(options: {
     client: TabId;
-}, testEnvironmentPath: string): Observable<string, unknown>;
+}, signal: AbortSignal | undefined, testEnvironmentPath: string): Promise<AsyncGenerator<string, void, unknown>>;
 export declare function start(options: StartNeovimGenericArguments, tabId: TabId, config: TestServerConfig): Promise<TestDirectory>;
 export declare function sendStdin(options: {
     tabId: TabId;

package/dist/src/server/neovim/index.js

@@ -1,40 +1,34 @@
-import { observable } from "@trpc/server/observable";
 import assert from "assert";
+import { convertEventEmitterToAsyncGenerator } from "../utilities/generator";
 import { createTempDir } from "./environment/createTempDir";
 import { NeovimApplication } from "./NeovimApplication";
 const neovims = new Map();
-export function onStdout(options, testEnvironmentPath) {
-    return observable(emit => {
-        const tabId = options.client.tabId;
-        const neovim = neovims.get(tabId) ?? new NeovimApplication(testEnvironmentPath);
-        if (neovims.get(tabId) === undefined) {
-            neovims.set(tabId, neovim);
-        }
-        const send = (data) => {
-            assert(typeof data === "string");
-            emit.next(data);
-        };
-        neovim.events.on("stdout", send);
-        return () => {
-            neovim.events.off("stdout", send);
+export async function onStdout(options, signal, testEnvironmentPath) {
+    const tabId = options.client.tabId;
+    const neovim = neovims.get(tabId) ?? new NeovimApplication(testEnvironmentPath);
+    if (neovims.get(tabId) === undefined) {
+        neovims.set(tabId, neovim);
+    }
+    const stdout = convertEventEmitterToAsyncGenerator(neovim.events, "stdout");
+    if (signal) {
+        signal.addEventListener("abort", () => {
             void neovim[Symbol.asyncDispose]().finally(() => {
                 neovims.delete(tabId);
             });
-        };
-    });
+        });
+    }
+    return stdout;
 }
 export async function start(options, tabId, config) {
     const neovim = neovims.get(tabId.tabId);
     assert(neovim, `Neovim instance not found for client id ${tabId.tabId}`);
     const testDirectory = await createTempDir(config);
     await neovim.startNextAndKillCurrent(testDirectory, options);
-    const processId = neovim.processId();
-    assert(processId !== undefined, "Neovim was started without a process ID. This is a bug - please open an issue.");
-    console.log(`🚀 Started Neovim instance ${processId}`);
     return testDirectory;
 }
 export async function sendStdin(options) {
     const neovim = neovims.get(options.tabId.tabId);
     assert(neovim !== undefined, `Neovim instance for clientId not found - cannot send stdin. Maybe it's not started yet?`);
-    await neovim.write(options.data);
+    assert(neovim.application, `Neovim application not found for client id ${options.tabId.tabId}. Maybe it's not started yet?`);
+    await neovim.application.write(options.data);
 }

package/dist/src/server/server.d.ts

@@ -5,14 +5,15 @@ import type { TestServerConfig } from "./updateTestdirectorySchemaFile";
  * shuts down */
 declare const autocleanup: AsyncDisposableStack;
 export { autocleanup };
-declare function createAppRouter(config: TestServerConfig): import("@trpc/server/unstable-core-do-not-import").BuiltRouter<{
-    ctx: import("./connection/trpc").Connection;
+/** @private */
+export declare function createAppRouter(config: TestServerConfig): Promise<import("@trpc/server/unstable-core-do-not-import").BuiltRouter<{
+    ctx: object;
     meta: object;
     errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
     transformer: false;
 }, import("@trpc/server/unstable-core-do-not-import").DecorateCreateRouterOptions<{
     neovim: import("@trpc/server/unstable-core-do-not-import").BuiltRouter<{
-        ctx: import("./connection/trpc").Connection;
+        ctx: object;
         meta: object;
         errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
         transformer: false;
@@ -35,13 +36,13 @@ declare function createAppRouter(config: TestServerConfig): import("@trpc/server
             };
             output: import("./types").TestDirectory;
         }>;
-        onStdout: import("@trpc/server/unstable-core-do-not-import").LegacyObservableSubscriptionProcedure<{
+        onStdout: import("@trpc/server").TRPCSubscriptionProcedure<{
             input: {
                 client: {
                     tabId: string;
                 };
             };
-            output: string;
+            output: AsyncGenerator<string, void, unknown>;
         }>;
         sendStdin: import("@trpc/server").TRPCMutationProcedure<{
             input: {
@@ -53,7 +54,7 @@ declare function createAppRouter(config: TestServerConfig): import("@trpc/server
             output: void;
         }>;
     }>;
-}>>;
-export type AppRouter = ReturnType<typeof createAppRouter>;
+}>>>;
+export type AppRouter = Awaited<ReturnType<typeof createAppRouter>>;
 export type RouterInput = inferRouterInputs<AppRouter>;
 export declare function startTestServer(config: TestServerConfig): Promise<TestServer>;

package/dist/src/server/server.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { trpc } from "./connection/trpc";
 import * as neovim from "./neovim";
 import { TestServer } from "./TestServer";
+import { applicationAvailable } from "./utilities/applicationAvailable";
 import { tabIdSchema } from "./utilities/tabId";
 /** Stack for managing resources that need to be disposed of when the server
  * shuts down */
@@ -10,7 +11,12 @@ autocleanup.defer(() => {
     console.log("Closing any open test applications");
 });
 export { autocleanup };
-function createAppRouter(config) {
+/** @private */
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export async function createAppRouter(config) {
+    if (!(await applicationAvailable("nvim"))) {
+        throw new Error("Neovim is not installed. Please install Neovim (nvim).");
+    }
     const appRouter = trpc.router({
         neovim: trpc.router({
             start: trpc.procedure
@@ -34,7 +40,7 @@ function createAppRouter(config) {
                 return neovim.start(options.input.startNeovimArguments, options.input.tabId, config);
             }),
             onStdout: trpc.procedure.input(z.object({ client: tabIdSchema })).subscription(options => {
-                return neovim.onStdout(options.input, config.testEnvironmentPath);
+                return neovim.onStdout(options.input, options.signal, config.testEnvironmentPath);
             }),
             sendStdin: trpc.procedure.input(z.object({ tabId: tabIdSchema, data: z.string() })).mutation(options => {
                 return neovim.sendStdin(options.input);
@@ -45,7 +51,7 @@ function createAppRouter(config) {
 }
 export async function startTestServer(config) {
     const testServer = new TestServer(3000);
-    const appRouter = createAppRouter(config);
+    const appRouter = await createAppRouter(config);
     await testServer.startAndRun(appRouter, config);
     return testServer;
 }

package/dist/src/server/server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/server/server.test.js

@@ -0,0 +1,23 @@
+import { createAppRouter } from "./server";
+import { applicationAvailable } from "./utilities/applicationAvailable";
+vi.mock("./utilities/applicationAvailable");
+const mocked = {
+    applicationAvailable: vi.mocked(applicationAvailable),
+};
+describe("Neovim server", () => {
+    it("complains when neovim is not installed", async () => {
+        await expect(createAppRouter({
+            outputFilePath: "outputFilePath",
+            testEnvironmentPath: "testEnvironmentPath",
+        })).rejects.toThrow("Neovim is not installed. Please install Neovim (nvim).");
+        expect(mocked.applicationAvailable).toHaveBeenCalledWith("nvim");
+    });
+    it("creates a router when neovim is installed", async () => {
+        mocked.applicationAvailable.mockResolvedValue("nvim");
+        await expect(createAppRouter({
+            outputFilePath: "outputFilePath",
+            testEnvironmentPath: "testEnvironmentPath",
+        })).resolves.toBeDefined();
+        expect(mocked.applicationAvailable).toHaveBeenCalledWith("nvim");
+    });
+});

package/dist/src/server/updateTestdirectorySchemaFile.d.ts

@@ -3,4 +3,5 @@ export type TestServerConfig = {
     testEnvironmentPath: string;
     outputFilePath: string;
 };
-export declare function updateTestdirectorySchemaFile({ testEnvironmentPath, outputFilePath, }: TestServerConfig): Promise<void>;
+export type UpdateTestdirectorySchemaFileResult = "updated" | "did-nothing";
+export declare function updateTestdirectorySchemaFile({ testEnvironmentPath, outputFilePath, }: TestServerConfig): Promise<UpdateTestdirectorySchemaFileResult>;

package/dist/src/server/updateTestdirectorySchemaFile.js

@@ -15,5 +15,9 @@ export async function updateTestdirectorySchemaFile({ testEnvironmentPath, outpu
         // because file watchers will trigger on file changes and we don't want to
         // trigger a build if the schema hasn't changed
         writeFileSync(outputFilePath, newSchema);
+        return "updated";
+    }
+    else {
+        return "did-nothing";
     }
 }

package/dist/src/server/updateTestdirectorySchemaFile.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/server/updateTestdirectorySchemaFile.test.js

@@ -0,0 +1,34 @@
+import { readFileSync, writeFileSync } from "fs";
+import { buildTestDirectorySchema } from "./dirtree";
+import { updateTestdirectorySchemaFile } from "./updateTestdirectorySchemaFile";
+vi.mock("fs");
+vi.mock("./dirtree");
+vi.spyOn(console, "log").mockImplementation(vi.fn());
+const mock = {
+    readFileSync: vi.mocked(readFileSync),
+    writeFileSync: vi.mocked(writeFileSync),
+    buildTestDirectorySchema: vi.mocked(buildTestDirectorySchema),
+};
+describe("when the schema has not changed", () => {
+    it("does not write the file", async () => {
+        mock.buildTestDirectorySchema.mockResolvedValue("schema");
+        mock.readFileSync.mockImplementation(() => "schema");
+        const result = await updateTestdirectorySchemaFile({
+            testEnvironmentPath: "path",
+            outputFilePath: "path",
+        });
+        expect(result).toBe("did-nothing");
+    });
+});
+describe("when the schema has changed", () => {
+    it("writes the file", async () => {
+        mock.buildTestDirectorySchema.mockResolvedValue("new schema");
+        mock.readFileSync.mockImplementation(() => "old schema");
+        const result = await updateTestdirectorySchemaFile({
+            testEnvironmentPath: "path",
+            outputFilePath: "path",
+        });
+        expect(result).toBe("updated");
+        expect(mock.writeFileSync).toHaveBeenCalledWith("path", "new schema");
+    });
+});

package/dist/src/server/utilities/DisposableSingleApplication.d.ts

@@ -1,16 +1,14 @@
 import type { TerminalApplication } from "./TerminalApplication";
+export type StartableApplication = Pick<TerminalApplication, "write" | "processId" | "killAndWait">;
 /** A testable application that can be started, killed, and given input. For a
  * single instance of this interface, only a single instance can be running at
- * a time (1 to 1 mapping).
- *
- * @typeParam T The type of context the tests should have, e.g. information
- * about a custom directory that the application is running in.
- *
+ * a time.
  */
-export declare abstract class DisposableSingleApplication implements AsyncDisposable {
-    protected application: TerminalApplication | undefined;
-    killCurrent(): Promise<void>;
+export declare class DisposableSingleApplication implements AsyncDisposable {
+    protected application: StartableApplication | undefined;
+    startNextAndKillCurrent(startNext: () => Promise<StartableApplication>): Promise<void>;
     write(input: string): Promise<void>;
     processId(): number | undefined;
+    /** Kill the current application if it exists. */
     [Symbol.asyncDispose](): Promise<void>;
 }

package/dist/src/server/utilities/DisposableSingleApplication.js

@@ -1,27 +1,27 @@
+import assert from "assert";
 /** A testable application that can be started, killed, and given input. For a
  * single instance of this interface, only a single instance can be running at
- * a time (1 to 1 mapping).
- *
- * @typeParam T The type of context the tests should have, e.g. information
- * about a custom directory that the application is running in.
- *
+ * a time.
  */
 export class DisposableSingleApplication {
     application;
-    async killCurrent() {
-        await this.application?.killAndWait();
+    async startNextAndKillCurrent(startNext) {
+        await this[Symbol.asyncDispose]();
+        this.application = await startNext();
     }
     async write(input) {
-        return this.application?.write(input);
+        assert(this.application, "The application not started yet. It makes no sense to write to it, so this looks like a bug.");
+        this.application.write(input);
     }
     processId() {
         return this.application?.processId;
     }
+    /** Kill the current application if it exists. */
     async [Symbol.asyncDispose]() {
         if (this.processId() === undefined) {
             return;
         }
         console.log(`Killing current application ${this.processId()}...`);
-        await this.killCurrent();
+        await this.application?.killAndWait();
     }
 }

package/dist/src/server/utilities/DisposableSingleApplication.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/server/utilities/DisposableSingleApplication.test.js

@@ -0,0 +1,55 @@
+import { DisposableSingleApplication } from "./DisposableSingleApplication";
+vi.spyOn(console, "log").mockImplementation(vi.fn());
+class TestDisposableSingleApplication extends DisposableSingleApplication {
+    getApplication() {
+        return this.application;
+    }
+}
+const fakeApp = {
+    processId: 123,
+    write: vi.fn(),
+    killAndWait: vi.fn(),
+};
+describe("DisposableSingleApplication", () => {
+    it("has no application when created", () => {
+        const app = new TestDisposableSingleApplication();
+        expect(app.processId()).toBeUndefined();
+        expect(app.getApplication()).toBeUndefined();
+    });
+    it("can start an application", async () => {
+        const app = new TestDisposableSingleApplication();
+        await app.startNextAndKillCurrent(async () => fakeApp);
+        expect(app.processId()).toBe(123);
+        expect(app.getApplication()).toBe(fakeApp);
+    });
+    it("can write to the application", async () => {
+        const app = new TestDisposableSingleApplication();
+        await app.startNextAndKillCurrent(async () => fakeApp);
+        await app.write("hello");
+        expect(fakeApp.write).toHaveBeenCalledWith("hello");
+    });
+    it("fails to write if the application is not started", async () => {
+        // there is no need to support soft failing in the ui, so we do hard
+        // failing to make this error obvious
+        const app = new TestDisposableSingleApplication();
+        await expect(app.write("hello")).rejects.toThrowErrorMatchingInlineSnapshot(`[AssertionError: The application not started yet. It makes no sense to write to it, so this looks like a bug.]`);
+    });
+    describe("disposing", () => {
+        it("disposes the application when disposed", async () => {
+            // it's important to make sure there are no dangling applications when
+            // starting new tests or ending the user session entirely and closing the
+            // application
+            const app = new TestDisposableSingleApplication();
+            await app.startNextAndKillCurrent(async () => fakeApp);
+            expect(app.getApplication()).toBe(fakeApp);
+            await app[Symbol.asyncDispose]();
+            expect(fakeApp.killAndWait).toHaveBeenCalledOnce();
+        });
+        it("does nothing if there is no application to dispose", async () => {
+            const app = new TestDisposableSingleApplication();
+            expect(app.getApplication()).toBeUndefined();
+            expect(app.processId()).toBeUndefined();
+            expect(() => app[Symbol.asyncDispose]()).not.toThrow();
+        });
+    });
+});