@tui-sandbox/library 11.11.1 → 12.0.0

package/src/server/types.ts

@@ -1,98 +0,0 @@
-import type { VimValue } from "neovim/lib/types/VimValue.js"
-import * as z from "zod"
-
-/** Describes the contents of the test directory, which is a blueprint for
- * files and directories. Tests can create a unique, safe environment for
- * interacting with the contents of such a directory.
- *
- * Having strong typing for the test directory contents ensures that tests can
- * be written with confidence that the files and directories they expect are
- * actually found. Otherwise the tests are brittle and can break easily.
- */
-export type TestDirectory<TContents extends Record<string, unknown> = Record<string, unknown>> = {
-  /** The path to the unique test directory (the root).
-   *
-   * @example /Users/mikavilpas/git/tui-sandbox/packages/integration-tests/test-environment/testdirs/dir-0199UZ
-   */
-  rootPathAbsolute: string
-
-  /** The path to the test environment directory, which is the blueprint for
-   *
-   * the test directory.
-   * @example /Users/mikavilpas/git/tui-sandbox/packages/integration-tests/test-environment
-   * */
-  testEnvironmentPath: string
-
-  /** The relative path from the {@link testEnvironmentPath} to {@link rootPathAbsolute}.
-   *
-   * @example testdirs/dir-0199UZ/
-   */
-  testEnvironmentPathRelative: string
-
-  latestEnvironmentSymlink: string
-
-  contents: TContents
-}
-
-export const serverTestDirectorySchema = z.object({
-  rootPathAbsolute: z.string(),
-  testEnvironmentPath: z.string(),
-  testEnvironmentPathRelative: z.string(),
-  latestEnvironmentSymlink: z.string(),
-  contents: z.record(z.string(), z.unknown()),
-})
-export type ServerTestDirectory = z.infer<typeof serverTestDirectorySchema>
-
-export type TestEnvironmentCommonEnvironmentVariables = {
-  HOME: string
-
-  /** This is needed so that the application being tested can load its
-   * configuration, emulating a common setup real users have
-   */
-  XDG_CONFIG_HOME: string
-
-  /** The data directory is where the application stores its data. To prevent
-   * downloading a new set of plugins/whatever for each test, share the data
-   * directory.
-   */
-  XDG_DATA_HOME: string
-
-  /** The path to the test environment directory, which is the blueprint for
-   * the test directory.
-   * @example /Users/mikavilpas/git/tui-sandbox/packages/integration-tests/test-environment
-   * */
-  TUI_SANDBOX_TEST_ENVIRONMENT_PATH: string
-}
-
-export type { StartNeovimGenericArguments } from "./applications/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.
-    }
-
-export type RunLuaCodeOutput = {
-  value?: VimValue
-  // to catch errors, use pcall() in the Lua code
-}
-
-export type RunExCommandOutput = { value?: string }
-
-/**
- * Require all of an object's keys to be set explicitly. This is useful for
- * readability: writing all the keys makes their presence explicit. They could
- * also be added via a spread operator (...obj), but in that case the following
- * cases are unclear:
- *
- * - extra keys might be included because TypeScript does not check for them
- * - if the target object type has optional keys, they might be missing. In
- *   this case, they will never get set
- **/
-export type AllKeys<T extends Record<never, never>> = Record<keyof T, unknown>

package/src/server/updateTestdirectorySchemaFile.test.ts

@@ -1,49 +0,0 @@
-import { readFileSync, writeFileSync } from "fs"
-import type { PartialDeep } from "type-fest"
-import { describe, expect, it, vi } from "vitest"
-import { buildTestDirectorySchema } from "./dirtree/index.js"
-import type { TestServerConfig, UpdateTestdirectorySchemaFileResult } from "./updateTestdirectorySchemaFile.js"
-import { updateTestdirectorySchemaFile } from "./updateTestdirectorySchemaFile.js"
-
-vi.mock("fs")
-vi.mock("./dirtree")
-vi.spyOn(console, "log").mockImplementation(vi.fn())
-
-const mock = {
-  readFileSync: vi.mocked(readFileSync),
-  writeFileSync: vi.mocked(writeFileSync),
-  buildTestDirectorySchema: vi.mocked(buildTestDirectorySchema),
-}
-
-describe("when the schema has not changed", () => {
-  it("does not write the file", async () => {
-    mock.buildTestDirectorySchema.mockResolvedValue("schema")
-    mock.readFileSync.mockImplementation(() => "schema")
-
-    const result = await updateTestdirectorySchemaFile({
-      directories: {
-        testEnvironmentPath: "path",
-        outputFilePath: "path",
-      },
-    } satisfies PartialDeep<TestServerConfig> as TestServerConfig)
-
-    expect(result).toBe("did-nothing" satisfies UpdateTestdirectorySchemaFileResult)
-  })
-})
-
-describe("when the schema has changed", () => {
-  it("writes the file", async () => {
-    mock.buildTestDirectorySchema.mockResolvedValue("new schema")
-    mock.readFileSync.mockImplementation(() => "old schema")
-
-    const result = await updateTestdirectorySchemaFile({
-      directories: {
-        testEnvironmentPath: "path",
-        outputFilePath: "path",
-      },
-    } satisfies PartialDeep<TestServerConfig> as TestServerConfig)
-
-    expect(result).toBe("updated" satisfies UpdateTestdirectorySchemaFileResult)
-    expect(mock.writeFileSync).toHaveBeenCalledWith("path", "new schema")
-  })
-})

package/src/server/updateTestdirectorySchemaFile.ts

@@ -1,71 +0,0 @@
-import { readFileSync, writeFileSync } from "fs"
-import { debuglog } from "util"
-import * as z from "zod"
-import { buildTestDirectorySchema } from "./dirtree/index.js"
-
-const log = debuglog(`tui-sandbox.${updateTestdirectorySchemaFile.name}`)
-
-export type DirectoriesConfig = TestServerConfig["directories"]
-
-export type TestServerConfig = z.output<typeof testServerConfigSchema>
-
-export type TestServerConfigMetadata = {
-  configFilePath: string
-  config: TestServerConfig
-}
-
-export type Dictionary = Record<string, string>
-
-export type CustomizeEnv = (env: Dictionary) => Promise<Dictionary>
-
-export type CustomizeMiseEnvironmentVariables = (
-  env: Dictionary,
-  defaultImplementation: CustomizeEnv
-) => Promise<Record<string, string>>
-
-export type NeovimIntegrationDefaultAppName = "nvim"
-const neovimIntegration = z.strictObject({
-  NVIM_APPNAMEs: z
-    .array(z.string())
-    .min(1)
-    .default(["nvim" satisfies NeovimIntegrationDefaultAppName]),
-})
-
-export type NeovimIntegrationConfig = z.output<typeof neovimIntegration>
-
-export const testServerConfigSchema = z.strictObject({
-  directories: z.object({
-    testEnvironmentPath: z.string(),
-    outputFilePath: z.string(),
-    latestSymlinkName: z.string().optional().default("latest"),
-  }),
-  port: z.number().int().min(1).max(65535),
-  integrations: z.strictObject({
-    neovim: neovimIntegration,
-  }),
-})
-
-export type UpdateTestdirectorySchemaFileResult = "updated" | "did-nothing"
-
-export async function updateTestdirectorySchemaFile(
-  config: TestServerConfig
-): Promise<UpdateTestdirectorySchemaFileResult> {
-  const newSchema: string = await buildTestDirectorySchema(config)
-  let oldSchema = ""
-
-  try {
-    oldSchema = readFileSync(config.directories.outputFilePath, "utf-8")
-  } catch {
-    log("No existing schema file found, creating a new one")
-  }
-
-  if (oldSchema !== newSchema) {
-    // 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
-    writeFileSync(config.directories.outputFilePath, newSchema)
-    return "updated"
-  } else {
-    return "did-nothing"
-  }
-}

package/src/server/utilities/DisposableSingleApplication.test.ts

@@ -1,92 +0,0 @@
-import { describe, expect, it, vi } from "vitest"
-import type { StartableApplication } from "./DisposableSingleApplication.js"
-import { DisposableSingleApplication } from "./DisposableSingleApplication.js"
-import type { ExitInfo } from "./TerminalApplication.js"
-
-vi.spyOn(console, "log").mockImplementation(vi.fn())
-
-class TestDisposableSingleApplication extends DisposableSingleApplication {
-  public getApplication() {
-    return this.application
-  }
-}
-
-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", () => {
-    const app = new TestDisposableSingleApplication()
-    expect(app.processId()).toBeUndefined()
-    expect(app.getApplication()).toBeUndefined()
-  })
-
-  it("can start an application", async () => {
-    const app = new TestDisposableSingleApplication()
-    await app.startNextAndKillCurrent(async () => fakeApp)
-    expect(app.processId()).toBe(123)
-    expect(app.getApplication()).toBe(fakeApp)
-  })
-
-  it("can write to the application", async () => {
-    const app = new TestDisposableSingleApplication()
-    await app.startNextAndKillCurrent(async () => fakeApp)
-    await app.write("hello")
-    expect(fakeApp.write).toHaveBeenCalledWith("hello")
-  })
-
-  it("fails to write if the application is not started", async () => {
-    // there is no need to support soft failing in the ui, so we do hard
-    // failing to make this error obvious
-    const app = new TestDisposableSingleApplication()
-    await expect(app.write("hello")).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[AssertionError: The application not started yet. It makes no sense to write to it, so this looks like a bug.]`
-    )
-  })
-
-  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
-      // starting new tests or ending the user session entirely and closing the
-      // application
-      const app = new TestDisposableSingleApplication()
-
-      await app.startNextAndKillCurrent(async () => fakeApp)
-      expect(app.getApplication()).toBe(fakeApp)
-
-      await app[Symbol.asyncDispose]()
-      expect(fakeApp.killAndWait).toHaveBeenCalledOnce()
-    })
-
-    it("does nothing if there is no application to dispose", async () => {
-      const app = new TestDisposableSingleApplication()
-      expect(app.getApplication()).toBeUndefined()
-      expect(app.processId()).toBeUndefined()
-
-      expect(() => app[Symbol.asyncDispose]()).not.toThrow()
-    })
-  })
-})

package/src/server/utilities/DisposableSingleApplication.ts

@@ -1,49 +0,0 @@
-import assert from "assert"
-import { debuglog } from "util"
-import type { ExitInfo, TerminalApplication } from "./TerminalApplication.js"
-
-export type StartableApplication = Pick<TerminalApplication, "write" | "processId" | "killAndWait" | "untilExit">
-
-const log = debuglog("tui-sandbox.DisposableSingleApplication")
-
-/** 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
- * a time.
- */
-export class DisposableSingleApplication implements AsyncDisposable {
-  protected application: StartableApplication | undefined
-
-  public async startNextAndKillCurrent(startNext: () => Promise<StartableApplication>): Promise<void> {
-    await this[Symbol.asyncDispose]()
-    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,
-      "The application not started yet. It makes no sense to write to it, so this looks like a bug."
-    )
-    this.application.write(input)
-  }
-
-  public processId(): number | undefined {
-    return this.application?.processId
-  }
-
-  /** Kill the current application if it exists. */
-  public async [Symbol.asyncDispose](): Promise<void> {
-    if (this.processId() === undefined) {
-      return
-    }
-    log(`Killing current application ${this.processId()}...`)
-    await this.application?.killAndWait()
-  }
-}

package/src/server/utilities/Lazy.ts

@@ -1,16 +0,0 @@
-export class Lazy<T> {
-  private value?: T
-
-  constructor(private readonly factory: () => T) {}
-
-  get(): T {
-    if (this.value === undefined) {
-      this.value = this.factory()
-    }
-    return this.value
-  }
-
-  set(value: T): void {
-    this.value = value
-  }
-}

package/src/server/utilities/TerminalApplication.ts

@@ -1,100 +0,0 @@
-import type winston from "winston"
-import { createLogger, format, transports } from "winston"
-
-import type { ITerminalDimensions } from "@xterm/addon-fit"
-import type { IPty } from "node-pty"
-import pty from "node-pty"
-import { debuglog } from "util"
-import type { StartableApplication } from "./DisposableSingleApplication.js"
-
-const log = debuglog("tui-sandbox.TerminalApplication")
-
-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 {
-  public readonly processId: number
-
-  public readonly logger: winston.Logger
-
-  private constructor(
-    private readonly subProcess: IPty,
-    public readonly onStdoutOrStderr: (data: string) => void,
-    public readonly untilExit: Promise<ExitInfo>,
-    public readonly name: string
-  ) {
-    this.processId = subProcess.pid
-
-    this.logger = createLogger({
-      transports: [new transports.Console()],
-      defaultMeta: { pid: this.processId },
-      format: format.combine(format.colorize(), format.cli()),
-    })
-
-    this.logger.debug(`started`)
-
-    subProcess.onExit(({ exitCode, signal }) => {
-      signal satisfies number | undefined
-      const msg = `Child process ${this.processId} (${this.name}) exited with code ${String(exitCode)} and signal ${String(signal)}`
-      this.onStdoutOrStderr(msg)
-      this.logger.debug(msg)
-    })
-  }
-
-  /** @constructor Start a new terminal application. */
-  public static start({
-    onStdoutOrStderr,
-    command,
-    args,
-    cwd,
-    env,
-    dimensions,
-  }: {
-    onStdoutOrStderr: (data: string) => void
-    command: string
-    args: string[]
-    cwd: string
-    env?: NodeJS.ProcessEnv
-    dimensions: ITerminalDimensions
-  }): TerminalApplication {
-    log(`Starting '${command}' with args '${args.join(" ")}' in cwd '${cwd}'`)
-
-    const ptyProcess = pty.spawn(command, args, {
-      name: "xterm-color",
-      cwd,
-      env,
-      cols: dimensions.cols,
-      rows: dimensions.rows,
-    })
-    ptyProcess.onData(onStdoutOrStderr)
-    ptyProcess.onExit(({ exitCode, signal }) => {
-      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, untilExit, ptyProcess.process satisfies string)
-  }
-
-  /** Write to the terminal's stdin. */
-  public write(data: string): void {
-    this.subProcess.write(data)
-  }
-
-  public async killAndWait(): Promise<void> {
-    log(`💣 Killing process ${this.processId}`)
-    this.subProcess.kill()
-    log(`💥 Killed process ${this.processId}`)
-  }
-}

package/src/server/utilities/generator.test.ts

@@ -1,50 +0,0 @@
-import { EventEmitter } from "stream"
-import { describe, expect, it } from "vitest"
-import { convertEventEmitterToAsyncGenerator } from "./generator.js"
-
-describe("when a listener is attached", () => {
-  it("forwards events from an EventEmitter to an async generator", async () => {
-    const eventEmitter = new EventEmitter()
-    const generator = convertEventEmitterToAsyncGenerator(eventEmitter, "test")
-
-    {
-      const promise = generator.next()
-      eventEmitter.emit("test", "message")
-
-      expect(await promise).toMatchInlineSnapshot(`
-        {
-          "done": false,
-          "value": "message",
-        }
-      `)
-
-      const promise2 = generator.next()
-      eventEmitter.emit("test", "message2")
-
-      expect(await promise2).toMatchInlineSnapshot(`
-        {
-          "done": false,
-          "value": "message2",
-        }
-      `)
-    }
-  })
-})
-
-describe("when no listener is attached, messages are lost permanently", () => {
-  it("does not resend lost events after a subscriber attaches", async () => {
-    const eventEmitter = new EventEmitter()
-    eventEmitter.emit("test", "this message should be lost")
-
-    const generator = convertEventEmitterToAsyncGenerator(eventEmitter, "test")
-    const promise = generator.next()
-    eventEmitter.emit("test", "new message that will be received")
-
-    expect(await promise).toMatchInlineSnapshot(`
-      {
-        "done": false,
-        "value": "new message that will be received",
-      }
-    `)
-  })
-})

package/src/server/utilities/generator.ts

@@ -1,12 +0,0 @@
-import type EventEmitter from "events"
-
-export async function* convertEventEmitterToAsyncGenerator(
-  emitter: EventEmitter,
-  eventName: string
-): AsyncGenerator<string, void, unknown> {
-  while (true) {
-    yield await new Promise(resolve => {
-      emitter.once(eventName, resolve)
-    })
-  }
-}

package/src/server/utilities/tabId.ts

@@ -1,4 +0,0 @@
-import * as z from "zod"
-
-export type TabId = z.infer<typeof tabIdSchema>
-export const tabIdSchema = z.object({ tabId: z.string() })

package/src/server/utilities/timeout.ts

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

package/src/server/utilities/timeoutable.ts

@@ -1,19 +0,0 @@
-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 {
-    return await Promise.race([promise, timeoutPromise])
-  } finally {
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    assert(timeoutHandle!)
-    clearTimeout(timeoutHandle)
-  }
-}

package/tsconfig.json

@@ -1,31 +0,0 @@
-{
-  "compilerOptions": {
-    "skipLibCheck": true,
-    "module": "NodeNext",
-    "sourceMap": true,
-    "noImplicitOverride": true,
-    "noPropertyAccessFromIndexSignature": true,
-    "noUncheckedIndexedAccess": true,
-    "moduleResolution": "NodeNext",
-    "target": "ES2022",
-    "isolatedModules": true,
-    "esModuleInterop": true,
-    "allowJs": true,
-    "outDir": "dist",
-    "lib": ["ES2023", "ESNext.Disposable"],
-    "types": ["node", "cypress"],
-    "composite": true,
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": false,
-    "noUnusedParameters": true,
-    "noFallthroughCasesInSwitch": true
-  },
-
-  "include": [
-    //
-    "./src/",
-    "src/scripts/tui.ts"
-  ]
-}

package/vite.config.js

@@ -1,27 +0,0 @@
-import { defineConfig } from "vite"
-
-// https://vitejs.dev/config/
-export default defineConfig({
-  server: {
-    host: "127.0.0.1",
-    https: false,
-    strictPort: true,
-    proxy: {
-      // inside @tui-sandbox/library, a vite development server can be used. It
-      // will proxy requests to the backend.
-      //
-      // When running in production, the backend starts its own static file
-      // server that is used (in development, it's just ignored).
-      "/trpc": "http://localhost:3000",
-    },
-  },
-  build: {
-    outDir: "./dist/browser/",
-  },
-  test: {
-    exclude: ["node_modules", "dist"],
-    globals: true, // This will make describe, it, etc. available globally
-    environment: "node",
-    mockReset: true,
-  },
-})