@tui-sandbox/library 0.0.0

package/dist/src/server/neovim/NeovimApplication.js

@@ -0,0 +1,111 @@
+import { exec } from "child_process";
+import EventEmitter from "events";
+import { existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+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 class NeovimApplication extends DisposableSingleApplication {
+    testEnvironmentPath;
+    testDirectory;
+    events;
+    constructor(testEnvironmentPath) {
+        super();
+        this.testEnvironmentPath = testEnvironmentPath;
+        this.events = new EventEmitter();
+    }
+    /**
+     * Kill the current application and start a new one with the given arguments.
+     */
+    async startNextAndKillCurrent(testDirectory, startArgs) {
+        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) {
+                stdout.emit("stdout", data);
+            },
+        });
+    }
+    async [Symbol.asyncDispose]() {
+        await super.killCurrent();
+        if (this.testDirectory) {
+            exec(`rm -rf ${this.testDirectory.rootPathAbsolute}`);
+        }
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { TestDirectory } from "../../types";
+import type { TestServerConfig } from "../../updateTestdirectorySchemaFile";
+export declare function createTempDir(config: TestServerConfig): Promise<TestDirectory>;

package/dist/src/server/neovim/environment/createTempDir.js

@@ -0,0 +1,41 @@
+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 { updateTestdirectorySchemaFile } from "../../updateTestdirectorySchemaFile";
+export async function createTempDir(config) {
+    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) {
+    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/dist/src/server/neovim/index.d.ts

@@ -0,0 +1,13 @@
+import type { Observable } from "@trpc/server/observable";
+import type { TestDirectory } from "../types";
+import type { TestServerConfig } from "../updateTestdirectorySchemaFile";
+import type { TabId } from "../utilities/tabId";
+import type { StartNeovimGenericArguments } from "./NeovimApplication";
+export declare function onStdout(options: {
+    client: TabId;
+}, testEnvironmentPath: string): Observable<string, unknown>;
+export declare function start(options: StartNeovimGenericArguments, tabId: TabId, config: TestServerConfig): Promise<TestDirectory>;
+export declare function sendStdin(options: {
+    tabId: TabId;
+    data: string;
+}): Promise<void>;

package/dist/src/server/neovim/index.js

@@ -0,0 +1,40 @@
+import { observable } from "@trpc/server/observable";
+import assert from "assert";
+import { createTempDir } from "./environment/createTempDir";
+import { NeovimApplication } from "./NeovimApplication";
+const neovims = new Map();
+export function onStdout(options, testEnvironmentPath) {
+    return observable(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) => {
+            assert(typeof data === "string");
+            emit.next(data);
+        };
+        neovim.events.on("stdout", send);
+        return () => {
+            neovim.events.off("stdout", send);
+            void neovim[Symbol.asyncDispose]().finally(() => {
+                neovims.delete(tabId);
+            });
+        };
+    });
+}
+export async function start(options, tabId, config) {
+    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) {
+    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/dist/src/server/server.d.ts

@@ -0,0 +1,59 @@
+import type { inferRouterInputs } from "@trpc/server";
+import { TestServer } from ".";
+import type { TestServerConfig } from "./updateTestdirectorySchemaFile";
+/** Stack for managing resources that need to be disposed of when the server
+ * shuts down */
+declare const autocleanup: AsyncDisposableStack;
+export { autocleanup };
+declare function createAppRouter(config: TestServerConfig): import("@trpc/server/unstable-core-do-not-import").BuiltRouter<{
+    ctx: import("./connection/trpc").Connection;
+    meta: object;
+    errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
+    transformer: false;
+}, import("@trpc/server/unstable-core-do-not-import").DecorateCreateRouterOptions<{
+    neovim: import("@trpc/server/unstable-core-do-not-import").BuiltRouter<{
+        ctx: import("./connection/trpc").Connection;
+        meta: object;
+        errorShape: import("@trpc/server/unstable-core-do-not-import").DefaultErrorShape;
+        transformer: false;
+    }, {
+        start: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                tabId: {
+                    tabId: string;
+                };
+                startNeovimArguments: {
+                    filename?: string | {
+                        openInVerticalSplits: string[];
+                    } | undefined;
+                    startupScriptModifications?: string[] | undefined;
+                };
+                terminalDimensions?: {
+                    cols: number;
+                    rows: number;
+                } | undefined;
+            };
+            output: import("./types").TestDirectory;
+        }>;
+        onStdout: import("@trpc/server").TRPCSubscriptionProcedure<{
+            input: {
+                client: {
+                    tabId: string;
+                };
+            };
+            output: string;
+        }>;
+        sendStdin: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                tabId: {
+                    tabId: string;
+                };
+                data: string;
+            };
+            output: void;
+        }>;
+    }>;
+}>>;
+export type AppRouter = ReturnType<typeof createAppRouter>;
+export type RouterInput = inferRouterInputs<AppRouter>;
+export declare function startTestServer(config: TestServerConfig): Promise<TestServer>;

package/dist/src/server/server.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { TestServer } from ".";
+import { trpc } from "./connection/trpc";
+import * as neovim from "./neovim";
+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) {
+    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 async function startTestServer(config) {
+    const testServer = new TestServer(3000);
+    const appRouter = createAppRouter(config);
+    await testServer.startAndRun(appRouter, config);
+    return testServer;
+}

package/dist/src/server/types.d.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/dist/src/server/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/server/updateTestdirectorySchemaFile.d.ts

@@ -0,0 +1,6 @@
+import "core-js/proposals/async-explicit-resource-management";
+export type TestServerConfig = {
+    testEnvironmentPath: string;
+    outputFilePath: string;
+};
+export declare function updateTestdirectorySchemaFile({ testEnvironmentPath, outputFilePath, }: TestServerConfig): Promise<void>;

package/dist/src/server/updateTestdirectorySchemaFile.js

@@ -0,0 +1,13 @@
+import "core-js/proposals/async-explicit-resource-management";
+import { readFileSync, writeFileSync } from "fs";
+import { buildTestDirectorySchema } from "./dirtree";
+export async function updateTestdirectorySchemaFile({ testEnvironmentPath, outputFilePath, }) {
+    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/dist/src/server/utilities/DisposableSingleApplication.d.ts

@@ -0,0 +1,16 @@
+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 declare abstract class DisposableSingleApplication implements AsyncDisposable {
+    protected application: TerminalApplication | undefined;
+    killCurrent(): Promise<void>;
+    write(input: string): Promise<void>;
+    processId(): number | undefined;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/dist/src/server/utilities/DisposableSingleApplication.js

@@ -0,0 +1,27 @@
+/** 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 class DisposableSingleApplication {
+    application;
+    async killCurrent() {
+        await this.application?.killAndWait();
+    }
+    async write(input) {
+        return this.application?.write(input);
+    }
+    processId() {
+        return this.application?.processId;
+    }
+    async [Symbol.asyncDispose]() {
+        if (this.processId() === undefined) {
+            return;
+        }
+        console.log(`Killing current application ${this.processId()}...`);
+        await this.killCurrent();
+    }
+}

package/dist/src/server/utilities/Lazy.d.ts

@@ -0,0 +1,6 @@
+export declare class Lazy<T> {
+    private readonly factory;
+    private value?;
+    constructor(factory: () => T);
+    get(): T;
+}

package/dist/src/server/utilities/Lazy.js

@@ -0,0 +1,13 @@
+export class Lazy {
+    factory;
+    value;
+    constructor(factory) {
+        this.factory = factory;
+    }
+    get() {
+        if (this.value === undefined) {
+            this.value = this.factory();
+        }
+        return this.value;
+    }
+}

package/dist/src/server/utilities/TerminalApplication.d.ts

@@ -0,0 +1,21 @@
+import winston from "winston";
+import type { ITerminalDimensions } from "@xterm/addon-fit";
+export declare class TerminalApplication {
+    private readonly subProcess;
+    readonly onStdoutOrStderr: (data: string) => void;
+    readonly processId: number;
+    readonly logger: winston.Logger;
+    private constructor();
+    /** @constructor Start a new terminal application. */
+    static start({ onStdoutOrStderr, command, args, cwd, env, dimensions: givenDimensions, }: {
+        onStdoutOrStderr: (data: string) => void;
+        command: string;
+        args: string[];
+        cwd: string;
+        env?: NodeJS.ProcessEnv;
+        dimensions?: ITerminalDimensions;
+    }): TerminalApplication;
+    /** Write to the terminal's stdin. */
+    write(data: string): void;
+    killAndWait(): Promise<void>;
+}

package/dist/src/server/utilities/TerminalApplication.js

@@ -0,0 +1,54 @@
+import winston from "winston";
+import pty from "node-pty";
+// NOTE the size for the terminal was chosen so that it looks good in my
+// cypress test preview
+const defaultDimensions = { cols: 125, rows: 43 };
+// NOTE separating stdout and stderr is not supported by node-pty
+// https://github.com/microsoft/node-pty/issues/71
+export class TerminalApplication {
+    subProcess;
+    onStdoutOrStderr;
+    processId;
+    logger;
+    constructor(subProcess, onStdoutOrStderr) {
+        this.subProcess = subProcess;
+        this.onStdoutOrStderr = onStdoutOrStderr;
+        this.processId = subProcess.pid;
+        this.logger = winston.createLogger({
+            transports: [new winston.transports.Console()],
+            defaultMeta: { pid: this.processId },
+            format: winston.format.combine(winston.format.colorize(), winston.format.cli()),
+        });
+        this.logger.debug(`started`);
+        subProcess.onData(this.onStdoutOrStderr);
+        subProcess.onExit(({ exitCode, signal }) => {
+            this.logger.debug(`Child process ${this.processId} exited with code ${String(exitCode)} and signal ${String(signal)}`);
+        });
+    }
+    /** @constructor Start a new terminal application. */
+    static start({ onStdoutOrStderr, command, args, cwd, env, dimensions: givenDimensions, }) {
+        const dimensions = givenDimensions ?? defaultDimensions;
+        console.log(`Starting '${command} ${args.join(" ")}' in cwd '${cwd}'`);
+        const ptyProcess = pty.spawn(command, args, {
+            name: "xterm-color",
+            cwd,
+            env,
+            cols: dimensions.cols,
+            rows: dimensions.rows,
+        });
+        const processId = ptyProcess.pid;
+        if (!processId) {
+            throw new Error("Failed to spawn child process");
+        }
+        return new TerminalApplication(ptyProcess, onStdoutOrStderr);
+    }
+    /** Write to the terminal's stdin. */
+    write(data) {
+        this.subProcess.write(data);
+    }
+    async killAndWait() {
+        console.log(`💣 Killing process ${this.processId}`);
+        this.subProcess.kill();
+        console.log(`💥 Killed process ${this.processId}`);
+    }
+}

package/dist/src/server/utilities/tabId.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+export type TabId = z.infer<typeof tabIdSchema>;
+export declare const tabIdSchema: z.ZodObject<{
+    tabId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    tabId: string;
+}, {
+    tabId: string;
+}>;

package/dist/src/server/utilities/tabId.js

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export const tabIdSchema = z.object({ tabId: z.string() });