feat: add cy.runExCommand() to run Ex commands in Neovim (#160)

packages/integration-tests/cypress/e2e/neovim.cy.ts

@@ -171,4 +171,24 @@ describe("neovim features", () => {
       })
     })
   })
+
+  it("can runExCommand and get its result", () => {
+    cy.visit("/")
+    cy.startNeovim().then(() => {
+      // wait until text on the start screen is visible
+      cy.contains("If you see this text, Neovim is ready!")
+
+      cy.runExCommand({ command: "echo 'hello from ex command'" }).then(result => {
+        expect(result.value).to.equal("hello from ex command")
+      })
+
+      cy.contains("Hello from the subdirectory!").should("not.exist")
+      cy.runExCommand({ command: `vsplit ${"subdirectory/subdirectory-file.txt" satisfies MyTestDirectoryFile}` }).then(
+        result => {
+          expect(result.value).to.equal("")
+        }
+      )
+      cy.contains("Hello from the subdirectory!")
+    })
+  })
 })

packages/integration-tests/cypress/support/tui-sandbox.ts

@@ -2,9 +2,14 @@
 //
 // This file is autogenerated by tui-sandbox. Do not edit it directly.
 //
-import type { BlockingCommandClientInput, LuaCodeClientInput } from "@tui-sandbox/library/dist/src/server/server"
+import type {
+  BlockingCommandClientInput,
+  ExCommandClientInput,
+  LuaCodeClientInput,
+} from "@tui-sandbox/library/dist/src/server/server"
 import type {
   BlockingShellCommandOutput,
+  RunExCommandOutput,
   RunLuaCodeOutput,
   StartNeovimGenericArguments,
 } from "@tui-sandbox/library/dist/src/server/types"
@@ -21,6 +26,7 @@ declare global {
     startNeovim(startArguments?: MyStartNeovimServerArguments): Promise<NeovimContext>
     runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
     runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
+    runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
   }
 }
 
@@ -57,6 +63,12 @@ Cypress.Commands.add("runLuaCode", (input: LuaCodeClientInput) => {
   })
 })
 
+Cypress.Commands.add("runExCommand", (input: ExCommandClientInput) => {
+  cy.window().then(async win => {
+    return await win.runExCommand(input)
+  })
+})
+
 before(function () {
   // disable Cypress's default behavior of logging all XMLHttpRequests and
   // fetches to the Command Log
@@ -78,6 +90,8 @@ declare global {
       runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
 
       runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
+
+      runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
     }
   }
 }

packages/library/src/browser/neovim-client.ts

@@ -1,7 +1,8 @@
 import { TerminalClient } from "../client/index.js"
-import type { BlockingCommandClientInput, LuaCodeClientInput } from "../server/server.js"
+import type { BlockingCommandClientInput, ExCommandClientInput, LuaCodeClientInput } from "../server/server.js"
 import type {
   BlockingShellCommandOutput,
+  RunExCommandOutput,
   RunLuaCodeOutput,
   StartNeovimGenericArguments,
   TestDirectory,
@@ -35,10 +36,15 @@ window.runLuaCode = async function (input: LuaCodeClientInput): Promise<RunLuaCo
   return client.runLuaCode(input)
 }
 
+window.runExCommand = async function (input: ExCommandClientInput): Promise<RunExCommandOutput> {
+  return client.runExCommand(input)
+}
+
 declare global {
   interface Window {
     startNeovim(startArguments?: StartNeovimGenericArguments): Promise<TestDirectory>
     runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
     runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
+    runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
   }
 }

packages/library/src/client/terminal-client.ts

@@ -1,9 +1,15 @@
 import { createTRPCClient, httpBatchLink, splitLink, unstable_httpSubscriptionLink } from "@trpc/client"
 import type { Terminal } from "@xterm/xterm"
 import "@xterm/xterm/css/xterm.css"
-import type { AppRouter, BlockingCommandClientInput, LuaCodeClientInput } from "../server/server.js"
+import type {
+  AppRouter,
+  BlockingCommandClientInput,
+  ExCommandClientInput,
+  LuaCodeClientInput,
+} from "../server/server.js"
 import type {
   BlockingShellCommandOutput,
+  RunExCommandOutput,
   RunLuaCodeOutput,
   StartNeovimGenericArguments,
   TestDirectory,
@@ -105,4 +111,12 @@ export class TerminalClient {
       tabId: this.tabId,
     })
   }
+
+  public async runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput> {
+    await this.ready
+    return this.trpc.neovim.runExCommand.mutate({
+      command: input.command,
+      tabId: this.tabId,
+    })
+  }
 }

packages/library/src/server/cypress-support/contents.test.ts

@@ -7,9 +7,14 @@ it("should return the expected contents", async () => {
     //
     // This file is autogenerated by tui-sandbox. Do not edit it directly.
     //
-    import type { BlockingCommandClientInput, LuaCodeClientInput } from "@tui-sandbox/library/dist/src/server/server"
+    import type {
+      BlockingCommandClientInput,
+      ExCommandClientInput,
+      LuaCodeClientInput,
+    } from "@tui-sandbox/library/dist/src/server/server"
     import type {
       BlockingShellCommandOutput,
+      RunExCommandOutput,
       RunLuaCodeOutput,
       StartNeovimGenericArguments,
     } from "@tui-sandbox/library/dist/src/server/types"
@@ -26,6 +31,7 @@ it("should return the expected contents", async () => {
         startNeovim(startArguments?: MyStartNeovimServerArguments): Promise<NeovimContext>
         runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
         runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
+        runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
       }
     }
 
@@ -62,6 +68,12 @@ it("should return the expected contents", async () => {
       })
     })
 
+    Cypress.Commands.add("runExCommand", (input: ExCommandClientInput) => {
+      cy.window().then(async win => {
+        return await win.runExCommand(input)
+      })
+    })
+
     before(function () {
       // disable Cypress's default behavior of logging all XMLHttpRequests and
       // fetches to the Command Log
@@ -83,6 +95,8 @@ it("should return the expected contents", async () => {
           runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
 
           runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
+
+          runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
         }
       }
     }

packages/library/src/server/cypress-support/contents.ts

@@ -6,14 +6,18 @@ const __filename = fileURLToPath(import.meta.url)
 export async function createCypressSupportFileContents(): Promise<string> {
   // this is the interface of tui-sandbox as far as cypress in the user's
   // application is concerned
-  let text = `
-/// <reference types="cypress" />
+  let text = `/// <reference types="cypress" />
 //
 // This file is autogenerated by tui-sandbox. Do not edit it directly.
 //
-import type { BlockingCommandClientInput, LuaCodeClientInput } from "@tui-sandbox/library/dist/src/server/server"
+import type {
+  BlockingCommandClientInput,
+  ExCommandClientInput,
+  LuaCodeClientInput,
+} from "@tui-sandbox/library/dist/src/server/server"
 import type {
   BlockingShellCommandOutput,
+  RunExCommandOutput,
   RunLuaCodeOutput,
   StartNeovimGenericArguments,
 } from "@tui-sandbox/library/dist/src/server/types"
@@ -30,6 +34,7 @@ declare global {
     startNeovim(startArguments?: MyStartNeovimServerArguments): Promise<NeovimContext>
     runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
     runLuaCode(input: LuaCodeClientInput): Promise<RunLuaCodeOutput>
+    runExCommand(input: ExCommandClientInput): Promise<RunExCommandOutput>
   }
 }
 
@@ -66,6 +71,12 @@ Cypress.Commands.add("runLuaCode", (input: LuaCodeClientInput) => {
   })
 })
 
+Cypress.Commands.add("runExCommand", (input: ExCommandClientInput) => {
+  cy.window().then(async win => {
+    return await win.runExCommand(input)
+  })
+})
+
 before(function () {
   // disable Cypress's default behavior of logging all XMLHttpRequests and
   // fetches to the Command Log
@@ -87,6 +98,8 @@ declare global {
       runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
 
       runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
+
+      runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
     }
   }
 }

packages/library/src/server/neovim/index.ts

@@ -2,9 +2,10 @@ import assert from "assert"
 import { exec } from "child_process"
 import "core-js/proposals/async-explicit-resource-management.js"
 import util from "util"
-import type { BlockingCommandInput, LuaCodeInput } from "../server.js"
+import type { BlockingCommandInput, ExCommandInput, LuaCodeInput } from "../server.js"
 import type {
   BlockingShellCommandOutput,
+  RunExCommandOutput,
   RunLuaCodeOutput,
   StartNeovimGenericArguments,
   TestDirectory,
@@ -141,3 +142,29 @@ export async function runLuaCode(options: LuaCodeInput): Promise<RunLuaCodeOutpu
     throw new Error(`Error running Lua code: ${options.luaCode}`, { cause: e })
   }
 }
+
+export async function runExCommand(options: ExCommandInput): Promise<RunExCommandOutput> {
+  const neovim = neovims.get(options.tabId.tabId)
+  assert(
+    neovim !== undefined,
+    `Neovim instance for clientId not found - cannot runExCommand. 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()} running Ex command: ${options.command}`)
+  try {
+    const output = await api.commandOutput(options.command)
+    return { value: output }
+  } catch (e) {
+    console.warn(`Error running Ex command: ${options.command}`, e)
+    throw new Error(`Error running Ex command: ${options.command}`, { cause: e })
+  }
+}

packages/library/src/server/server.ts

@@ -29,6 +29,10 @@ const luaCodeInputSchema = z.object({ tabId: tabIdSchema, luaCode: z.string() })
 export type LuaCodeClientInput = Except<LuaCodeInput, "tabId">
 export type LuaCodeInput = z.infer<typeof luaCodeInputSchema>
 
+const exCommandInputSchema = z.object({ tabId: tabIdSchema, command: z.string() })
+export type ExCommandClientInput = Except<ExCommandInput, "tabId">
+export type ExCommandInput = z.infer<typeof exCommandInputSchema>
+
 /** @private */
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 export async function createAppRouter(config: TestServerConfig) {
@@ -80,6 +84,10 @@ export async function createAppRouter(config: TestServerConfig) {
       runLuaCode: trpc.procedure.input(luaCodeInputSchema).mutation(options => {
         return neovim.runLuaCode(options.input)
       }),
+
+      runExCommand: trpc.procedure.input(exCommandInputSchema).mutation(options => {
+        return neovim.runExCommand(options.input)
+      }),
     }),
   })
 

packages/library/src/server/types.ts

@@ -49,3 +49,5 @@ export type RunLuaCodeOutput = {
   value?: VimValue
   // to catch errors, use pcall() in the Lua code
 }
+
+export type RunExCommandOutput = { value?: string }