@tui-sandbox/library 9.2.0 → 9.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tui-sandbox/library",
-  "version": "9.2.0",
+  "version": "9.3.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -8,8 +8,8 @@
   },
   "dependencies": {
     "@catppuccin/palette": "1.7.1",
-    "@trpc/client": "11.0.0-rc.768",
-    "@trpc/server": "11.0.0-rc.768",
+    "@trpc/client": "11.0.0-rc.795",
+    "@trpc/server": "11.0.0-rc.795",
     "@xterm/addon-attach": "0.11.0",
     "@xterm/addon-fit": "0.10.0",
     "@xterm/xterm": "5.5.0",
@@ -21,8 +21,8 @@
     "neovim": "5.3.0",
     "node-pty": "1.0.0",
     "prettier": "3.5.1",
-    "tsx": "4.19.2",
-    "type-fest": "4.34.1",
+    "tsx": "4.19.3",
+    "type-fest": "4.35.0",
     "winston": "3.17.0",
     "zod": "3.24.2"
   },
@@ -33,8 +33,8 @@
     "@types/express": "5.0.0",
     "@types/node": "22.13.4",
     "nodemon": "3.1.9",
-    "vite": "6.1.0",
-    "vitest": "3.0.5"
+    "vite": "6.1.1",
+    "vitest": "3.0.6"
   },
   "peerDependencies": {
     "cypress": "^13 || ^14",

package/src/browser/neovim-client.ts

@@ -1,6 +1,7 @@
 import { TerminalClient as NeovimTerminalClient } from "../client/index.js"
 import { TerminalTerminalClient } from "../client/terminal-terminal-client.js"
-import type { BlockingCommandClientInput, ExCommandClientInput, LuaCodeClientInput } from "../server/server.js"
+import type { BlockingCommandClientInput } from "../server/blockingCommandInputSchema.js"
+import type { ExCommandClientInput, LuaCodeClientInput } from "../server/server.js"
 import type { StartTerminalGenericArguments } from "../server/terminal/TerminalTestApplication.js"
 import type {
   BlockingShellCommandOutput,

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

@@ -1,12 +1,8 @@
 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,
-  ExCommandClientInput,
-  LuaCodeClientInput,
-} from "../server/server.js"
+import type { BlockingCommandClientInput } from "../server/blockingCommandInputSchema.js"
+import type { AppRouter, ExCommandClientInput, LuaCodeClientInput } from "../server/server.js"
 import type {
   BlockingShellCommandOutput,
   RunExCommandOutput,

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

@@ -1,7 +1,8 @@
 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 } from "../server/server.js"
+import type { BlockingCommandClientInput } from "../server/blockingCommandInputSchema.js"
+import type { AppRouter } from "../server/server.js"
 import type { StartTerminalGenericArguments } from "../server/terminal/TerminalTestApplication.js"
 import type { BlockingShellCommandOutput, TestDirectory } from "../server/types.js"
 import "./style.css"

package/src/server/blockingCommandInputSchema.test.ts

@@ -0,0 +1,23 @@
+import { blockingCommandInputSchema, type BlockingCommandInput } from "./blockingCommandInputSchema.js"
+
+describe("blockingCommandInputSchema", () => {
+  it("allows either cwd or cwdRelative but not both", () => {
+    // It doesn't make sense to have two sources of truth for the cwd.
+    const fails = blockingCommandInputSchema.safeParse({
+      command: "command",
+      tabId: { tabId: "123" },
+      cwd: "cwd",
+      cwdRelative: "cwdRelative",
+    } satisfies Partial<BlockingCommandInput>)
+
+    expect(fails.error).toMatchInlineSnapshot(`
+      [ZodError: [
+        {
+          "code": "custom",
+          "message": "Both cwd and cwdRelative provided. Please provide either but not both at the same time.",
+          "path": []
+        }
+      ]]
+    `)
+  })
+})

package/src/server/blockingCommandInputSchema.ts

@@ -0,0 +1,28 @@
+import "core-js/proposals/async-explicit-resource-management.js"
+import type { Except } from "type-fest"
+import { z } from "zod"
+import { tabIdSchema } from "./utilities/tabId.js"
+
+export const blockingCommandInputSchema = z
+  .object({
+    command: z.string(),
+    shell: z.string().optional(),
+    tabId: tabIdSchema,
+    allowFailure: z.boolean().optional(),
+
+    // absolute cwd
+    cwd: z.string().optional(),
+    cwdRelative: z.string().optional(),
+    envOverrides: z.record(z.string()).optional(),
+    uid: z.number().optional(),
+    gid: z.number().optional(),
+  })
+  .refine(
+    data =>
+      // disallow both cwd and cwdRelative
+      !(data.cwd && data.cwdRelative),
+    { message: "Both cwd and cwdRelative provided. Please provide either but not both at the same time." }
+  )
+
+export type BlockingCommandClientInput = Except<BlockingCommandInput, "tabId">
+export type BlockingCommandInput = z.infer<typeof blockingCommandInputSchema>

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

@@ -14,11 +14,7 @@ import type {
   GenericNeovimBrowserApi,
   GenericTerminalBrowserApi,
 } from "@tui-sandbox/library/dist/src/browser/neovim-client"
-import type {
-  BlockingCommandClientInput,
-  ExCommandClientInput,
-  LuaCodeClientInput,
-} from "@tui-sandbox/library/dist/src/server/server"
+import type { ExCommandClientInput, LuaCodeClientInput } from "@tui-sandbox/library/dist/src/server/server"
 import type {
   BlockingShellCommandOutput,
   RunExCommandOutput,
@@ -26,6 +22,7 @@ import type {
   StartNeovimGenericArguments,
   TestDirectory,
 } from "@tui-sandbox/library/dist/src/server/types"
+import type { BlockingCommandClientInput } from "@tui-sandbox/library/src/server/blockingCommandInputSchema"
 import type { StartTerminalGenericArguments } from "@tui-sandbox/library/src/server/terminal/TerminalTestApplication"
 import type { OverrideProperties } from "type-fest"
 import type { MyTestDirectory, MyTestDirectoryFile } from "../../MyTestDirectory"
@@ -37,7 +34,7 @@ export type TerminalTestApplicationContext = {
 
   /** Runs a shell command in a blocking manner, waiting for the command to
    * finish before returning. Requires the terminal to be running. */
-  runBlockingShellCommand(input: BlockingCommandClientInput): Cypress.Chainable<BlockingShellCommandOutput>
+  runBlockingShellCommand(input: MyBlockingCommandClientInput): Cypress.Chainable<BlockingShellCommandOutput>
 
   /** The test directory, providing type-safe access to its file and directory structure */
   dir: TestDirectory<MyTestDirectory>
@@ -51,7 +48,7 @@ export type NeovimContext = {
 
   /** Runs a shell command in a blocking manner, waiting for the command to
    * finish before returning. Requires neovim to be running. */
-  runBlockingShellCommand(input: BlockingCommandClientInput): Cypress.Chainable<BlockingShellCommandOutput>
+  runBlockingShellCommand(input: MyBlockingCommandClientInput): Cypress.Chainable<BlockingShellCommandOutput>
 
   /** Runs a shell command in a blocking manner, waiting for the command to
    * finish before returning. Requires neovim to be running. */
@@ -112,7 +109,21 @@ Cypress.Commands.add("startNeovim", (startArguments?: MyStartNeovimServerArgumen
 
 Cypress.Commands.add("startTerminalApplication", (args: StartTerminalGenericArguments) => {
   cy.window().then(async win => {
-    const api: GenericTerminalBrowserApi = await win.startTerminalApplication(args)
+    const terminal: GenericTerminalBrowserApi = await win.startTerminalApplication(args)
+
+    Cypress.Commands.addAll({
+      terminal_runBlockingShellCommand: terminal.runBlockingShellCommand,
+    })
+
+    const api: TerminalTestApplicationContext = {
+      dir: terminal.dir as TestDirectory<MyTestDirectory>,
+      runBlockingShellCommand(input) {
+        return cy.terminal_runBlockingShellCommand(input)
+      },
+      typeIntoTerminal(text, options) {
+        cy.typeIntoTerminal(text, options)
+      },
+    }
 
     return api
   })
@@ -133,6 +144,11 @@ before(function () {
   cy.intercept({ resourceType: /xhr|fetch/ }, { log: false })
 })
 
+export type MyBlockingCommandClientInput = OverrideProperties<
+  BlockingCommandClientInput,
+  { cwdRelative?: MyTestDirectoryFile | undefined }
+>
+
 declare global {
   namespace Cypress {
     interface Chainable {
@@ -145,7 +161,7 @@ declare global {
 
       /** Runs a shell command in a blocking manner, waiting for the command to
        * finish before returning. Requires neovim to be running. */
-      nvim_runBlockingShellCommand(input: BlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
+      nvim_runBlockingShellCommand(input: MyBlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
 
       nvim_runLuaCode(input: LuaCodeClientInput): Chainable<RunLuaCodeOutput>
 
@@ -153,6 +169,8 @@ declare global {
        * @example "echo expand('%:.')" current file, relative to the cwd
        */
       nvim_runExCommand(input: ExCommandClientInput): Chainable<RunExCommandOutput>
+
+      terminal_runBlockingShellCommand(input: MyBlockingCommandClientInput): Chainable<BlockingShellCommandOutput>
     }
   }
 }

package/src/server/neovim/index.ts

@@ -2,7 +2,8 @@ import assert from "assert"
 import "core-js/proposals/async-explicit-resource-management.js"
 import { access } from "fs/promises"
 import path from "path"
-import type { BlockingCommandInput, ExCommandInput, LuaCodeInput } from "../server.js"
+import type { BlockingCommandInput } from "../blockingCommandInputSchema.js"
+import type { ExCommandInput, LuaCodeInput } from "../server.js"
 import { executeBlockingShellCommand } from "../terminal/runBlockingShellCommand.js"
 import type {
   BlockingShellCommandOutput,
@@ -124,7 +125,7 @@ export async function runBlockingShellCommand(
   assert(testDirectory, `Test directory not found for client id ${input.tabId.tabId}. Maybe neovim's not started yet?`)
 
   const env = neovim.getEnvironmentVariables(testDirectory, input.envOverrides)
-  return executeBlockingShellCommand(input, signal, allowFailure, env)
+  return executeBlockingShellCommand(testDirectory, input, signal, allowFailure, env)
 }
 
 export async function runLuaCode(options: LuaCodeInput): Promise<RunLuaCodeOutput> {

package/src/server/server.ts

@@ -2,6 +2,7 @@ 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 { blockingCommandInputSchema } from "./blockingCommandInputSchema.js"
 import { trpc } from "./connection/trpc.js"
 import * as neovim from "./neovim/index.js"
 import * as terminal from "./terminal/index.js"
@@ -9,22 +10,6 @@ import { TestServer } from "./TestServer.js"
 import type { DirectoriesConfig, TestServerConfig } from "./updateTestdirectorySchemaFile.js"
 import { tabIdSchema } from "./utilities/tabId.js"
 
-const blockingCommandInputSchema = z.object({
-  command: z.string(),
-  shell: z.string().optional(),
-  tabId: tabIdSchema,
-  allowFailure: z.boolean().optional(),
-
-  // child_process.ProcessEnvOptions
-  uid: z.number().optional(),
-  gid: z.number().optional(),
-  cwd: z.string().optional(),
-  envOverrides: z.record(z.string()).optional(),
-})
-
-export type BlockingCommandClientInput = Except<BlockingCommandInput, "tabId">
-export type BlockingCommandInput = z.infer<typeof blockingCommandInputSchema>
-
 const luaCodeInputSchema = z.object({ tabId: tabIdSchema, luaCode: z.string() })
 export type LuaCodeClientInput = Except<LuaCodeInput, "tabId">
 export type LuaCodeInput = z.infer<typeof luaCodeInputSchema>

package/src/server/terminal/index.ts

@@ -1,8 +1,8 @@
 import assert from "assert"
 import "core-js/proposals/async-explicit-resource-management.js"
+import type { BlockingCommandInput } from "../blockingCommandInputSchema.js"
 import type { TerminalDimensions } from "../neovim/NeovimApplication.js"
 import { prepareNewTestDirectory } from "../neovim/prepareNewTestDirectory.js"
-import type { BlockingCommandInput } from "../server.js"
 import type { BlockingShellCommandOutput } from "../types.js"
 import type { DirectoriesConfig } from "../updateTestdirectorySchemaFile.js"
 import { convertEventEmitterToAsyncGenerator } from "../utilities/generator.js"
@@ -81,5 +81,5 @@ export async function runBlockingShellCommand(
   assert(testDirectory, `Test directory not found for client id ${input.tabId.tabId}. Maybe neovim's not started yet?`)
 
   const env = app.getEnvironmentVariables(testDirectory, input.envOverrides)
-  return executeBlockingShellCommand(input, signal, allowFailure, env)
+  return executeBlockingShellCommand(testDirectory, input, signal, allowFailure, env)
 }

package/src/server/terminal/runBlockingShellCommand.test.ts

@@ -0,0 +1,40 @@
+import { getCwd } from "./runBlockingShellCommand.js"
+
+describe("getCwd", () => {
+  it("prefers cwdRelative if it is defined", () => {
+    // in many cases this is what the user wants to do, so prefer that
+
+    const result = getCwd({
+      rootPathAbsolute: "/root-absolute",
+      cwdRelative: "test-cwd-relative",
+      cwdAbsolute: "/test-cwd",
+      home: "/test-home",
+    })
+    expect(result).toEqual("/root-absolute/test-cwd-relative")
+  })
+
+  it("falls back to cwd if cwdRelative is not defined", () => {
+    // this is used when the user wants to use absolute paths
+
+    const result = getCwd({
+      rootPathAbsolute: "/root-absolute",
+      cwdRelative: undefined,
+      cwdAbsolute: "/test-cwd",
+      home: "/test-home",
+    })
+    expect(result).toEqual("/test-cwd")
+  })
+
+  it("falls back to HOME if neither cwdRelative nor cwd are defined", () => {
+    // if the user doesn't specify anything, we default to the home directory
+    // because a directory must be present when running the command
+
+    const result = getCwd({
+      rootPathAbsolute: "/root-absolute",
+      cwdRelative: undefined,
+      cwdAbsolute: undefined,
+      home: "/test-home",
+    })
+    expect(result).toEqual("/test-home")
+  })
+})

package/src/server/terminal/runBlockingShellCommand.ts

@@ -1,10 +1,12 @@
 import { exec } from "child_process"
 import "core-js/proposals/async-explicit-resource-management.js"
+import { join } from "path"
 import util from "util"
-import type { BlockingCommandInput } from "../server.js"
-import type { BlockingShellCommandOutput } from "../types.js"
+import type { BlockingCommandInput } from "../blockingCommandInputSchema.js"
+import type { BlockingShellCommandOutput, TestDirectory } from "../types.js"
 
 export async function executeBlockingShellCommand(
+  testDirectory: TestDirectory,
   input: BlockingCommandInput,
   signal: AbortSignal | undefined,
   allowFailure: boolean,
@@ -12,19 +14,22 @@ export async function executeBlockingShellCommand(
 ): Promise<BlockingShellCommandOutput> {
   const execPromise = util.promisify(exec)
 
-  const cwd = input.cwd ?? env["HOME"]
-
-  const processPromise = execPromise(input.command, {
-    signal: signal,
-    shell: input.shell,
-    uid: input.uid,
-    gid: input.gid,
-    cwd: cwd,
-    env,
+  const cwd = getCwd({
+    rootPathAbsolute: testDirectory.rootPathAbsolute,
+    cwdRelative: input.cwdRelative,
+    cwdAbsolute: input.cwd,
+    home: testDirectory.rootPathAbsolute,
   })
 
   try {
-    const result = await processPromise
+    const result = await execPromise(input.command, {
+      signal: signal,
+      shell: input.shell,
+      uid: input.uid,
+      gid: input.gid,
+      cwd,
+      env,
+    })
     console.log(
       `Successfully ran shell blockingCommand (${input.command}) with stdout: ${result.stdout}, stderr: ${result.stderr}`
     )
@@ -43,3 +48,16 @@ export async function executeBlockingShellCommand(
     throw new Error(`Error running shell blockingCommand (${input.command})`, { cause: e })
   }
 }
+
+export type GetCwdArguments = {
+  rootPathAbsolute: string
+  cwdRelative: string | undefined
+  cwdAbsolute: string | undefined
+  home: string
+}
+export function getCwd(args: GetCwdArguments): string {
+  if (args.cwdRelative) {
+    return join(args.rootPathAbsolute, args.cwdRelative)
+  }
+  return args.cwdAbsolute ?? args.home
+}