@tui-sandbox/library 2.0.2 → 2.2.0

package/dist/vitest.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("vite").UserConfig;
+export default _default;

package/dist/vitest.config.js

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+export default defineConfig({
+    test: {
+        globals: true, // This will make describe, it, etc. available globally
+        environment: "node",
+        mockReset: true,
+    },
+});

package/package.json

@@ -1,29 +1,32 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "license": "MIT",
   "type": "module",
   "dependencies": {
-    "@catppuccin/palette": "1.4.0",
-    "@trpc/client": "11.0.0-rc.586",
-    "@trpc/server": "11.0.0-rc.586",
-    "@types/ws": "8.5.12",
+    "@catppuccin/palette": "1.5.0",
+    "@trpc/client": "11.0.0-rc.608",
+    "@trpc/server": "11.0.0-rc.608",
     "@xterm/addon-attach": "0.11.0",
     "@xterm/addon-fit": "0.10.0",
     "@xterm/xterm": "5.5.0",
-    "core-js": "3.38.1",
+    "command-exists": "1.2.9",
+    "core-js": "3.39.0",
+    "cors": "2.8.5",
     "dree": "5.1.5",
     "node-pty": "1.0.0",
     "prettier": "3.3.3",
-    "winston": "3.15.0",
-    "ws": "8.18.0",
+    "type-fest": "4.26.1",
+    "winston": "3.16.0",
     "zod": "3.23.8"
   },
   "devDependencies": {
     "@runtyping/zod": "2.1.1",
-    "@types/node": "22.7.6",
+    "@types/command-exists": "1.2.3",
+    "@types/cors": "2.8.17",
+    "@types/node": "22.8.6",
     "nodemon": "3.1.7",
-    "vitest": "2.1.3"
+    "vitest": "2.1.4"
   },
   "scripts": {
     "build": "tsc",

package/src/client/neovim-client.ts

@@ -1,6 +1,7 @@
-import { createTRPCClient, createWSClient, wsLink } from "@trpc/client"
+import { createTRPCClient, httpBatchLink, splitLink, unstable_httpSubscriptionLink } from "@trpc/client"
 import type { Terminal } from "@xterm/xterm"
 import "@xterm/xterm/css/xterm.css"
+import type { Except } from "type-fest"
 import type { StartNeovimGenericArguments } from "../server/neovim/NeovimApplication.ts"
 import type { AppRouter } from "../server/server.ts"
 import type { TestDirectory } from "../server/types.ts"
@@ -14,9 +15,18 @@ export class NeovimClient {
   private readonly trpc: ReturnType<typeof createTRPCClient<AppRouter>>
 
   constructor(app: HTMLElement) {
-    const wsClient = createWSClient({ url: `ws://localhost:3000`, WebSocket })
     const trpc = createTRPCClient<AppRouter>({
-      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
 
@@ -56,7 +66,7 @@ export class NeovimClient {
     })
   }
 
-  public async startNeovim(args: StartNeovimGenericArguments): Promise<TestDirectory> {
+  public async startNeovim(args: Except<StartNeovimGenericArguments, "terminalDimensions">): Promise<TestDirectory> {
     await this.ready
 
     const neovim = await this.trpc.neovim.start.mutate({

package/src/server/TestServer.ts

@@ -1,53 +1,45 @@
 import type { AnyTRPCRouter } from "@trpc/server"
-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 type { TestServerConfig } from "./updateTestdirectorySchemaFile"
 import { updateTestdirectorySchemaFile } from "./updateTestdirectorySchemaFile"
 
 export class TestServer {
   public constructor(private readonly port: number) {}
 
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-  public async startAndRun<TRouter extends AnyTRPCRouter>(appRouter: TRouter, config: TestServerConfig): Promise<void> {
+  public async startAndRun(appRouter: AnyTRPCRouter, config: TestServerConfig): Promise<void> {
     console.log("🚀 Server starting")
 
     await updateTestdirectorySchemaFile(config)
 
-    const wss = new WebSocketServer({ port: this.port })
-    const handler = applyWSSHandler<TRouter>({
-      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/src/server/connection/trpc.ts

@@ -1,17 +1,3 @@
 import { initTRPC } from "@trpc/server"
-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 function createContext(opts: CreateWSSContextFnOptions): Connection {
-  return { clientId: opts.res, socket: opts.req.socket }
-}
-
-type Context = Awaited<ReturnType<typeof createContext>>
-
-export const trpc = initTRPC.context<Context>().create()
+export const trpc = initTRPC.context<object>().create()

package/src/server/neovim/NeovimApplication.ts

@@ -1,3 +1,4 @@
+import assert from "assert"
 import { exec } from "child_process"
 import EventEmitter from "events"
 import { existsSync } from "fs"
@@ -59,12 +60,14 @@ export type StartNeovimGenericArguments = {
   startupScriptModifications?: string[]
 }
 
-export class NeovimApplication extends DisposableSingleApplication {
+export class NeovimApplication {
   private testDirectory: TestDirectory | undefined
   public readonly events: EventEmitter
 
-  public constructor(private readonly testEnvironmentPath: string) {
-    super()
+  public constructor(
+    private readonly testEnvironmentPath: string,
+    public readonly application: DisposableSingleApplication = new DisposableSingleApplication()
+  ) {
     this.events = new EventEmitter()
   }
 
@@ -105,22 +108,29 @@ export class NeovimApplication extends DisposableSingleApplication {
     }
     const stdout = this.events
 
-    this.application = TerminalApplication.start({
-      command: "nvim",
-      args: neovimArguments,
+    await this.application.startNextAndKillCurrent(async () => {
+      return TerminalApplication.start({
+        command: "nvim",
+        args: neovimArguments,
 
-      cwd: this.testEnvironmentPath,
-      env: process.env,
-      dimensions: startArgs.terminalDimensions,
+        cwd: this.testEnvironmentPath,
+        env: process.env,
+        dimensions: startArgs.terminalDimensions,
 
-      onStdoutOrStderr(data: string) {
-        stdout.emit("stdout" satisfies StdoutMessage, data)
-      },
+        onStdoutOrStderr(data) {
+          data satisfies string
+          stdout.emit("stdout" satisfies StdoutMessage, 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}`)
   }
 
-  override async [Symbol.asyncDispose](): Promise<void> {
-    await super.killCurrent()
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.application[Symbol.asyncDispose]()
     if (this.testDirectory) {
       exec(`rm -rf ${this.testDirectory.rootPathAbsolute}`)
     }

package/src/server/neovim/environment/createTempDir.test.ts

@@ -4,6 +4,8 @@ import { expect, it } from "vitest"
 import type { TestDirsPath } from "./createTempDir"
 import { createTempDir } from "./createTempDir"
 
+vi.spyOn(console, "log").mockImplementation(vi.fn())
+
 type TestTempDirPrefix = "test-temp-dir-"
 
 class TempDirectory implements Disposable {

package/src/server/neovim/index.ts

@@ -1,37 +1,35 @@
-import type { Observable } from "@trpc/server/observable"
-import { observable } from "@trpc/server/observable"
 import assert from "assert"
 import type { TestDirectory } from "../types"
 import type { TestServerConfig } from "../updateTestdirectorySchemaFile"
+import { convertEventEmitterToAsyncGenerator } from "../utilities/generator"
 import type { TabId } from "../utilities/tabId"
 import { createTempDir } from "./environment/createTempDir"
-import type { StartNeovimGenericArguments, StdoutMessage } from "./NeovimApplication"
+import type { StartNeovimGenericArguments } from "./NeovimApplication"
 import { NeovimApplication } from "./NeovimApplication"
 
 const neovims = new Map<TabId["tabId"], NeovimApplication>()
 
-export function onStdout(options: { client: TabId }, testEnvironmentPath: string): Observable<string, unknown> {
-  return observable<string>(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: unknown) => {
-      assert(typeof data === "string")
-      emit.next(data)
-    }
-
-    neovim.events.on("stdout" satisfies StdoutMessage, send)
-
-    return () => {
-      neovim.events.off("stdout" satisfies StdoutMessage, send)
+export async function onStdout(
+  options: { client: TabId },
+  signal: AbortSignal | undefined,
+  testEnvironmentPath: string
+): Promise<AsyncGenerator<string, void, unknown>> {
+  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(
@@ -45,10 +43,6 @@ export async function start(
   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
 }
 
@@ -58,6 +52,10 @@ export async function sendStdin(options: { tabId: TabId; data: string }): Promis
     neovim !== undefined,
     `Neovim instance for clientId not found - cannot send stdin. Maybe it's not started yet?`
   )
+  assert(
+    neovim.application,
+    `Neovim application not found for client id ${options.tabId.tabId}. Maybe it's not started yet?`
+  )
 
-  await neovim.write(options.data)
+  await neovim.application.write(options.data)
 }

package/src/server/server.test.ts

@@ -0,0 +1,34 @@
+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/src/server/server.ts

@@ -4,6 +4,7 @@ import { trpc } from "./connection/trpc"
 import * as neovim from "./neovim"
 import { TestServer } from "./TestServer"
 import type { TestServerConfig } from "./updateTestdirectorySchemaFile"
+import { applicationAvailable } from "./utilities/applicationAvailable"
 import { tabIdSchema } from "./utilities/tabId"
 
 /** Stack for managing resources that need to be disposed of when the server
@@ -14,7 +15,13 @@ autocleanup.defer(() => {
 })
 export { autocleanup }
 
-function createAppRouter(config: TestServerConfig) {
+/** @private */
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export async function createAppRouter(config: TestServerConfig) {
+  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
@@ -40,7 +47,7 @@ function createAppRouter(config: TestServerConfig) {
           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)
@@ -51,12 +58,12 @@ function createAppRouter(config: TestServerConfig) {
   return appRouter
 }
 
-export type AppRouter = ReturnType<typeof createAppRouter>
+export type AppRouter = Awaited<ReturnType<typeof createAppRouter>>
 export type RouterInput = inferRouterInputs<AppRouter>
 
 export async function startTestServer(config: TestServerConfig): Promise<TestServer> {
   const testServer = new TestServer(3000)
-  const appRouter = createAppRouter(config)
+  const appRouter = await createAppRouter(config)
   await testServer.startAndRun(appRouter, config)
 
   return testServer

package/src/server/updateTestdirectorySchemaFile.test.ts

@@ -0,0 +1,43 @@
+import { readFileSync, writeFileSync } from "fs"
+import { buildTestDirectorySchema } from "./dirtree"
+import type { UpdateTestdirectorySchemaFileResult } from "./updateTestdirectorySchemaFile"
+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" satisfies UpdateTestdirectorySchemaFileResult)
+  })
+})
+
+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" satisfies UpdateTestdirectorySchemaFileResult)
+    expect(mock.writeFileSync).toHaveBeenCalledWith("path", "new schema")
+  })
+})

package/src/server/updateTestdirectorySchemaFile.ts

@@ -7,11 +7,13 @@ export type TestServerConfig = {
   outputFilePath: string
 }
 
+export type UpdateTestdirectorySchemaFileResult = "updated" | "did-nothing"
+
 export async function updateTestdirectorySchemaFile({
   testEnvironmentPath,
   outputFilePath,
-}: TestServerConfig): Promise<void> {
-  const newSchema = await buildTestDirectorySchema(testEnvironmentPath)
+}: TestServerConfig): Promise<UpdateTestdirectorySchemaFileResult> {
+  const newSchema: string = await buildTestDirectorySchema(testEnvironmentPath)
   let oldSchema = ""
 
   try {
@@ -25,5 +27,8 @@ export async function updateTestdirectorySchemaFile({
     // 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/src/server/utilities/DisposableSingleApplication.test.ts

@@ -0,0 +1,70 @@
+import type { StartableApplication } from "./DisposableSingleApplication"
+import { DisposableSingleApplication } from "./DisposableSingleApplication"
+
+vi.spyOn(console, "log").mockImplementation(vi.fn())
+
+class TestDisposableSingleApplication extends DisposableSingleApplication {
+  public getApplication() {
+    return this.application
+  }
+}
+
+const fakeApp: StartableApplication = {
+  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()
+    })
+  })
+})

package/src/server/utilities/DisposableSingleApplication.ts

@@ -1,33 +1,38 @@
+import assert from "assert"
 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 abstract class DisposableSingleApplication implements AsyncDisposable {
-  protected application: TerminalApplication | undefined
+export class DisposableSingleApplication implements AsyncDisposable {
+  protected application: StartableApplication | undefined
 
-  public async killCurrent(): Promise<void> {
-    await this.application?.killAndWait()
+  public async startNextAndKillCurrent(startNext: () => Promise<StartableApplication>): Promise<void> {
+    await this[Symbol.asyncDispose]()
+    this.application = await startNext()
   }
 
   public async write(input: string): Promise<void> {
-    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)
   }
 
   public processId(): number | undefined {
     return this.application?.processId
   }
 
-  async [Symbol.asyncDispose](): Promise<void> {
+  /** Kill the current application if it exists. */
+  public async [Symbol.asyncDispose](): Promise<void> {
     if (this.processId() === undefined) {
       return
     }
     console.log(`Killing current application ${this.processId()}...`)
-    await this.killCurrent()
+    await this.application?.killAndWait()
   }
 }

package/src/server/utilities/TerminalApplication.ts

@@ -4,10 +4,11 @@ import { createLogger, format, transports } from "winston"
 import type { ITerminalDimensions } from "@xterm/addon-fit"
 import type { IPty } from "node-pty"
 import pty from "node-pty"
+import type { StartableApplication } from "./DisposableSingleApplication"
 
 // NOTE separating stdout and stderr is not supported by node-pty
 // https://github.com/microsoft/node-pty/issues/71
-export class TerminalApplication {
+export class TerminalApplication implements StartableApplication {
   public readonly processId: number
 
   public readonly logger: winston.Logger

package/src/server/utilities/applicationAvailable.test.ts

@@ -0,0 +1,14 @@
+import { applicationAvailable } from "./applicationAvailable"
+
+describe("sanity checks for mocking", () => {
+  // because it makes no sense to mock the actual implementation if we don't
+  // know what it does in the current version, we better check what it's
+  // expected to do
+  it("can find neovim using the actual implementation", async () => {
+    await expect(applicationAvailable("nvim")).resolves.toBe("nvim")
+  })
+
+  it("complains when a nonexistent command is checked", async () => {
+    await expect(applicationAvailable("thisCommandDoesNotExist")).rejects.toBe(null)
+  })
+})

package/src/server/utilities/applicationAvailable.ts

@@ -0,0 +1,5 @@
+import commandExists from "command-exists"
+
+export async function applicationAvailable(command: string): Promise<string | null> {
+  return commandExists(command)
+}