@tui-sandbox/library 7.2.0 → 7.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -8,8 +8,8 @@
   },
   "dependencies": {
     "@catppuccin/palette": "1.7.1",
-    "@trpc/client": "11.0.0-rc.643",
-    "@trpc/server": "11.0.0-rc.643",
+    "@trpc/client": "11.0.0-rc.648",
+    "@trpc/server": "11.0.0-rc.648",
     "@xterm/addon-attach": "0.11.0",
     "@xterm/addon-fit": "0.10.0",
     "@xterm/xterm": "5.5.0",
@@ -20,9 +20,9 @@
     "express": "4.21.1",
     "neovim": "5.3.0",
     "node-pty": "1.0.0",
-    "prettier": "3.3.3",
+    "prettier": "3.4.1",
     "tsx": "4.19.2",
-    "type-fest": "4.27.0",
+    "type-fest": "4.29.0",
     "winston": "3.17.0",
     "zod": "3.23.8"
   },
@@ -31,10 +31,10 @@
     "@types/command-exists": "1.2.3",
     "@types/cors": "2.8.17",
     "@types/express": "5.0.0",
-    "@types/node": "22.9.1",
+    "@types/node": "22.10.1",
     "nodemon": "3.1.7",
-    "vite": "5.4.11",
-    "vitest": "2.1.5"
+    "vite": "6.0.1",
+    "vitest": "2.1.6"
   },
   "peerDependencies": {
     "cypress": "^13",

package/src/scripts/tui.ts

@@ -1,32 +1,63 @@
+import assert from "node:assert"
 import { stat } from "node:fs/promises"
 import path from "node:path"
 import { createCypressSupportFile } from "../server/cypress-support/createCypressSupportFile.js"
 import type { TestServerConfig } from "../server/index.js"
 import { startTestServer, updateTestdirectorySchemaFile } from "../server/index.js"
+import type { StdoutOrStderrMessage } from "../server/neovim/NeovimApplication.js"
+import { NeovimApplication } from "../server/neovim/NeovimApplication.js"
+import { prepareNewTestDirectory } from "../server/neovim/index.js"
 
 //
 // This is the main entrypoint to tui-sandbox
 //
 
-// the arguments passed to this script start at index 2
-const args = process.argv.slice(2)
-
-if (args[0] !== "start") {
-  throw new Error(`Usage: tui start`)
-}
 const outputFileName = "MyTestDirectory.ts"
 
 /** The cwd in the user's directory when they are running this script. Not the
  * cwd of the script itself. */
 const cwd = process.cwd()
+const config = {
+  testEnvironmentPath: path.join(cwd, "test-environment/"),
+  outputFilePath: path.join(cwd, outputFileName),
+} satisfies TestServerConfig
+
+// the arguments passed to this script start at index 2
+const args = process.argv.slice(2)
+
+if (args[0] === "neovim") {
+  if (!(args[1] === "exec" && args.length === 3)) {
+    showUsageAndExit()
+  }
+
+  const command = args[2]
+  assert(command, "No command provided")
+
+  {
+    // automatically dispose of the neovim instance when done
+    await using app = new NeovimApplication(config.testEnvironmentPath)
+    app.events.on("stdout" satisfies StdoutOrStderrMessage, data => {
+      console.log(`  neovim output: ${data}`)
+    })
+    const testDirectory = await prepareNewTestDirectory(config)
+    await app.startNextAndKillCurrent(
+      testDirectory,
+      { filename: "empty.txt", headlessCmd: command },
+      { cols: 80, rows: 24 }
+    )
+    await app.application.untilExit()
+  }
+
+  process.exit(0)
+}
+
+if (args[0] !== "start") {
+  showUsageAndExit()
+}
 console.log(`🚀 Starting test server in ${cwd} - this should be the root of your integration-tests directory 🤞🏻`)
 await stat(path.join(cwd, outputFileName))
 
 try {
-  const config = {
-    testEnvironmentPath: path.join(cwd, "test-environment/"),
-    outputFilePath: path.join(cwd, outputFileName),
-  } satisfies TestServerConfig
   await createCypressSupportFile({
     cypressSupportDirectoryPath: path.join(cwd, "cypress", "support"),
     supportFileName: "tui-sandbox.ts",
@@ -36,3 +67,16 @@ try {
 } catch (e) {
   console.error(e)
 }
+
+function showUsageAndExit() {
+  console.log(
+    [
+      //
+      `Usage (pick one):`,
+      `    tui start`,
+      `    tui neovim exec '<ex-command>'`,
+    ].join("\n")
+  )
+
+  process.exit(1)
+}

package/src/server/TestServer.ts

@@ -39,7 +39,9 @@ export class TestServer {
       } catch (e) {
         // This is normal when developing the tui-sandbox library locally. It
         // should always exist when using it as an npm package, however.
-        console.log(`⚠️ Warning: the tui-sandbox root contents directory is not accessible at: ${publicPath}`)
+        console.log(
+          `⚠️ Warning: Looks like the tui-sandbox root contents directory is not accessible at: ${publicPath}`
+        )
       }
 
       // eslint-disable-next-line import-x/no-named-as-default-member
@@ -47,24 +49,24 @@ export class TestServer {
     }
 
     app.use("/ping", (_, res) => {
-      console.log("🏓 received /ping")
+      // console.log("🏓 received /ping")
       res.send("pong")
     })
 
     const server = app.listen(this.settings.port, "0.0.0.0")
 
     server.on("connection", socket => {
-      const connectionInfo = `${socket.remoteAddress}:${socket.remotePort}`
-      console.log(`➕➕ Connection from ${connectionInfo}`)
+      // const connectionInfo = `${socket.remoteAddress}:${socket.remotePort}`
+      // console.log(`➕➕ Connection from ${connectionInfo}`)
       socket.once("close", () => {
-        console.log(`➖➖ Connection from ${connectionInfo}`)
+        // console.log(`➖➖ Connection from ${connectionInfo}`)
       })
     })
 
     console.log(`✅ Server listening on port ${this.settings.port}`)
 
     await Promise.race([once(process, "SIGTERM"), once(process, "SIGINT")])
-    console.log("Shutting down...")
+    console.log("😴 Shutting down...")
     server.close(error => {
       if (error) {
         console.error("Error closing server", error)

package/src/server/neovim/NeovimApplication.ts

@@ -56,12 +56,15 @@ Run "nvim -V1 -v" for more info
 
 */
 
-export type StdoutMessage = "stdout"
+export type StdoutOrStderrMessage = "stdout"
 
 export type StartNeovimGenericArguments = {
   filename: string | { openInVerticalSplits: string[] }
   startupScriptModifications?: string[]
 
+  /** Executes the given command with --headless -c <command> -c qa */
+  headlessCmd?: string
+
   /** Additions to the environment variables for the Neovim process. These
    * override any already existing environment variables. */
   additionalEnvironmentVariables?: Record<string, string> | undefined
@@ -128,6 +131,13 @@ export class NeovimApplication {
       }
     }
 
+    if (startArgs.headlessCmd) {
+      // NOTE: update the doc comment above if this changes
+      neovimArguments.push("--headless")
+      neovimArguments.push("-c", startArgs.headlessCmd)
+      neovimArguments.push("-c", "qa")
+    }
+
     const id = Math.random().toString().slice(2, 8)
     const socketPath = `${tmpdir()}/tui-sandbox-nvim-socket-${id}`
     neovimArguments.push("--listen", socketPath)
@@ -146,7 +156,7 @@ export class NeovimApplication {
 
         onStdoutOrStderr(data) {
           data satisfies string
-          stdout.emit("stdout" satisfies StdoutMessage, data)
+          stdout.emit("stdout" satisfies StdoutOrStderrMessage, data)
         },
       })
     })

package/src/server/neovim/NeovimJavascriptApiClient.ts

@@ -14,10 +14,10 @@ export function connectNeovimApi(socketPath: string): Lazy<Promise<NeovimJavascr
     for (let i = 0; i < 100; i++) {
       try {
         await access(socketPath)
-        console.log(`socket file ${socketPath} created after at attempt ${i + 1}`)
+        // console.log(`socket file ${socketPath} created after at attempt ${i + 1}`)
         break
       } catch (e) {
-        console.log(`polling for socket file ${socketPath} to be created (attempt ${i + 1})`)
+        // console.log(`polling for socket file ${socketPath} to be created (attempt ${i + 1})`)
         await new Promise(resolve => setTimeout(resolve, 100 satisfies PollingInterval))
       }
     }

package/src/server/neovim/index.ts

@@ -12,14 +12,18 @@ import type {
 } from "../types.js"
 import type { TestServerConfig } from "../updateTestdirectorySchemaFile.js"
 import { convertEventEmitterToAsyncGenerator } from "../utilities/generator.js"
+import { Lazy } from "../utilities/Lazy.js"
 import type { TabId } from "../utilities/tabId.js"
 import { createTempDir, removeTestDirectories } from "./environment/createTempDir.js"
 import type { TerminalDimensions } from "./NeovimApplication.js"
 import { NeovimApplication } from "./NeovimApplication.js"
 
 const neovims = new Map<TabId["tabId"], NeovimApplication>()
+export const resources: Lazy<AsyncDisposableStack> = new Lazy(() => {
+  return new AsyncDisposableStack()
+})
 
-export async function onStdout(
+export async function initializeStdout(
   options: { client: TabId },
   signal: AbortSignal | undefined,
   testEnvironmentPath: string
@@ -28,6 +32,9 @@ export async function onStdout(
   const neovim = neovims.get(tabId) ?? new NeovimApplication(testEnvironmentPath)
   if (neovims.get(tabId) === undefined) {
     neovims.set(tabId, neovim)
+    resources.get().adopt(neovim, async n => {
+      await n[Symbol.asyncDispose]()
+    })
   }
 
   const stdout = convertEventEmitterToAsyncGenerator(neovim.events, "stdout")
@@ -51,13 +58,18 @@ export async function start(
   const neovim = neovims.get(tabId.tabId)
   assert(neovim, `Neovim instance not found for client id ${tabId.tabId}`)
 
-  await removeTestDirectories(config.testEnvironmentPath)
-  const testDirectory = await createTempDir(config)
+  const testDirectory = await prepareNewTestDirectory(config)
   await neovim.startNextAndKillCurrent(testDirectory, options, terminalDimensions)
 
   return testDirectory
 }
 
+export async function prepareNewTestDirectory(config: TestServerConfig): Promise<TestDirectory> {
+  await removeTestDirectories(config.testEnvironmentPath)
+  const testDirectory = await createTempDir(config)
+  return testDirectory
+}
+
 export async function sendStdin(options: { tabId: TabId; data: string }): Promise<void> {
   const neovim = neovims.get(options.tabId.tabId)
   assert(

package/src/server/server.ts

@@ -71,7 +71,7 @@ export async function createAppRouter(config: TestServerConfig) {
           )
         }),
       onStdout: trpc.procedure.input(z.object({ client: tabIdSchema })).subscription(options => {
-        return neovim.onStdout(options.input, options.signal, config.testEnvironmentPath)
+        return neovim.initializeStdout(options.input, options.signal, config.testEnvironmentPath)
       }),
       sendStdin: trpc.procedure.input(z.object({ tabId: tabIdSchema, data: z.string() })).mutation(options => {
         return neovim.sendStdin(options.input)

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

@@ -1,5 +1,6 @@
 import type { StartableApplication } from "./DisposableSingleApplication.js"
 import { DisposableSingleApplication } from "./DisposableSingleApplication.js"
+import type { ExitInfo } from "./TerminalApplication.js"
 
 vi.spyOn(console, "log").mockImplementation(vi.fn())
 
@@ -9,11 +10,12 @@ class TestDisposableSingleApplication extends DisposableSingleApplication {
   }
 }
 
-const fakeApp: StartableApplication = {
+const fakeApp = {
   processId: 123,
   write: vi.fn(),
   killAndWait: vi.fn(),
-}
+  untilExit: Promise.resolve<ExitInfo>({ exitCode: 0, signal: undefined }),
+} satisfies StartableApplication
 
 describe("DisposableSingleApplication", () => {
   it("has no application when created", () => {
@@ -45,6 +47,25 @@ describe("DisposableSingleApplication", () => {
     )
   })
 
+  describe("untilExit allows waiting for the application to exit", () => {
+    it("successful exit works", async () => {
+      const app = new TestDisposableSingleApplication()
+      await app.startNextAndKillCurrent(async () => fakeApp)
+      fakeApp.untilExit = Promise.resolve({ exitCode: 1, signal: 9 })
+      await expect(app.untilExit()).resolves.toStrictEqual({
+        exitCode: 1,
+        signal: 9,
+      } satisfies ExitInfo)
+    })
+
+    it("when the application throws an error, the error is propagated", async () => {
+      const app = new TestDisposableSingleApplication()
+      await app.startNextAndKillCurrent(async () => fakeApp)
+      fakeApp.untilExit = Promise.reject(new Error("fake error"))
+      await expect(app.untilExit()).rejects.toThrowError(new Error("fake error"))
+    })
+  })
+
   describe("disposing", () => {
     it("disposes the application when disposed", async () => {
       // it's important to make sure there are no dangling applications when

package/src/server/utilities/DisposableSingleApplication.ts

@@ -1,7 +1,7 @@
 import assert from "assert"
-import type { TerminalApplication } from "./TerminalApplication.js"
+import type { ExitInfo, TerminalApplication } from "./TerminalApplication.js"
 
-export type StartableApplication = Pick<TerminalApplication, "write" | "processId" | "killAndWait">
+export type StartableApplication = Pick<TerminalApplication, "write" | "processId" | "killAndWait" | "untilExit">
 
 /** 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
@@ -15,6 +15,14 @@ export class DisposableSingleApplication implements AsyncDisposable {
     this.application = await startNext()
   }
 
+  public async untilExit(): Promise<ExitInfo> {
+    assert(
+      this.application,
+      "The application not started yet. It makes no sense to wait for it to exit, so this looks like a bug."
+    )
+    return this.application.untilExit
+  }
+
   public async write(input: string): Promise<void> {
     assert(
       this.application,

package/src/server/utilities/TerminalApplication.ts

@@ -6,6 +6,8 @@ import type { IPty } from "node-pty"
 import pty from "node-pty"
 import type { StartableApplication } from "./DisposableSingleApplication.js"
 
+export type ExitInfo = { exitCode: number; signal: number | undefined }
+
 // NOTE separating stdout and stderr is not supported by node-pty
 // https://github.com/microsoft/node-pty/issues/71
 export class TerminalApplication implements StartableApplication {
@@ -15,7 +17,8 @@ export class TerminalApplication implements StartableApplication {
 
   private constructor(
     private readonly subProcess: IPty,
-    public readonly onStdoutOrStderr: (data: string) => void
+    public readonly onStdoutOrStderr: (data: string) => void,
+    public readonly untilExit: Promise<ExitInfo>
   ) {
     this.processId = subProcess.pid
 
@@ -60,14 +63,23 @@ export class TerminalApplication implements StartableApplication {
       cols: dimensions.cols,
       rows: dimensions.rows,
     })
+    ptyProcess.onExit(({ exitCode, signal }) => {
+      console.log(`Child process exited with code ${exitCode} and signal ${signal}`)
+    })
 
     const processId = ptyProcess.pid
 
     if (!processId) {
       throw new Error("Failed to spawn child process")
     }
+    const untilExit = new Promise<ExitInfo>(resolve => {
+      ptyProcess.onExit(({ exitCode, signal }) => {
+        // console.log(`Child process ${processId} exited with code ${exitCode} and signal ${signal}`)
+        resolve({ exitCode, signal })
+      })
+    })
 
-    return new TerminalApplication(ptyProcess, onStdoutOrStderr)
+    return new TerminalApplication(ptyProcess, onStdoutOrStderr, untilExit)
   }
 
   /** Write to the terminal's stdin. */