@tui-sandbox/library 6.0.2 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "6.0.2",
+  "version": "7.0.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
     "@types/command-exists": "1.2.3",
     "@types/cors": "2.8.17",
     "@types/express": "5.0.0",
-    "@types/node": "22.9.0",
+    "@types/node": "22.9.1",
     "nodemon": "3.1.7",
     "vite": "5.4.11",
     "vitest": "2.1.5"

package/src/browser/neovim-client.ts

@@ -1,12 +1,13 @@
-import { NeovimClient } from "../client/index.js"
-import type { StartNeovimGenericArguments, TestDirectory } from "../server/types.js"
+import { TerminalClient } from "../client/index.js"
+import type { BlockingCommandClientInput } from "../server/server.js"
+import type { BlockingShellCommandOutput, StartNeovimGenericArguments, TestDirectory } from "../server/types.js"
 
 const app = document.querySelector<HTMLElement>("#app")
 if (!app) {
   throw new Error("No app element found")
 }
 
-const client = new NeovimClient(app)
+const client = new TerminalClient(app)
 
 /** Entrypoint for the test runner (cypress) */
 window.startNeovim = async function (startArgs?: StartNeovimGenericArguments): Promise<TestDirectory> {
@@ -19,8 +20,15 @@ window.startNeovim = async function (startArgs?: StartNeovimGenericArguments): P
   return testDirectory
 }
 
+window.runBlockingShellCommand = async function (
+  input: BlockingCommandClientInput
+): Promise<BlockingShellCommandOutput> {
+  return client.runBlockingShellCommand(input)
+}
+
 declare global {
   interface Window {
     startNeovim(startArguments?: StartNeovimGenericArguments): Promise<TestDirectory>
+    runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
   }
 }

package/src/client/index.ts

@@ -1,4 +1,4 @@
 // This is the public client api. Semantic versioning will be applied to this.
 
 export { rgbify } from "./color-utilities.js"
-export { NeovimClient } from "./neovim-client.js"
+export { TerminalClient } from "./terminal-client.js"

package/src/client/{neovim-client.ts → terminal-client.ts}

@@ -1,12 +1,14 @@
 import { createTRPCClient, httpBatchLink, splitLink, unstable_httpSubscriptionLink } from "@trpc/client"
 import type { Terminal } from "@xterm/xterm"
 import "@xterm/xterm/css/xterm.css"
-import type { AppRouter } from "../server/server.ts"
-import type { StartNeovimGenericArguments, TestDirectory } from "../server/types.js"
+import type { AppRouter, BlockingCommandClientInput } from "../server/server.js"
+import type { BlockingShellCommandOutput, StartNeovimGenericArguments, TestDirectory } from "../server/types.js"
 import "./style.css"
 import { getTabId, startTerminal } from "./websocket-client.js"
 
-export class NeovimClient {
+/** Manages the terminal state in the browser as well as the (browser's)
+ * connection to the server side terminal application api. */
+export class TerminalClient {
   private readonly ready: Promise<void>
   private readonly tabId: { tabId: string }
   private readonly terminal: Terminal
@@ -82,4 +84,12 @@ export class NeovimClient {
 
     return testDirectory
   }
+
+  public async runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput> {
+    await this.ready
+    return this.trpc.neovim.runBlockingShellCommand.mutate({
+      ...input,
+      tabId: this.tabId,
+    })
+  }
 }

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

@@ -7,7 +7,11 @@ it("should return the expected contents", async () => {
     //
     // This file is autogenerated by tui-sandbox. Do not edit it directly.
     //
-    import type { StartNeovimGenericArguments } from "@tui-sandbox/library/dist/src/server/types"
+    import type { BlockingCommandClientInput } from "@tui-sandbox/library/dist/src/server/server"
+    import type {
+      BlockingShellCommandOutput,
+      StartNeovimGenericArguments,
+    } from "@tui-sandbox/library/dist/src/server/types"
     import type { OverrideProperties } from "type-fest"
     import type { MyTestDirectory, MyTestDirectoryFile } from "../../MyTestDirectory"
 
@@ -19,6 +23,7 @@ it("should return the expected contents", async () => {
     declare global {
       interface Window {
         startNeovim(startArguments?: MyStartNeovimServerArguments): Promise<NeovimContext>
+        runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
       }
     }
 
@@ -37,6 +42,12 @@ it("should return the expected contents", async () => {
       })
     })
 
+    Cypress.Commands.add("runBlockingShellCommand", (input: BlockingCommandClientInput) => {
+      cy.window().then(async win => {
+        return await win.runBlockingShellCommand(input)
+      })
+    })
+
     Cypress.Commands.add("typeIntoTerminal", (text: string, options?: Partial<Cypress.TypeOptions>) => {
       // the syntax for keys is described here:
       // https://docs.cypress.io/api/commands/type
@@ -54,7 +65,14 @@ it("should return the expected contents", async () => {
       namespace Cypress {
         interface Chainable {
           startNeovim(args?: MyStartNeovimServerArguments): Chainable<NeovimContext>
+
+          /** Types text into the terminal, making the terminal application receive
+           * the keystrokes as input. Requires neovim to be running. */
           typeIntoTerminal(text: string, options?: Partial<Cypress.TypeOptions>): Chainable<void>
+
+          /** Runs a shell command in a blocking manner, waiting for the command to
+           * finish before returning. Requires neovim to be running. */
+          runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
         }
       }
     }

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

@@ -11,8 +11,12 @@ export async function createCypressSupportFileContents(): Promise<string> {
 //
 // This file is autogenerated by tui-sandbox. Do not edit it directly.
 //
+import type { BlockingCommandClientInput } from "@tui-sandbox/library/dist/src/server/server"
+import type {
+  BlockingShellCommandOutput,
+  StartNeovimGenericArguments,
+} from "@tui-sandbox/library/dist/src/server/types"
 import type { OverrideProperties } from "type-fest"
-import type { StartNeovimGenericArguments } from "@tui-sandbox/library/dist/src/server/types"
 import type { MyTestDirectory, MyTestDirectoryFile } from "../../MyTestDirectory"
 
 export type NeovimContext = {
@@ -23,6 +27,7 @@ export type NeovimContext = {
 declare global {
   interface Window {
     startNeovim(startArguments?: MyStartNeovimServerArguments): Promise<NeovimContext>
+    runBlockingShellCommand(input: BlockingCommandClientInput): Promise<BlockingShellCommandOutput>
   }
 }
 
@@ -41,6 +46,12 @@ Cypress.Commands.add("startNeovim", (startArguments?: MyStartNeovimServerArgumen
   })
 })
 
+Cypress.Commands.add("runBlockingShellCommand", (input: BlockingCommandClientInput) => {
+  cy.window().then(async win => {
+    return await win.runBlockingShellCommand(input)
+  })
+})
+
 Cypress.Commands.add("typeIntoTerminal", (text: string, options?: Partial<Cypress.TypeOptions>) => {
   // the syntax for keys is described here:
   // https://docs.cypress.io/api/commands/type
@@ -58,7 +69,14 @@ declare global {
   namespace Cypress {
     interface Chainable {
       startNeovim(args?: MyStartNeovimServerArguments): Chainable<NeovimContext>
+
+      /** Types text into the terminal, making the terminal application receive
+       * the keystrokes as input. Requires neovim to be running. */
       typeIntoTerminal(text: string, options?: Partial<Cypress.TypeOptions>): Chainable<void>
+
+      /** Runs a shell command in a blocking manner, waiting for the command to
+       * finish before returning. Requires neovim to be running. */
+      runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
     }
   }
 }

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

@@ -25,13 +25,14 @@ export async function createCypressSupportFile({
   try {
     oldSchema = readFileSync(outputFilePath, "utf-8")
   } catch (error) {
-    console.log(`No existing cypress support file found at ${outputFilePath}, creating a new one`)
+    console.log(`No existing cypress support file found at ${outputFilePath}`)
   }
 
   if (oldSchema !== text) {
     // it's important to not write the file if the schema hasn't changed
     // because file watchers will trigger on file changes and we don't want to
     // trigger a build if the schema hasn't changed
+    console.log(`🪛 Writing cypress support file to ${outputFilePath}`)
     writeFileSync(outputFilePath, text)
     return "updated"
   } else {

package/src/server/neovim/NeovimApplication.ts

@@ -76,7 +76,7 @@ type ResettableState = {
 }
 
 export class NeovimApplication {
-  private state: ResettableState | undefined
+  public state: ResettableState | undefined
   public readonly events: EventEmitter
 
   public constructor(
@@ -135,20 +135,7 @@ export class NeovimApplication {
     const stdout = this.events
 
     await this.application.startNextAndKillCurrent(async () => {
-      const env = {
-        ...process.env,
-        HOME: testDirectory.rootPathAbsolute,
-
-        // this is needed so that neovim can load its configuration, emulating
-        // a common setup real neovim users have
-        XDG_CONFIG_HOME: join(testDirectory.rootPathAbsolute, ".config"),
-        // the data directory is where lazy.nvim stores its plugins. To prevent
-        // downloading a new set of plugins for each test, share the data
-        // directory.
-        XDG_DATA_HOME: join(testDirectory.testEnvironmentPath, ".repro", "data"),
-
-        ...startArgs.additionalEnvironmentVariables,
-      }
+      const env = this.getEnvironmentVariables(testDirectory, startArgs.additionalEnvironmentVariables)
       return TerminalApplication.start({
         command: "nvim",
         args: neovimArguments,
@@ -176,6 +163,26 @@ export class NeovimApplication {
     console.log(`🚀 Started Neovim instance ${processId}`)
   }
 
+  public getEnvironmentVariables(
+    testDirectory: TestDirectory,
+    additionalEnvironmentVariables?: Record<string, string>
+  ): NodeJS.ProcessEnv {
+    return {
+      ...process.env,
+      HOME: testDirectory.rootPathAbsolute,
+
+      // this is needed so that neovim can load its configuration, emulating
+      // a common setup real neovim users have
+      XDG_CONFIG_HOME: join(testDirectory.rootPathAbsolute, ".config"),
+      // the data directory is where lazy.nvim stores its plugins. To prevent
+      // downloading a new set of plugins for each test, share the data
+      // directory.
+      XDG_DATA_HOME: join(testDirectory.testEnvironmentPath, ".repro", "data"),
+
+      ...additionalEnvironmentVariables,
+    }
+  }
+
   async [Symbol.asyncDispose](): Promise<void> {
     await this.application[Symbol.asyncDispose]()
 

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

@@ -23,7 +23,7 @@ class TempDirectory implements Disposable {
 
 it("should create a temp dir with no contents", async () => {
   // typically the user will want to have contents, but this should not be an error
-  await using dir = TempDirectory.create()
+  using dir = TempDirectory.create()
   const result = await createTempDir({
     testEnvironmentPath: dir.path,
     outputFilePath: nodePath.join(dir.path, "MyTestDirectory.ts"),

package/src/server/neovim/index.ts

@@ -1,5 +1,9 @@
 import assert from "assert"
-import type { StartNeovimGenericArguments, TestDirectory } from "../types.js"
+import { exec } from "child_process"
+import "core-js/proposals/async-explicit-resource-management.js"
+import util from "util"
+import type { BlockingCommandInput } from "../server.js"
+import type { BlockingShellCommandOutput, StartNeovimGenericArguments, TestDirectory } from "../types.js"
 import type { TestServerConfig } from "../updateTestdirectorySchemaFile.js"
 import { convertEventEmitterToAsyncGenerator } from "../utilities/generator.js"
 import type { TabId } from "../utilities/tabId.js"
@@ -61,3 +65,44 @@ export async function sendStdin(options: { tabId: TabId; data: string }): Promis
 
   await neovim.application.write(options.data)
 }
+
+export async function runBlockingShellCommand(
+  signal: AbortSignal | undefined,
+  input: BlockingCommandInput
+): Promise<BlockingShellCommandOutput> {
+  const neovim = neovims.get(input.tabId.tabId)
+  assert(
+    neovim !== undefined,
+    `Neovim instance for clientId not found - cannot run blocking shell command. Maybe neovim's not started yet?`
+  )
+  const testDirectory = neovim.state?.testDirectory
+  assert(testDirectory, `Test directory not found for client id ${input.tabId.tabId}. Maybe neovim's not started yet?`)
+
+  const execPromise = util.promisify(exec)
+  const env = neovim.getEnvironmentVariables(testDirectory, input.envOverrides)
+  const processPromise = execPromise(input.command, {
+    signal: signal,
+    shell: input.shell,
+    uid: input.uid,
+    gid: input.gid,
+    cwd: input.cwd ?? env["HOME"],
+    env,
+  })
+
+  try {
+    const result = await processPromise
+    console.log(
+      `Successfully ran shell blockingCommand (${input.command}) with stdout: ${result.stdout}, stderr: ${result.stderr}`
+    )
+    return {
+      type: "success",
+      stdout: result.stdout,
+      stderr: result.stderr,
+    } satisfies BlockingShellCommandOutput
+  } catch (e) {
+    console.warn(`Error running shell blockingCommand (${input.command})`, e)
+    return {
+      type: "failed",
+    }
+  }
+}

package/src/server/server.ts

@@ -1,5 +1,6 @@
 import type { inferRouterInputs } from "@trpc/server"
 import "core-js/proposals/async-explicit-resource-management.js"
+import type { Except } from "type-fest"
 import { z } from "zod"
 import { trpc } from "./connection/trpc.js"
 import * as neovim from "./neovim/index.js"
@@ -8,13 +9,20 @@ import type { TestServerConfig } from "./updateTestdirectorySchemaFile.js"
 import { applicationAvailable } from "./utilities/applicationAvailable.js"
 import { tabIdSchema } from "./utilities/tabId.js"
 
-/** Stack for managing resources that need to be disposed of when the server
- * shuts down */
-await using autocleanup = new AsyncDisposableStack()
-autocleanup.defer(() => {
-  console.log("Closing any open test applications")
+const blockingCommandInputSchema = z.object({
+  command: z.string(),
+  shell: z.string().optional(),
+  tabId: tabIdSchema,
+
+  // child_process.ProcessEnvOptions
+  uid: z.number().optional(),
+  gid: z.number().optional(),
+  cwd: z.string().optional(),
+  envOverrides: z.record(z.string()).optional(),
 })
-export { autocleanup }
+
+export type BlockingCommandClientInput = Except<BlockingCommandInput, "tabId">
+export type BlockingCommandInput = z.infer<typeof blockingCommandInputSchema>
 
 /** @private */
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
@@ -59,6 +67,10 @@ export async function createAppRouter(config: TestServerConfig) {
       sendStdin: trpc.procedure.input(z.object({ tabId: tabIdSchema, data: z.string() })).mutation(options => {
         return neovim.sendStdin(options.input)
       }),
+
+      runBlockingShellCommand: trpc.procedure.input(blockingCommandInputSchema).mutation(async options => {
+        return neovim.runBlockingShellCommand(options.signal, options.input)
+      }),
     }),
   })
 

package/src/server/types.ts

@@ -30,3 +30,15 @@ export type TestDirectory = {
 }
 
 export type { StartNeovimGenericArguments } from "../server/neovim/NeovimApplication.js"
+
+export type BlockingShellCommandOutput =
+  | {
+      type: "success"
+      stdout: string
+      stderr: string
+    }
+  | {
+      type: "failed"
+      // for now we log the error to the server's console output. It will be
+      // visible when running the tests.
+    }

package/dist/src/client/neovim-client.d.ts

@@ -1,11 +0,0 @@
-import "@xterm/xterm/css/xterm.css";
-import type { StartNeovimGenericArguments, TestDirectory } from "../server/types.js";
-import "./style.css";
-export declare class NeovimClient {
-    private readonly ready;
-    private readonly tabId;
-    private readonly terminal;
-    private readonly trpc;
-    constructor(app: HTMLElement);
-    startNeovim(args: StartNeovimGenericArguments): Promise<TestDirectory>;
-}