@tui-sandbox/library 9.5.1 → 10.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "9.5.1",
+  "version": "10.0.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -8,21 +8,21 @@
   },
   "dependencies": {
     "@catppuccin/palette": "1.7.1",
-    "@trpc/client": "11.0.0-rc.819",
-    "@trpc/server": "11.0.0-rc.819",
+    "@trpc/client": "11.0.0-rc.828",
+    "@trpc/server": "11.0.0-rc.828",
     "@xterm/addon-attach": "0.11.0",
     "@xterm/addon-fit": "0.10.0",
     "@xterm/xterm": "5.5.0",
     "command-exists": "1.2.9",
-    "core-js": "3.40.0",
+    "core-js": "3.41.0",
     "cors": "2.8.5",
     "dree": "5.1.5",
     "express": "4.21.2",
     "neovim": "5.3.0",
     "node-pty": "1.0.0",
-    "prettier": "3.5.2",
+    "prettier": "3.5.3",
     "tsx": "4.19.3",
-    "type-fest": "4.35.0",
+    "type-fest": "4.37.0",
     "winston": "3.17.0",
     "zod": "3.24.2"
   },
@@ -31,10 +31,10 @@
     "@types/command-exists": "1.2.3",
     "@types/cors": "2.8.17",
     "@types/express": "5.0.0",
-    "@types/node": "22.13.7",
+    "@types/node": "22.13.10",
     "nodemon": "3.1.9",
-    "vite": "6.2.0",
-    "vitest": "3.0.7"
+    "vite": "6.2.1",
+    "vitest": "3.0.8"
   },
   "peerDependencies": {
     "cypress": "^13 || ^14",

package/src/browser/neovim-client.ts

@@ -1,7 +1,7 @@
 import { TerminalClient as NeovimTerminalClient } from "../client/index.js"
 import { TerminalTerminalClient } from "../client/terminal-terminal-client.js"
 import type { BlockingCommandClientInput } from "../server/blockingCommandInputSchema.js"
-import type { ExCommandClientInput, LuaCodeClientInput } from "../server/server.js"
+import type { ExCommandClientInput, LuaCodeClientInput, PollLuaCodeClientInput } from "../server/server.js"
 import type { StartTerminalGenericArguments } from "../server/terminal/TerminalTestApplication.js"
 import type {
   BlockingShellCommandOutput,
@@ -24,6 +24,7 @@ const terminalClient = new Lazy(() => new TerminalTerminalClient(app))
 export type GenericNeovimBrowserApi = {
   runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
   runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
+  waitForLuaCode(input: PollLuaCodeClientInput): Promise<RunLuaCodeOutput>
   runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
   dir: TestDirectory
 }
@@ -44,6 +45,9 @@ window.startNeovim = async function (startArgs?: StartNeovimGenericArguments): P
     runLuaCode(input) {
       return neovim.runLuaCode(input)
     },
+    waitForLuaCode(input) {
+      return neovim.waitForLuaCode(input)
+    },
     runExCommand(input) {
       return neovim.runExCommand(input)
     },

package/src/client/neovim-terminal-client.ts

@@ -2,7 +2,7 @@ import { createTRPCClient, httpBatchLink, splitLink, unstable_httpSubscriptionLi
 import type { Terminal } from "@xterm/xterm"
 import "@xterm/xterm/css/xterm.css"
 import type { BlockingCommandClientInput } from "../server/blockingCommandInputSchema.js"
-import type { AppRouter, ExCommandClientInput, LuaCodeClientInput } from "../server/server.js"
+import type { AppRouter, ExCommandClientInput, LuaCodeClientInput, PollLuaCodeClientInput } from "../server/server.js"
 import type {
   BlockingShellCommandOutput,
   RunExCommandOutput,
@@ -102,6 +102,15 @@ export class NeovimTerminalClient {
     return this.trpc.neovim.runLuaCode.mutate({ ...input, tabId: this.tabId })
   }
 
+  public async waitForLuaCode(input: PollLuaCodeClientInput): Promise<RunLuaCodeOutput> {
+    await this.ready
+    try {
+      return await this.trpc.neovim.waitForLuaCode.mutate({ ...input, tabId: this.tabId })
+    } catch (e) {
+      throw e
+    }
+  }
+
   public async runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput> {
     await this.ready
     return this.trpc.neovim.runExCommand.mutate({ ...input, tabId: this.tabId })

package/src/scripts/tui.ts

@@ -3,6 +3,7 @@ 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 { installDependencies } from "../server/neovim/index.js"
 import type { StdoutOrStderrMessage } from "../server/neovim/NeovimApplication.js"
 import { NeovimApplication } from "../server/neovim/NeovimApplication.js"
 import { prepareNewTestDirectory } from "../server/neovim/prepareNewTestDirectory.js"
@@ -28,6 +29,15 @@ const config = {
 const args = process.argv.slice(2)
 
 if (args[0] === "neovim") {
+  if (args[1] === "prepare" && args.length === 2) {
+    console.log("🚀 Installing neovim dependencies...")
+    await installDependencies(config.directories.testEnvironmentPath, config.directories).catch((err: unknown) => {
+      console.error("Error installing neovim dependencies", err)
+      process.exit(1)
+    })
+    process.exit(0)
+  }
+
   if (!(args[1] === "exec" && args.length === 3)) {
     showUsageAndExit()
   }

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

@@ -14,7 +14,11 @@ import type {
   GenericNeovimBrowserApi,
   GenericTerminalBrowserApi,
 } from "@tui-sandbox/library/dist/src/browser/neovim-client"
-import type { ExCommandClientInput, LuaCodeClientInput } from "@tui-sandbox/library/dist/src/server/server"
+import type {
+  ExCommandClientInput,
+  LuaCodeClientInput,
+  PollLuaCodeClientInput,
+} from "@tui-sandbox/library/dist/src/server/server"
 import type {
   BlockingShellCommandOutput,
   RunExCommandOutput,
@@ -54,6 +58,16 @@ export type NeovimContext = {
    * finish before returning. Requires neovim to be running. */
   runLuaCode(input: LuaCodeClientInput): Cypress.Chainable<RunLuaCodeOutput>
 
+  /**
+   * Like runLuaCode, but waits until the given code (maybe using lua's return
+   * assert()) does not raise an error, and returns the first successful result.
+   *
+   * Useful for waiting until Neovim's internal state has changed in a way that
+   * means the test can continue executing. This can avoid timing issues that are
+   * otherwise hard to catch.
+   */
+  waitForLuaCode(input: PollLuaCodeClientInput): Cypress.Chainable<RunLuaCodeOutput>
+
   /** Run an ex command in neovim.
    * @example "echo expand('%:.')" current file, relative to the cwd
    */
@@ -85,6 +99,7 @@ Cypress.Commands.add("startNeovim", (startArguments?: MyStartNeovimServerArgumen
       nvim_runBlockingShellCommand: underlyingNeovim.runBlockingShellCommand,
       nvim_runExCommand: underlyingNeovim.runExCommand,
       nvim_runLuaCode: underlyingNeovim.runLuaCode,
+      nvim_waitForLuaCode: underlyingNeovim.waitForLuaCode,
     })
 
     const api: NeovimContext = {
@@ -97,6 +112,9 @@ Cypress.Commands.add("startNeovim", (startArguments?: MyStartNeovimServerArgumen
       runLuaCode(input) {
         return cy.nvim_runLuaCode(input)
       },
+      waitForLuaCode(input) {
+        return cy.nvim_waitForLuaCode(input)
+      },
       typeIntoTerminal(text, options) {
         cy.typeIntoTerminal(text, options)
       },
@@ -164,6 +182,7 @@ declare global {
       nvim_runBlockingShellCommand(input: MyBlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
 
       nvim_runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
+      nvim_waitForLuaCode(input: PollLuaCodeClientInput): Chainable<RunLuaCodeOutput>
 
       /** Run an ex command in neovim.
        * @example "echo expand('%:.')" current file, relative to the cwd

package/src/server/dirtree/index.test.ts

@@ -63,6 +63,10 @@ describe("dirtree", () => {
                 name: z.literal("add_command_to_count_open_buffers.lua"),
                 type: z.literal("file"),
               }),
+              "add_command_to_update_buffer_after_timeout.lua": z.object({
+                name: z.literal("add_command_to_update_buffer_after_timeout.lua"),
+                type: z.literal("file"),
+              }),
               "don't_crash_when_modification_contains_unescaped_characters\\".lua": z.object({
                 name: z.literal("don't_crash_when_modification_contains_unescaped_characters\\".lua"),
                 type: z.literal("file"),
@@ -135,6 +139,7 @@ describe("dirtree", () => {
         ".config/nvim",
         ".config",
         "config-modifications/add_command_to_count_open_buffers.lua",
+        "config-modifications/add_command_to_update_buffer_after_timeout.lua",
         "config-modifications/don't_crash_when_modification_contains_unescaped_characters\\".lua",
         "config-modifications",
         "dir with spaces/file1.txt",

package/src/server/neovim/index.ts

@@ -16,6 +16,7 @@ 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 { timeout } from "../utilities/timeout.js"
 import type { StdoutOrStderrMessage, TerminalDimensions } from "./NeovimApplication.js"
 import { NeovimApplication } from "./NeovimApplication.js"
 import { prepareNewTestDirectory } from "./prepareNewTestDirectory.js"
@@ -154,6 +155,61 @@ export async function runLuaCode(options: LuaCodeInput): Promise<RunLuaCodeOutpu
   }
 }
 
+export type PollLuaCodeInput = {
+  luaAssertion: string
+  tabId: TabId
+}
+
+export async function waitForLuaCode(
+  options: PollLuaCodeInput,
+  signal: AbortSignal | undefined
+): Promise<RunLuaCodeOutput> {
+  const neovim = neovims.get(options.tabId.tabId)
+  assert(
+    neovim !== undefined,
+    `Neovim instance for clientId not found - cannot pollLuaCode. Maybe neovim's not started yet?`
+  )
+  assert(
+    neovim.application,
+    `Neovim application not found for client id ${options.tabId.tabId}. Maybe it's not started yet?`
+  )
+
+  const api = await neovim.state?.client.get()
+  if (!api) {
+    throw new Error(`Neovim API not available for client id ${options.tabId.tabId}. Maybe it's not started yet?`)
+  }
+
+  console.log(`Neovim ${neovim.application.processId()} polling Lua code: ${options.luaAssertion}`)
+
+  let running: boolean = true
+  signal?.addEventListener("abort", () => {
+    console.log(`Polling Lua code: '${options.luaAssertion}' was aborted via signal`)
+    running = false
+  })
+
+  const maxIterations = 100
+  for (let iteration = 1; iteration <= maxIterations; iteration++) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!running) {
+      throw new Error(`Polling Lua code: '${options.luaAssertion}' was aborted after ${iteration} iterations`)
+    }
+
+    try {
+      const value = await api.lua(options.luaAssertion)
+      console.log(`Lua code assertion passed: ${options.luaAssertion} (iteration ${iteration})`)
+
+      return { value }
+    } catch (e) {
+      console.error(`Caught error in iteration ${iteration}:`, e)
+      await timeout(100)
+    }
+  }
+
+  throw new Error(
+    `Polling Lua code: '${options.luaAssertion}' always raised an error after ${maxIterations} iterations`
+  )
+}
+
 export async function runExCommand(options: ExCommandInput): Promise<RunExCommandOutput> {
   const neovim = neovims.get(options.tabId.tabId)
   assert(

package/src/server/server.ts

@@ -15,6 +15,13 @@ const luaCodeInputSchema = z.object({ tabId: tabIdSchema, luaCode: z.string() })
 export type LuaCodeClientInput = Except<LuaCodeInput, "tabId">
 export type LuaCodeInput = z.infer<typeof luaCodeInputSchema>
 
+const pollLuaCodeInputSchema = z.object({
+  tabId: tabIdSchema,
+  luaAssertion: z.string(),
+  timeoutMs: z.number().optional().default(10_000),
+})
+export type PollLuaCodeClientInput = Except<z.input<typeof pollLuaCodeInputSchema>, "tabId">
+
 const exCommandInputSchema = z.object({
   tabId: tabIdSchema,
   command: z.string(),
@@ -108,6 +115,11 @@ export async function createAppRouter(config: DirectoriesConfig) {
         return timeoutable(10_000, neovim.runLuaCode(options.input))
       }),
 
+      waitForLuaCode: trpc.procedure.input(pollLuaCodeInputSchema).mutation(async options => {
+        const result = await timeoutable(options.input.timeoutMs, neovim.waitForLuaCode(options.input, options.signal))
+        return result
+      }),
+
       runExCommand: trpc.procedure.input(exCommandInputSchema).mutation(options => {
         return timeoutable(10_000, neovim.runExCommand(options.input))
       }),
@@ -120,26 +132,14 @@ export async function createAppRouter(config: DirectoriesConfig) {
 export type AppRouter = Awaited<ReturnType<typeof createAppRouter>>
 export type RouterInput = inferRouterInputs<AppRouter>
 
-export async function startTestServer(config: TestServerConfig): Promise<TestServer> {
+export async function startTestServer(config: TestServerConfig): Promise<void> {
   try {
     const testServer = new TestServer({
       port: config.port,
     })
     const appRouter = await createAppRouter(config.directories)
 
-    const neovimTask: Promise<void> = neovim
-      .installDependencies(config.directories.testEnvironmentPath, config.directories)
-      .catch((err: unknown) => {
-        console.error("Error installing neovim dependencies", err)
-        // suppress the error because neovim is optional - other applications
-        // can still be tested
-      })
-
-    const startServerTask = testServer.startAndRun(appRouter)
-
-    await Promise.all([neovimTask, startServerTask])
-
-    return testServer
+    await testServer.startAndRun(appRouter)
   } catch (err: unknown) {
     console.error("Error starting test server", err)
     throw err

package/src/server/utilities/timeout.ts

@@ -1,3 +1,3 @@
 export function timeout(ms: number): Promise<unknown> {
-  return new Promise((_, reject) => setTimeout(reject, ms))
+  return new Promise(resolve => setTimeout(resolve, ms))
 }

package/src/server/utilities/timeoutable.ts

@@ -1,15 +1,19 @@
-export async function timeoutable<T>(ms: number, promise: Promise<T>): Promise<T> {
-  let timeoutId: NodeJS.Timeout | undefined = undefined
-  const timeout = new Promise<void>((_, reject) => {
-    timeoutId = setTimeout(() => {
-      reject(new Error(`Timeout after ${ms}ms`))
-    }, ms)
+import assert from "node:assert"
+
+export async function timeoutable<T>(timeoutMs: number, promise: Promise<T>): Promise<T> {
+  let timeoutHandle: NodeJS.Timeout
+
+  const timeoutPromise = new Promise<T>((_, reject) => {
+    timeoutHandle = setTimeout(() => {
+      reject(new Error(`Operation timed out after ${timeoutMs}ms`))
+    }, timeoutMs)
   })
 
   try {
-    await Promise.race([timeout, promise])
-    return await promise
+    return await Promise.race([promise, timeoutPromise])
   } finally {
-    clearTimeout(timeoutId) // Ensure the timeout is cleared
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    assert(timeoutHandle!)
+    clearTimeout(timeoutHandle)
   }
 }