t3code-cli 0.9.1 → 0.11.0

package/src/cli/terminal/wait.test.ts

@@ -0,0 +1,146 @@
+import "vite-plus/test/config";
+
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import { assert, describe, expect, it } from "@effect/vitest";
+import { Command } from "effect/unstable/cli";
+import { fromPartial } from "@total-typescript/shoehorn";
+
+import { T3Application } from "../../application/service.ts";
+import { T3Config } from "../../config/service.ts";
+import { NodeEnvironmentLive } from "../../environment/layer.ts";
+import { T3Output } from "../output/service.ts";
+import { TerminalCliError } from "./error.ts";
+import { resolveMetadataWait, waitTerminalCommand } from "./wait.ts";
+
+describe("resolveMetadataWait", () => {
+  it("resolves closed immediately when terminal is missing from snapshot", () => {
+    const resolution = resolveMetadataWait(
+      { type: "snapshot", terminals: [] },
+      "closed",
+      "thread-1",
+      "term-1",
+    );
+    expect(resolution).toEqual({
+      kind: "result",
+      value: {
+        threadId: "thread-1",
+        terminalId: "term-1",
+        target: "closed",
+        status: "closed",
+        alreadySatisfied: true,
+        missingTreatedAsClosed: true,
+      },
+    });
+  });
+
+  it("uses the same exited error when terminal is missing from snapshot or removed", () => {
+    const missing = resolveMetadataWait(
+      { type: "snapshot", terminals: [] },
+      "exited",
+      "thread-1",
+      "term-1",
+    );
+    const removed = resolveMetadataWait(
+      { type: "remove", threadId: "thread-1", terminalId: "term-1" },
+      "exited",
+      "thread-1",
+      "term-1",
+    );
+
+    expect(missing?.kind).toBe("fail");
+    expect(removed?.kind).toBe("fail");
+    if (missing?.kind === "fail" && removed?.kind === "fail") {
+      expect(missing.error.message).toBe(removed.error.message);
+      expect(missing.error).toBeInstanceOf(TerminalCliError);
+    }
+  });
+});
+
+describe("waitTerminalCommand", () => {
+  const testLayer = Layer.mergeAll(
+    Layer.succeed(
+      T3Application,
+      fromPartial({
+        getTerminal: () => Effect.die("getTerminal should not be called"),
+        watchTerminalMetadata: () =>
+          Stream.make({
+            type: "snapshot" as const,
+            terminals: [],
+          }),
+      }),
+    ),
+    Layer.succeed(
+      T3Config,
+      fromPartial({
+        resolve: () =>
+          Effect.succeed({
+            url: "ws://localhost",
+            token: "token",
+            source: "config",
+            local: true,
+          }),
+      }),
+    ),
+    Layer.succeed(T3Output, {
+      writeStdout: () => Effect.void,
+      writeStderr: () => Effect.void,
+      printJson: () => Effect.void,
+      printNdjson: () => Effect.void,
+      printInfo: () => Effect.void,
+    }),
+    NodeServices.layer,
+    NodeEnvironmentLive,
+  );
+
+  it.layer(testLayer)("waitTerminalCommand", (t) => {
+    t.effect("does not require getTerminal before waiting for closed", () =>
+      Effect.gen(function* () {
+        const run = Command.runWith(waitTerminalCommand, { version: "0.0.0-test" });
+        const exit = yield* run([
+          "--thread",
+          "thread-1",
+          "term-1",
+          "--for",
+          "closed",
+          "--format",
+          "json",
+        ]).pipe(Effect.exit);
+        assert.isTrue(Exit.isSuccess(exit));
+      }),
+    );
+
+    t.effect("uses exited error without getTerminal when terminal is already missing", () =>
+      Effect.gen(function* () {
+        const run = Command.runWith(waitTerminalCommand, { version: "0.0.0-test" });
+        const exit = yield* run([
+          "--thread",
+          "thread-1",
+          "term-1",
+          "--for",
+          "exited",
+          "--format",
+          "json",
+        ]).pipe(Effect.exit);
+        assert.isTrue(Exit.isFailure(exit));
+        if (!Exit.isFailure(exit)) {
+          return;
+        }
+        const error = Cause.findErrorOption(exit.cause);
+        assert.isTrue(Option.isSome(error));
+        if (Option.isSome(error)) {
+          assert.instanceOf(error.value, TerminalCliError);
+          assert.equal(
+            error.value.message,
+            "terminal closed before an exited event was observed: term-1",
+          );
+        }
+      }),
+    );
+  });
+});

package/src/cli/terminal/wait.ts

@@ -0,0 +1,222 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import type { TerminalMetadataStreamEvent, TerminalSummary } from "#t3tools/contracts";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { T3Application } from "../../application/service.ts";
+import { Environment } from "../../environment/service.ts";
+import { formatFlag, threadFlag } from "../flags.ts";
+import { resolveOutputFormat } from "../output-format.ts";
+import { T3Output } from "../output/service.ts";
+import { TerminalCliError } from "./error.ts";
+import { requireCommandThreadId } from "./scope.ts";
+
+const terminalWaitTargetChoices = ["exited", "closed", "ended"] as const;
+type TerminalWaitTarget = (typeof terminalWaitTargetChoices)[number];
+
+type WaitResult =
+  | {
+      readonly threadId: string;
+      readonly terminalId: string;
+      readonly target: TerminalWaitTarget;
+      readonly status: string;
+      readonly exitCode?: number | null;
+      readonly exitSignal?: number | null;
+      readonly updatedAt?: string;
+      readonly sequence?: number;
+      readonly alreadySatisfied: boolean;
+      readonly missingTreatedAsClosed?: true;
+    }
+  | {
+      readonly threadId: string;
+      readonly terminalId: string;
+      readonly target: TerminalWaitTarget;
+      readonly status: "exited" | "closed";
+      readonly exitCode?: number | null;
+      readonly exitSignal?: number | null;
+      readonly sequence?: number;
+      readonly alreadySatisfied: false;
+    };
+
+type WaitResolution =
+  | { readonly kind: "result"; readonly value: WaitResult }
+  | { readonly kind: "fail"; readonly error: TerminalCliError };
+
+export const waitTerminalCommand = Command.make(
+  "wait",
+  {
+    thread: threadFlag,
+    terminalId: Argument.string("terminal-id"),
+    target: Flag.choice("for", terminalWaitTargetChoices).pipe(Flag.withDefault("exited")),
+    format: formatFlag,
+  },
+  ({ thread, terminalId, target, format }) =>
+    Effect.gen(function* () {
+      const application = yield* T3Application;
+      const environment = yield* Environment;
+      const output = yield* T3Output;
+      const threadId = yield* requireCommandThreadId({
+        thread,
+        env: environment.env,
+      });
+      const resolvedFormat = resolveOutputFormat(format, environment, "json");
+
+      const resolution = yield* application.watchTerminalMetadata().pipe(
+        Stream.map((event) => resolveMetadataWait(event, target, threadId, terminalId)),
+        Stream.filter((value): value is WaitResolution => value !== null),
+        Stream.runHead,
+      );
+
+      if (Option.isNone(resolution)) {
+        yield* Effect.fail(
+          new TerminalCliError({
+            message: "terminal wait stream ended unexpectedly",
+            threadId,
+            terminalId,
+          }),
+        );
+      } else if (resolution.value.kind === "fail") {
+        yield* Effect.fail(resolution.value.error);
+      } else {
+        const result = resolution.value.value;
+        if (resolvedFormat === "json") {
+          yield* output.printJson(result);
+        } else {
+          yield* output.printInfo(formatWaitHuman(result));
+        }
+      }
+    }),
+).pipe(Command.withDescription("wait for terminal lifecycle events"));
+
+function terminalClosedBeforeExitError(threadId: string, terminalId: string) {
+  return new TerminalCliError({
+    message: `terminal closed before an exited event was observed: ${terminalId}`,
+    threadId,
+    terminalId,
+  });
+}
+
+export function resolveMetadataWait(
+  event: TerminalMetadataStreamEvent,
+  target: TerminalWaitTarget,
+  threadId: string,
+  terminalId: string,
+): WaitResolution | null {
+  if (event.type === "snapshot") {
+    const terminal = event.terminals.find(
+      (candidate) => candidate.threadId === threadId && candidate.terminalId === terminalId,
+    );
+    if (terminal !== undefined) {
+      if (targetSatisfiedBySummary(target, terminal)) {
+        return {
+          kind: "result",
+          value: {
+            threadId: terminal.threadId,
+            terminalId: terminal.terminalId,
+            target,
+            status: terminal.status,
+            exitCode: terminal.exitCode,
+            exitSignal: terminal.exitSignal,
+            updatedAt: terminal.updatedAt,
+            alreadySatisfied: true,
+          },
+        };
+      }
+      return null;
+    }
+    if (target === "closed" || target === "ended") {
+      return {
+        kind: "result",
+        value: {
+          threadId,
+          terminalId,
+          target,
+          status: "closed",
+          alreadySatisfied: true,
+          missingTreatedAsClosed: true,
+        },
+      };
+    }
+    return {
+      kind: "fail",
+      error: terminalClosedBeforeExitError(threadId, terminalId),
+    };
+  }
+
+  if (event.type === "upsert") {
+    if (event.terminal.threadId !== threadId || event.terminal.terminalId !== terminalId) {
+      return null;
+    }
+    if ((target === "exited" || target === "ended") && event.terminal.status === "exited") {
+      return {
+        kind: "result",
+        value: {
+          threadId,
+          terminalId,
+          target,
+          status: "exited",
+          exitCode: event.terminal.exitCode,
+          exitSignal: event.terminal.exitSignal,
+          alreadySatisfied: false,
+        },
+      };
+    }
+    return null;
+  }
+
+  if (event.threadId !== threadId || event.terminalId !== terminalId) {
+    return null;
+  }
+
+  if (target === "exited") {
+    return {
+      kind: "fail",
+      error: terminalClosedBeforeExitError(threadId, terminalId),
+    };
+  }
+
+  if (target === "closed" || target === "ended") {
+    return {
+      kind: "result",
+      value: {
+        threadId,
+        terminalId,
+        target,
+        status: "closed",
+        alreadySatisfied: false,
+      },
+    };
+  }
+
+  return null;
+}
+
+function targetSatisfiedBySummary(target: TerminalWaitTarget, terminal: TerminalSummary) {
+  if (target === "exited") {
+    return terminal.status === "exited";
+  }
+  if (target === "closed") {
+    return false;
+  }
+  return terminal.status === "exited";
+}
+
+function formatWaitHuman(input: {
+  readonly threadId: string;
+  readonly terminalId: string;
+  readonly status: string;
+  readonly alreadySatisfied: boolean;
+  readonly exitCode?: number | null;
+  readonly exitSignal?: number | null;
+}) {
+  const details = [
+    typeof input.exitCode === "number" ? `code ${input.exitCode}` : null,
+    typeof input.exitSignal === "number" ? `signal ${input.exitSignal}` : null,
+  ]
+    .filter((value): value is string => value !== null)
+    .join(", ");
+  return details.length > 0
+    ? `terminal ${input.status}: ${input.terminalId} (${input.threadId}) ${details}`
+    : `terminal ${input.status}: ${input.terminalId} (${input.threadId})`;
+}

package/src/cli/terminal/write.ts

@@ -0,0 +1,132 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { formatTerminalWrittenHuman } from "../terminal-format.ts";
+import { T3Application } from "../../application/service.ts";
+import { Environment } from "../../environment/service.ts";
+import { InvalidFlagCombinationError } from "../error.ts";
+import { T3Input } from "../input/service.ts";
+import { formatFlag, threadFlag } from "../flags.ts";
+import { resolveOutputFormat } from "../output-format.ts";
+import { T3Output } from "../output/service.ts";
+import { decodeBase64Payload, decodeHexPayload } from "./encoding.ts";
+import { TerminalCliError } from "./error.ts";
+import { requireCommandThreadId } from "./scope.ts";
+
+export const writeTerminalCommand = Command.make(
+  "write",
+  {
+    thread: threadFlag,
+    terminalId: Argument.string("terminal-id"),
+    data: Argument.string("data").pipe(Argument.optional),
+    stdin: Flag.boolean("stdin"),
+    hex: Flag.string("hex").pipe(Flag.optional),
+    base64: Flag.string("base64").pipe(Flag.optional),
+    quiet: Flag.boolean("quiet"),
+    format: formatFlag,
+  },
+  ({ thread, terminalId, data, stdin, hex, base64, quiet, format }) =>
+    Effect.gen(function* () {
+      const output = yield* T3Output;
+      const inputService = yield* T3Input;
+      const application = yield* T3Application;
+      const environment = yield* Environment;
+      const threadId = yield* requireCommandThreadId({
+        thread,
+        env: environment.env,
+      });
+      const argumentData = Option.getOrUndefined(data);
+      const hexData = Option.getOrUndefined(hex);
+      const base64Data = Option.getOrUndefined(base64);
+      const inputCount = [
+        stdin,
+        argumentData !== undefined,
+        hexData !== undefined,
+        base64Data !== undefined,
+      ].filter(Boolean).length;
+
+      if (inputCount !== 1) {
+        yield* Effect.fail(
+          new InvalidFlagCombinationError({
+            message: "provide exactly one of <data>, --stdin, --hex <data>, or --base64 <data>",
+          }),
+        );
+      }
+
+      const payload =
+        hexData !== undefined
+          ? yield* decodeHexPayloadOrFail(hexData, threadId, terminalId)
+          : base64Data !== undefined
+            ? yield* decodeBase64PayloadOrFail(base64Data, threadId, terminalId)
+            : stdin
+              ? yield* inputService.readStdinBinary()
+              : argumentData!;
+      if (payload.length === 0) {
+        yield* Effect.fail(
+          new TerminalCliError({
+            message: "terminal write payload is empty",
+            threadId,
+            terminalId,
+          }),
+        );
+      }
+
+      yield* application.writeTerminal({
+        terminal: {
+          threadId,
+          terminalId,
+        },
+        data: payload,
+      });
+      if (quiet) {
+        return;
+      }
+      const bytes = Buffer.byteLength(payload, "latin1");
+      const resolvedFormat = resolveOutputFormat(format, environment, "json");
+      if (resolvedFormat === "json") {
+        yield* output.printJson({
+          threadId,
+          terminalId,
+          bytes,
+          encoding: hexData !== undefined ? "hex" : base64Data !== undefined ? "base64" : "latin1",
+        });
+        return;
+      }
+      yield* output.printInfo(
+        formatTerminalWrittenHuman({
+          terminalId,
+          threadId,
+          bytes,
+        }),
+      );
+    }),
+).pipe(Command.withDescription("write raw data to a terminal"));
+
+function decodeHexPayloadOrFail(value: string, threadId: string, terminalId: string) {
+  const decoded = decodeHexPayload(value);
+  if (decoded === undefined) {
+    return Effect.fail(
+      new TerminalCliError({
+        message: "invalid hex payload",
+        threadId,
+        terminalId,
+      }),
+    );
+  }
+  return Effect.succeed(decoded);
+}
+
+function decodeBase64PayloadOrFail(value: string, threadId: string, terminalId: string) {
+  const decoded = decodeBase64Payload(value);
+  if (decoded === undefined) {
+    return Effect.fail(
+      new TerminalCliError({
+        message: "invalid base64 payload",
+        threadId,
+        terminalId,
+      }),
+    );
+  }
+  return Effect.succeed(decoded);
+}

package/src/cli/terminal-format.ts

@@ -0,0 +1,167 @@
+import type { TerminalSessionSnapshot, TerminalSummary } from "#t3tools/contracts";
+
+type TerminalRow = {
+  readonly id: string;
+  readonly status: string;
+  readonly label: string;
+  readonly cwd: string;
+  readonly updated: string;
+  readonly process: string;
+};
+
+export function formatTerminalListHuman(terminals: ReadonlyArray<TerminalSummary>) {
+  if (terminals.length === 0) {
+    return "no terminals\n";
+  }
+  return `${formatTerminalTable(terminals.map(toSummaryRow))}\n`;
+}
+
+export function formatTerminalCreatedHuman(snapshot: TerminalSessionSnapshot) {
+  return `terminal created\n${formatTerminalTable([toSnapshotRow(snapshot)])}`;
+}
+
+export function formatTerminalWrittenHuman(input: {
+  readonly terminalId: string;
+  readonly threadId: string;
+  readonly bytes: number;
+}) {
+  return `wrote ${input.bytes} bytes to ${input.terminalId} (${input.threadId})`;
+}
+
+export function formatTerminalDestroyedHuman(input: {
+  readonly terminalId: string;
+  readonly threadId: string;
+}) {
+  return `destroyed ${input.terminalId} (${input.threadId})`;
+}
+
+function formatTerminalTable(rows: ReadonlyArray<TerminalRow>) {
+  const headers = {
+    id: "id",
+    status: "status",
+    label: "label",
+    cwd: "cwd",
+    updated: "updated",
+    process: "process",
+  };
+
+  const widths = {
+    id: columnWidth(
+      headers.id,
+      rows.map((row) => row.id),
+      44,
+    ),
+    status: columnWidth(
+      headers.status,
+      rows.map((row) => row.status),
+      8,
+    ),
+    label: columnWidth(
+      headers.label,
+      rows.map((row) => row.label),
+      24,
+    ),
+    cwd: columnWidth(
+      headers.cwd,
+      rows.map((row) => row.cwd),
+      40,
+    ),
+    updated: columnWidth(
+      headers.updated,
+      rows.map((row) => row.updated),
+      24,
+    ),
+    process: columnWidth(
+      headers.process,
+      rows.map((row) => row.process),
+      20,
+    ),
+  };
+
+  const header = [
+    pad(headers.id, widths.id),
+    pad(headers.status, widths.status),
+    pad(headers.label, widths.label),
+    pad(headers.cwd, widths.cwd),
+    pad(headers.updated, widths.updated),
+    pad(headers.process, widths.process),
+  ].join("  ");
+
+  const divider = [
+    "-".repeat(widths.id),
+    "-".repeat(widths.status),
+    "-".repeat(widths.label),
+    "-".repeat(widths.cwd),
+    "-".repeat(widths.updated),
+    "-".repeat(widths.process),
+  ].join("  ");
+
+  const body = rows
+    .map((row) =>
+      [
+        pad(row.id, widths.id),
+        pad(row.status, widths.status),
+        pad(row.label, widths.label),
+        pad(row.cwd, widths.cwd),
+        pad(row.updated, widths.updated),
+        pad(row.process, widths.process),
+      ].join("  "),
+    )
+    .join("\n");
+
+  return `${header}\n${divider}\n${body}`;
+}
+
+function toSummaryRow(terminal: TerminalSummary): TerminalRow {
+  return {
+    id: terminal.terminalId,
+    status: terminal.status,
+    label: terminal.label,
+    cwd: terminal.cwd,
+    updated: terminal.updatedAt,
+    process: formatProcessInfo(terminal),
+  };
+}
+
+function toSnapshotRow(snapshot: TerminalSessionSnapshot): TerminalRow {
+  return {
+    id: snapshot.terminalId,
+    status: snapshot.status,
+    label: snapshot.label,
+    cwd: snapshot.cwd,
+    updated: snapshot.updatedAt,
+    process: formatProcessInfo(snapshot),
+  };
+}
+
+function formatProcessInfo(input: {
+  readonly pid: number | null;
+  readonly exitCode: number | null;
+  readonly exitSignal: number | null;
+}) {
+  const parts = [
+    typeof input.pid === "number" ? `pid ${input.pid}` : null,
+    typeof input.exitCode === "number" ? `exit ${input.exitCode}` : null,
+    typeof input.exitSignal === "number" ? `sig ${input.exitSignal}` : null,
+  ].filter((part): part is string => part !== null);
+  return parts.length > 0 ? parts.join(", ") : "-";
+}
+
+function columnWidth(header: string, values: ReadonlyArray<string>, maxWidth: number) {
+  const widest = values.reduce((width, value) => Math.max(width, value.length), header.length);
+  return Math.min(widest, maxWidth);
+}
+
+function pad(value: string, width: number) {
+  return truncate(value, width).padEnd(width, " ");
+}
+
+function truncate(value: string, width: number) {
+  if (value.length <= width) {
+    return value;
+  }
+  if (width <= 3) {
+    return value.slice(0, width);
+  }
+  return `${value.slice(0, width - 3)}...`;
+}

package/src/cli/terminal.ts

@@ -0,0 +1,26 @@
+import { Command } from "effect/unstable/cli";
+
+import { attachTerminalCommand } from "./terminal/attach.ts";
+import { createTerminalCommand } from "./terminal/create.ts";
+import { destroyTerminalCommand } from "./terminal/destroy.ts";
+import { listTerminalCommand } from "./terminal/list.ts";
+import { readTerminalCommand } from "./terminal/read.ts";
+import { streamTerminalCommand } from "./terminal/stream.ts";
+import { waitTerminalCommand } from "./terminal/wait.ts";
+import { writeTerminalCommand } from "./terminal/write.ts";
+
+export function createTerminalCommandGroup() {
+  return Command.make("terminal").pipe(
+    Command.withDescription("terminal commands"),
+    Command.withSubcommands([
+      listTerminalCommand,
+      createTerminalCommand,
+      attachTerminalCommand,
+      readTerminalCommand,
+      streamTerminalCommand,
+      waitTerminalCommand,
+      writeTerminalCommand,
+      destroyTerminalCommand,
+    ]),
+  );
+}