@tui-sandbox/library 7.2.1 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "7.2.1",
+  "version": "7.4.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
     "node-pty": "1.0.0",
     "prettier": "3.4.1",
     "tsx": "4.19.2",
-    "type-fest": "4.29.0",
+    "type-fest": "4.30.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.10.0",
+    "@types/node": "22.10.1",
     "nodemon": "3.1.7",
-    "vite": "6.0.1",
-    "vitest": "2.1.6"
+    "vite": "6.0.2",
+    "vitest": "2.1.8"
   },
   "peerDependencies": {
     "cypress": "^13",

package/src/scripts/tui.ts

@@ -1,38 +1,85 @@
+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 = {
+  directories: {
+    testEnvironmentPath: path.join(cwd, "test-environment/"),
+    outputFilePath: path.join(cwd, outputFileName),
+  },
+  port: process.env["PORT"] ? parseInt(process.env["PORT"]) : 3000,
+} 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.directories.testEnvironmentPath)
+    app.events.on("stdout" satisfies StdoutOrStderrMessage, data => {
+      console.log(`  neovim output: ${data}`)
+    })
+    const testDirectory = await prepareNewTestDirectory(config.directories)
+    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",
   })
-  await updateTestdirectorySchemaFile(config)
+  await updateTestdirectorySchemaFile(config.directories)
   await startTestServer(config)
 } 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/cypress-support/contents.test.ts

@@ -96,6 +96,9 @@ it("should return the expected contents", async () => {
 
           runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
 
+          /** Run an ex command in neovim.
+           * @example "echo expand('%:.')" current file, relative to the cwd
+           */
           runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
         }
       }

package/src/server/cypress-support/contents.ts

@@ -99,6 +99,9 @@ declare global {
 
       runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
 
+      /** Run an ex command in neovim.
+       * @example "echo expand('%:.')" current file, relative to the cwd
+       */
       runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
     }
   }

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/environment/createTempDir.ts

@@ -6,10 +6,10 @@ import { access, mkdir, mkdtemp } from "fs/promises"
 import path from "path"
 import { convertDree, getDirectoryTree } from "../../dirtree/index.js"
 import type { TestDirectory } from "../../types.js"
-import type { TestServerConfig } from "../../updateTestdirectorySchemaFile.js"
+import type { DirectoriesConfig } from "../../updateTestdirectorySchemaFile.js"
 import { updateTestdirectorySchemaFile } from "../../updateTestdirectorySchemaFile.js"
 
-export async function createTempDir(config: TestServerConfig): Promise<TestDirectory> {
+export async function createTempDir(config: DirectoriesConfig): Promise<TestDirectory> {
   try {
     const dir = await createUniqueDirectory(config.testEnvironmentPath)
 

package/src/server/neovim/index.ts

@@ -10,16 +10,20 @@ import type {
   StartNeovimGenericArguments,
   TestDirectory,
 } from "../types.js"
-import type { TestServerConfig } from "../updateTestdirectorySchemaFile.js"
+import type { DirectoriesConfig } 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")
@@ -46,18 +53,23 @@ export async function start(
   options: StartNeovimGenericArguments,
   terminalDimensions: TerminalDimensions,
   tabId: TabId,
-  config: TestServerConfig
+  config: DirectoriesConfig
 ): Promise<TestDirectory> {
   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: DirectoriesConfig): 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

@@ -5,7 +5,7 @@ import { z } from "zod"
 import { trpc } from "./connection/trpc.js"
 import * as neovim from "./neovim/index.js"
 import { TestServer } from "./TestServer.js"
-import type { TestServerConfig } from "./updateTestdirectorySchemaFile.js"
+import type { DirectoriesConfig, TestServerConfig } from "./updateTestdirectorySchemaFile.js"
 import { applicationAvailable } from "./utilities/applicationAvailable.js"
 import { tabIdSchema } from "./utilities/tabId.js"
 
@@ -35,7 +35,7 @@ export type ExCommandInput = z.infer<typeof exCommandInputSchema>
 
 /** @private */
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-export async function createAppRouter(config: TestServerConfig) {
+export async function createAppRouter(config: DirectoriesConfig) {
   if (!(await applicationAvailable("nvim"))) {
     throw new Error("Neovim is not installed. Please install Neovim (nvim).")
   }
@@ -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)
@@ -99,9 +99,9 @@ export type RouterInput = inferRouterInputs<AppRouter>
 
 export async function startTestServer(config: TestServerConfig): Promise<TestServer> {
   const testServer = new TestServer({
-    port: 3000,
+    port: config.port,
   })
-  const appRouter = await createAppRouter(config)
+  const appRouter = await createAppRouter(config.directories)
   await testServer.startAndRun(appRouter)
 
   return testServer

package/src/server/updateTestdirectorySchemaFile.ts

@@ -1,17 +1,22 @@
 import { readFileSync, writeFileSync } from "fs"
 import { buildTestDirectorySchema } from "./dirtree/index.js"
 
-export type TestServerConfig = {
+export type DirectoriesConfig = {
   testEnvironmentPath: string
   outputFilePath: string
 }
 
+export type TestServerConfig = {
+  directories: DirectoriesConfig
+  port: number
+}
+
 export type UpdateTestdirectorySchemaFileResult = "updated" | "did-nothing"
 
 export async function updateTestdirectorySchemaFile({
   testEnvironmentPath,
   outputFilePath,
-}: TestServerConfig): Promise<UpdateTestdirectorySchemaFileResult> {
+}: DirectoriesConfig): Promise<UpdateTestdirectorySchemaFileResult> {
   const newSchema: string = await buildTestDirectorySchema(testEnvironmentPath)
   let oldSchema = ""
 

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. */