@tui-sandbox/library 0.0.0

package/src/server/dirtree/index.ts

@@ -0,0 +1,114 @@
+import assert from "assert"
+import type { Dree } from "dree"
+import { scan, Type } from "dree"
+import { format, resolveConfig } from "prettier"
+import { fileURLToPath } from "url"
+import { jsonToZod } from "./json-to-zod"
+
+type TreeResult = { dree: Dree; allFiles: Dree[] }
+
+/** Convert a directory tree to a TypeScript type. This is useful for testing
+ * as the initial state of the test directory is fully known in tests. */
+export function getDirectoryTree(path: string): TreeResult {
+  const allFiles: Dree[] = []
+  const result = scan(
+    path,
+    {
+      exclude: [/.repro/, /testdirs/],
+      hash: false,
+      size: false,
+      sizeInBytes: false,
+    },
+    file => {
+      allFiles.push(file)
+    },
+    dir => {
+      allFiles.push(dir)
+    }
+  )
+
+  return { dree: result, allFiles }
+}
+
+type FileNode = {
+  type: Type.FILE
+  name: string
+  extension: string | undefined
+  stem: string
+}
+type DirectoryNode = {
+  type: Type.DIRECTORY
+  name: string
+  contents: Record<string, TreeNode>
+}
+
+type TreeNode = FileNode | DirectoryNode
+
+export function convertDree(root: Dree): TreeNode {
+  if (root.type === Type.FILE) {
+    return {
+      name: root.name,
+      type: root.type,
+      extension: root.extension,
+      stem: root.extension ? root.name.slice(0, -root.extension.length) : root.name,
+    }
+  }
+
+  assert(root.children)
+  const node: DirectoryNode = {
+    name: root.name,
+    type: root.type,
+    contents: {},
+  }
+  for (const child of root.children) {
+    node.contents[child.name] = convertDree(child)
+  }
+
+  return node
+}
+
+export async function buildSchemaForDirectoryTree(result: TreeResult, name: string): Promise<string> {
+  const root = result.dree
+  assert(root.type === Type.DIRECTORY)
+  const node = convertDree(root)
+  const schema = (await jsonToZod(node, `${name}Schema`)).split("\n")
+
+  const lines = `
+// Note: This file is autogenerated. Do not edit it directly.
+//
+// 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.
+`.split("\n")
+
+  const allFilePaths = result.allFiles.map(f => f.relativePath)
+  const ContentsSchema = `${name}ContentsSchema`
+  const ContentsSchemaType = `${name}ContentsSchemaType`
+  return [
+    ...lines,
+    ...schema,
+    `export const ${ContentsSchema} = ${name}Schema.shape.contents`,
+    `export type ${ContentsSchemaType} = z.infer<typeof ${name}Schema>`,
+    "",
+    `export type ${name} = ${ContentsSchemaType}["contents"]`,
+    "",
+    `export const testDirectoryFiles = z.enum(${JSON.stringify(allFilePaths, null, 2)})`,
+    `export type MyTestDirectoryFile = z.infer<typeof testDirectoryFiles>`,
+  ].join("\n")
+}
+
+const __filename = fileURLToPath(import.meta.url)
+
+export async function buildTestDirectorySchema(testDirectoryPath: string): Promise<string> {
+  const dree = getDirectoryTree(testDirectoryPath)
+  let text = await buildSchemaForDirectoryTree(dree, "MyTestDirectory")
+
+  const options = await resolveConfig(__filename)
+  text = await format(text, { ...options, parser: "typescript" })
+
+  return text
+}

package/src/server/dirtree/json-to-zod.ts

@@ -0,0 +1,58 @@
+import { format, resolveConfig } from "prettier"
+import babelParser from "prettier/parser-babel"
+import { fileURLToPath } from "url"
+
+const __filename = fileURLToPath(import.meta.url)
+
+export async function jsonToZod(object: unknown, name: string = "schema"): Promise<string> {
+  const parse = (o: unknown, seen: object[]): string => {
+    switch (typeof o) {
+      case "string":
+        return `z.literal("${o}")`
+      case "number":
+        return "z.number()"
+      case "bigint":
+        return "z.number().int()"
+      case "boolean":
+        return "z.boolean()"
+      case "object":
+        if (o === null) {
+          return "z.null()"
+        }
+        if (seen.find(_obj => Object.is(_obj, o))) {
+          throw new Error("Circular objects are not supported")
+        }
+        seen.push(o)
+        if (Array.isArray(o)) {
+          const options = o
+            .map(obj => parse(obj, seen))
+            .reduce((acc: string[], curr: string) => (acc.includes(curr) ? acc : [...acc, curr]), [])
+          if (options.length === 1) {
+            return `z.array(${options[0]})`
+          } else if (options.length > 1) {
+            // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+            return `z.array(z.union([${options}]))`
+          } else {
+            return `z.array(z.unknown())`
+          }
+        }
+        // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+        return `z.object({${Object.entries(o).map(([k, v]) => `'${k}':${parse(v, seen)}`)}})`
+      case "undefined":
+        return "z.undefined()"
+      case "function":
+        return "z.function()"
+      case "symbol":
+      default:
+        return "z.unknown()"
+    }
+  }
+
+  const prettierConfig = await resolveConfig(__filename)
+
+  return format(`import {z} from "zod"\n\nexport const ${name}=${parse(object, [])}`, {
+    ...(prettierConfig || {}),
+    parser: "babel",
+    plugins: [babelParser],
+  })
+}

package/src/server/index.ts

@@ -0,0 +1,54 @@
+import type { AnyRouter } from "@trpc/server"
+import { applyWSSHandler } from "@trpc/server/adapters/ws"
+import "core-js/proposals/async-explicit-resource-management"
+import { once } from "events"
+import { WebSocketServer } from "ws"
+import { createContext } from "./connection/trpc"
+import type { TestServerConfig } from "./updateTestdirectorySchemaFile"
+import { updateTestdirectorySchemaFile } from "./updateTestdirectorySchemaFile"
+
+export class TestServer {
+  public constructor(private readonly port: number) {}
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+  public async startAndRun<TRouter extends AnyRouter>(appRouter: TRouter, config: TestServerConfig): Promise<void> {
+    console.log("🚀 Server starting")
+
+    await updateTestdirectorySchemaFile(config)
+
+    const wss = new WebSocketServer({ port: this.port })
+    const handler = applyWSSHandler<TRouter>({
+      wss,
+      router: appRouter,
+      createContext,
+      // Enable heartbeat messages to keep connection open (disabled by default)
+      keepAlive: {
+        enabled: true,
+        // server ping message interval in milliseconds
+        pingMs: 30_000,
+        // connection is terminated if pong message is not received in this many milliseconds
+        pongWaitMs: 5000,
+      },
+    })
+
+    wss.on("connection", socket => {
+      console.log(`➕➕ Connection (${wss.clients.size})`)
+      socket.once("close", () => {
+        console.log(`➖➖ Connection (${wss.clients.size})`)
+      })
+    })
+    console.log(`✅ WebSocket Server listening on ws://localhost:${this.port}`)
+
+    await Promise.race([once(process, "SIGTERM"), once(process, "SIGINT")])
+    console.log("Shutting down...")
+    handler.broadcastReconnectNotification()
+    wss.close(error => {
+      if (error) {
+        console.error("Error closing WebSocket server", error)
+        process.exit(1)
+      }
+      console.log("WebSocket server closed")
+      process.exit(0)
+    })
+  }
+}

package/src/server/neovim/NeovimApplication.ts

@@ -0,0 +1,134 @@
+import { exec } from "child_process"
+import EventEmitter from "events"
+import { existsSync } from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+import type { TestDirectory } from "../types"
+import { DisposableSingleApplication } from "../utilities/DisposableSingleApplication"
+import { TerminalApplication } from "../utilities/TerminalApplication"
+
+/*
+
+Usage:
+  nvim [options] [file ...]
+
+Options:
+  --cmd <cmd>           Execute <cmd> before any config
+  +<cmd>, -c <cmd>      Execute <cmd> after config and first file
+  -l <script> [args...] Execute Lua <script> (with optional args)
+  -S <session>          Source <session> after loading the first file
+  -s <scriptin>         Read Normal mode commands from <scriptin>
+  -u <config>           Use this config file
+
+  -d                    Diff mode
+  -es, -Es              Silent (batch) mode
+  -h, --help            Print this help message
+  -i <shada>            Use this shada file
+  -n                    No swap file, use memory only
+  -o[N]                 Open N windows (default: one per file)
+  -O[N]                 Open N vertical windows (default: one per file)
+  -p[N]                 Open N tab pages (default: one per file)
+  -R                    Read-only (view) mode
+  -v, --version         Print version information
+  -V[N][file]           Verbose [level][file]
+
+  --                    Only file names after this
+  --api-info            Write msgpack-encoded API metadata to stdout
+  --clean               "Factory defaults" (skip user config and plugins, shada)
+  --embed               Use stdin/stdout as a msgpack-rpc channel
+  --headless            Don't start a user interface
+  --listen <address>    Serve RPC API from this address
+  --remote[-subcommand] Execute commands remotely on a server
+  --server <address>    Specify RPC server to send commands to
+  --startuptime <file>  Write startup timing messages to <file>
+
+See ":help startup-options" for all options.
+
+$ nvim --version
+NVIM v0.11.0-dev-608+g9d74dc3ac
+Build type: Release
+LuaJIT 2.1.1720049189
+Run "nvim -V1 -v" for more info
+
+*/
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url))
+export type StdoutMessage = "stdout"
+
+export type StartNeovimGenericArguments = {
+  terminalDimensions?: { cols: number; rows: number }
+  filename?: string | { openInVerticalSplits: string[] }
+  startupScriptModifications?: string[]
+}
+
+export class NeovimApplication extends DisposableSingleApplication {
+  private testDirectory: TestDirectory | undefined
+  public readonly events: EventEmitter
+
+  public constructor(private readonly testEnvironmentPath: string) {
+    super()
+    this.events = new EventEmitter()
+  }
+
+  /**
+   * Kill the current application and start a new one with the given arguments.
+   */
+  public async startNextAndKillCurrent(
+    testDirectory: TestDirectory,
+    startArgs: StartNeovimGenericArguments
+  ): Promise<void> {
+    await this[Symbol.asyncDispose]()
+    this.testDirectory = testDirectory
+
+    const neovimArguments = ["-u", "test-setup.lua"]
+
+    if (startArgs.startupScriptModifications) {
+      for (const modification of startArgs.startupScriptModifications) {
+        const file = path.join(testDirectory.rootPathAbsolute, "config-modifications", modification)
+        if (!existsSync(file)) {
+          throw new Error(`startupScriptModifications file does not exist: ${file}`)
+        }
+
+        neovimArguments.push("-c", `lua dofile('${file}')`)
+      }
+    }
+
+    if (!startArgs.filename) {
+      startArgs.filename = "initial-file.txt"
+    }
+
+    if (typeof startArgs.filename === "string") {
+      const file = path.join(testDirectory.rootPathAbsolute, startArgs.filename)
+      neovimArguments.push(file)
+    } else if (startArgs.filename.openInVerticalSplits.length > 0) {
+      // `-O[N]` Open N vertical windows (default: one per file)
+      neovimArguments.push("-O")
+
+      for (const file of startArgs.filename.openInVerticalSplits) {
+        const filePath = path.join(testDirectory.rootPathAbsolute, file)
+        neovimArguments.push(filePath)
+      }
+    }
+    const stdout = this.events
+
+    this.application = TerminalApplication.start({
+      command: "nvim",
+      args: neovimArguments,
+
+      cwd: this.testEnvironmentPath,
+      env: process.env,
+      dimensions: startArgs.terminalDimensions,
+
+      onStdoutOrStderr(data: string) {
+        stdout.emit("stdout" satisfies StdoutMessage, data)
+      },
+    })
+  }
+
+  override async [Symbol.asyncDispose](): Promise<void> {
+    await super.killCurrent()
+    if (this.testDirectory) {
+      exec(`rm -rf ${this.testDirectory.rootPathAbsolute}`)
+    }
+  }
+}

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

@@ -0,0 +1,46 @@
+import assert from "assert"
+import { execSync } from "child_process"
+import { Type } from "dree"
+import { constants, readdirSync } from "fs"
+import { access, mkdir, mkdtemp } from "fs/promises"
+import path from "path"
+import { convertDree, getDirectoryTree } from "../../dirtree"
+import type { TestDirectory } from "../../types"
+import type { TestServerConfig } from "../../updateTestdirectorySchemaFile"
+import { updateTestdirectorySchemaFile } from "../../updateTestdirectorySchemaFile"
+
+export async function createTempDir(config: TestServerConfig): Promise<TestDirectory> {
+  try {
+    const dir = await createUniqueDirectory(config.testEnvironmentPath)
+
+    readdirSync(config.testEnvironmentPath).forEach(entry => {
+      if (entry === "testdirs") return
+      if (entry === ".repro") return
+
+      execSync(`cp -a '${path.join(config.testEnvironmentPath, entry)}' ${dir}/`)
+    })
+    console.log(`Created test directory at ${dir}`)
+
+    const tree = convertDree(getDirectoryTree(dir).dree)
+    assert(tree.type === Type.DIRECTORY)
+
+    await updateTestdirectorySchemaFile(config)
+    return { rootPathAbsolute: dir, contents: tree.contents }
+  } catch (err) {
+    console.error(err)
+    throw err
+  }
+}
+
+async function createUniqueDirectory(testEnvironmentPath: string): Promise<string> {
+  const testdirs = path.join(testEnvironmentPath, "testdirs")
+  try {
+    await access(testdirs, constants.F_OK)
+  } catch {
+    await mkdir(testdirs)
+  }
+  const dir = await mkdtemp(path.join(testdirs, "dir-"))
+  assert(typeof dir === "string")
+
+  return dir
+}

package/src/server/neovim/index.ts

@@ -0,0 +1,63 @@
+import type { Observable } from "@trpc/server/observable"
+import { observable } from "@trpc/server/observable"
+import assert from "assert"
+import type { TestDirectory } from "../types"
+import type { TestServerConfig } from "../updateTestdirectorySchemaFile"
+import type { TabId } from "../utilities/tabId"
+import { createTempDir } from "./environment/createTempDir"
+import type { StartNeovimGenericArguments, StdoutMessage } from "./NeovimApplication"
+import { NeovimApplication } from "./NeovimApplication"
+
+const neovims = new Map<TabId["tabId"], NeovimApplication>()
+
+export function onStdout(options: { client: TabId }, testEnvironmentPath: string): Observable<string, unknown> {
+  return observable<string>(emit => {
+    const tabId = options.client.tabId
+    const neovim = neovims.get(tabId) ?? new NeovimApplication(testEnvironmentPath)
+    if (neovims.get(tabId) === undefined) {
+      neovims.set(tabId, neovim)
+    }
+
+    const send = (data: unknown) => {
+      assert(typeof data === "string")
+      emit.next(data)
+    }
+
+    neovim.events.on("stdout" satisfies StdoutMessage, send)
+
+    return () => {
+      neovim.events.off("stdout" satisfies StdoutMessage, send)
+      void neovim[Symbol.asyncDispose]().finally(() => {
+        neovims.delete(tabId)
+      })
+    }
+  })
+}
+
+export async function start(
+  options: StartNeovimGenericArguments,
+  tabId: TabId,
+  config: TestServerConfig
+): Promise<TestDirectory> {
+  const neovim = neovims.get(tabId.tabId)
+  assert(neovim, `Neovim instance not found for client id ${tabId.tabId}`)
+
+  const testDirectory = await createTempDir(config)
+  await neovim.startNextAndKillCurrent(testDirectory, options)
+
+  const processId = neovim.processId()
+  assert(processId !== undefined, "Neovim was started without a process ID. This is a bug - please open an issue.")
+  console.log(`🚀 Started Neovim instance ${processId}`)
+
+  return testDirectory
+}
+
+export async function sendStdin(options: { tabId: TabId; data: string }): Promise<void> {
+  const neovim = neovims.get(options.tabId.tabId)
+  assert(
+    neovim !== undefined,
+    `Neovim instance for clientId not found - cannot send stdin. Maybe it's not started yet?`
+  )
+
+  await neovim.write(options.data)
+}

package/src/server/server.ts

@@ -0,0 +1,67 @@
+import type { inferRouterInputs } from "@trpc/server"
+import { z } from "zod"
+import { TestServer } from "."
+import { trpc } from "./connection/trpc"
+import * as neovim from "./neovim"
+import type { TestServerConfig } from "./updateTestdirectorySchemaFile"
+import { tabIdSchema } from "./utilities/tabId"
+
+/** 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")
+})
+export { autocleanup }
+
+function createAppRouter(config: TestServerConfig) {
+  const appRouter = trpc.router({
+    neovim: trpc.router({
+      start: trpc.procedure
+        .input(
+          z.object({
+            tabId: tabIdSchema,
+            terminalDimensions: z
+              .object({
+                cols: z.number(),
+                rows: z.number(),
+              })
+              .optional(),
+            startNeovimArguments: z.object({
+              filename: z
+                .union([
+                  z.string(),
+                  z.object({
+                    openInVerticalSplits: z.array(z.string()),
+                  }),
+                ])
+                .optional(),
+              startupScriptModifications: z.array(z.string()).optional(),
+            }),
+          })
+        )
+        .mutation(options => {
+          return neovim.start(options.input, options.input.tabId, config)
+        }),
+      onStdout: trpc.procedure.input(z.object({ client: tabIdSchema })).subscription(options => {
+        return neovim.onStdout(options.input, config.testEnvironmentPath)
+      }),
+      sendStdin: trpc.procedure.input(z.object({ tabId: tabIdSchema, data: z.string() })).mutation(options => {
+        return neovim.sendStdin(options.input)
+      }),
+    }),
+  })
+
+  return appRouter
+}
+
+export type AppRouter = ReturnType<typeof createAppRouter>
+export type RouterInput = inferRouterInputs<AppRouter>
+
+export async function startTestServer(config: TestServerConfig): Promise<TestServer> {
+  const testServer = new TestServer(3000)
+  const appRouter = createAppRouter(config)
+  await testServer.startAndRun(appRouter, config)
+
+  return testServer
+}

package/src/server/types.ts

@@ -0,0 +1,13 @@
+/** 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 = {
+  /** The path to the unique test directory (the root). */
+  rootPathAbsolute: string
+  contents: object
+}

package/src/server/updateTestdirectorySchemaFile.ts

@@ -0,0 +1,23 @@
+import "core-js/proposals/async-explicit-resource-management"
+import { readFileSync, writeFileSync } from "fs"
+import { buildTestDirectorySchema } from "./dirtree"
+
+export type TestServerConfig = {
+  testEnvironmentPath: string
+  outputFilePath: string
+}
+
+export async function updateTestdirectorySchemaFile({
+  testEnvironmentPath,
+  outputFilePath,
+}: TestServerConfig): Promise<void> {
+  const newSchema = await buildTestDirectorySchema(testEnvironmentPath)
+  const oldSchema = readFileSync(outputFilePath, "utf-8")
+
+  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(outputFilePath, newSchema)
+  }
+}

package/src/server/utilities/DisposableSingleApplication.ts

@@ -0,0 +1,33 @@
+import type { TerminalApplication } from "./TerminalApplication"
+
+/** 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 (1 to 1 mapping).
+ *
+ * @typeParam T The type of context the tests should have, e.g. information
+ * about a custom directory that the application is running in.
+ *
+ */
+export abstract class DisposableSingleApplication implements AsyncDisposable {
+  protected application: TerminalApplication | undefined
+
+  public async killCurrent(): Promise<void> {
+    await this.application?.killAndWait()
+  }
+
+  public async write(input: string): Promise<void> {
+    return this.application?.write(input)
+  }
+
+  public processId(): number | undefined {
+    return this.application?.processId
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    if (this.processId() === undefined) {
+      return
+    }
+    console.log(`Killing current application ${this.processId()}...`)
+    await this.killCurrent()
+  }
+}

package/src/server/utilities/Lazy.ts

@@ -0,0 +1,12 @@
+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
+  }
+}