t3code-cli 0.10.0 → 0.11.0

package/src/cli/terminal/io-service.ts

@@ -0,0 +1,25 @@
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import type * as Stream from "effect/Stream";
+
+import type { TerminalIoError } from "./error.ts";
+
+export type TerminalWindowSize = {
+  readonly cols: number;
+  readonly rows: number;
+};
+
+export type RawTerminalIoSession = {
+  readonly input: Stream.Stream<Uint8Array>;
+  readonly resize: Stream.Stream<TerminalWindowSize>;
+};
+
+export class TerminalIo extends Context.Service<
+  TerminalIo,
+  {
+    readonly getWindowSize: Effect.Effect<TerminalWindowSize, TerminalIoError>;
+    readonly writeOutput: (text: string) => Effect.Effect<void>;
+    readonly openRawSession: Effect.Effect<RawTerminalIoSession, TerminalIoError, Scope.Scope>;
+  }
+>()("t3cli/T3TerminalIo") {}

package/src/cli/terminal/list.ts

@@ -0,0 +1,35 @@
+import * as Effect from "effect/Effect";
+import { Command } from "effect/unstable/cli";
+
+import { formatTerminalListHuman } from "../terminal-format.ts";
+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 { requireCommandThreadId } from "./scope.ts";
+
+export const listTerminalCommand = Command.make(
+  "list",
+  {
+    thread: threadFlag,
+    format: formatFlag,
+  },
+  ({ thread, 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 terminals = yield* application.listTerminals(threadId);
+      if (resolvedFormat === "json") {
+        yield* output.printJson(terminals);
+      } else {
+        yield* output.writeStdout(formatTerminalListHuman(terminals));
+      }
+    }),
+).pipe(Command.withDescription("list terminals for a thread"));

package/src/cli/terminal/read.ts

@@ -0,0 +1,102 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { T3Application } from "../../application/service.ts";
+import { Environment } from "../../environment/service.ts";
+import { InvalidFlagCombinationError, InvalidLimitError } from "../error.ts";
+import { threadFlag } from "../flags.ts";
+import { T3Output } from "../output/service.ts";
+import { TerminalCliError } from "./error.ts";
+import { requireCommandThreadId } from "./scope.ts";
+import { filterAttachStreamEvent, toTerminalAttachTarget } from "./shared.ts";
+
+const jsonNdjsonFormatChoices = ["json", "ndjson"] as const;
+
+export const readTerminalCommand = Command.make(
+  "read",
+  {
+    thread: threadFlag,
+    terminalId: Argument.string("terminal-id"),
+    history: Flag.boolean("history"),
+    follow: Flag.boolean("follow"),
+    fromSequence: Flag.integer("from-sequence").pipe(Flag.optional),
+    format: Flag.choice("format", jsonNdjsonFormatChoices).pipe(Flag.withDefault("json")),
+  },
+  ({ thread, terminalId, history, follow, fromSequence, format }) =>
+    Effect.gen(function* () {
+      const output = yield* T3Output;
+      const application = yield* T3Application;
+      const environment = yield* Environment;
+      const threadId = yield* requireCommandThreadId({
+        thread,
+        env: environment.env,
+      });
+      const fromSequenceValue = Option.getOrUndefined(fromSequence);
+
+      if (fromSequenceValue !== undefined && fromSequenceValue < 0) {
+        yield* Effect.fail(
+          new InvalidLimitError({
+            message: "from-sequence must be a non-negative integer",
+            value: String(fromSequenceValue),
+          }),
+        );
+      }
+      if (fromSequenceValue !== undefined && !follow) {
+        yield* Effect.fail(
+          new InvalidFlagCombinationError({
+            message: "--from-sequence requires --follow",
+          }),
+        );
+      }
+      if (follow && format !== "ndjson") {
+        yield* Effect.fail(
+          new InvalidFlagCombinationError({
+            message: "--follow requires --format ndjson",
+          }),
+        );
+      }
+
+      const terminal = yield* application.getTerminal({
+        threadId,
+        terminalId,
+      });
+      const stream = application
+        .attachTerminal({
+          terminal: toTerminalAttachTarget(terminal),
+        })
+        .pipe(
+          Stream.map((event) =>
+            filterAttachStreamEvent(event, {
+              includeHistory: history,
+              ...(fromSequenceValue !== undefined ? { fromSequence: fromSequenceValue } : {}),
+            }),
+          ),
+          Stream.filter((event): event is NonNullable<typeof event> => event !== null),
+        );
+
+      if (follow) {
+        yield* Stream.runForEach(stream, (event) => output.printNdjson(event));
+        return;
+      }
+
+      const item = yield* Stream.runHead(stream);
+      const event = Option.getOrUndefined(item);
+      if (event === undefined || event.type !== "snapshot") {
+        yield* Effect.fail(
+          new TerminalCliError({
+            message: "server did not return terminal snapshot",
+            threadId,
+            terminalId,
+          }),
+        );
+      } else {
+        if (format === "ndjson") {
+          yield* output.printNdjson(event);
+        } else {
+          yield* output.printJson(event.snapshot);
+        }
+      }
+    }),
+).pipe(Command.withDescription("read terminal state and optional history"));

package/src/cli/terminal/scope.ts

@@ -0,0 +1,30 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+
+import { resolveThreadId } from "../../scope/index.ts";
+import { MissingThreadError } from "../error.ts";
+
+export function resolveCommandThreadId(input: {
+  readonly thread: Option.Option<string>;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}): string | undefined {
+  return resolveThreadId({
+    value: Option.getOrUndefined(input.thread),
+    env: input.env,
+  });
+}
+
+export const requireCommandThreadId = Effect.fn("requireCommandThreadId")(function* (input: {
+  readonly thread: Option.Option<string>;
+  readonly env: Readonly<Record<string, string | undefined>>;
+}) {
+  const threadId = resolveCommandThreadId(input);
+  if (threadId === undefined) {
+    return yield* Effect.fail(
+      new MissingThreadError({
+        message: "thread id is required: pass --thread or set T3CODE_THREAD_ID",
+      }),
+    );
+  }
+  return threadId;
+});

package/src/cli/terminal/shared.ts

@@ -0,0 +1,250 @@
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Match from "effect/Match";
+import * as Stream from "effect/Stream";
+import type {
+  TerminalAttachStreamEvent,
+  TerminalSessionSnapshot,
+  TerminalSummary,
+} from "#t3tools/contracts";
+
+import type { TerminalAttachTarget, TerminalRef } from "../../application/service.ts";
+import { T3Application } from "../../application/service.ts";
+import type { ApplicationError } from "../../application/error.ts";
+import { bytesToLatin1String } from "./encoding.ts";
+import { TerminalCliError, type TerminalIoError } from "./error.ts";
+import { TerminalIo } from "./io-service.ts";
+
+const DETACH_BYTE = 0x1d;
+const ANSI_CLEAR_SCREEN = "\u001bc";
+
+type AttachSessionResult =
+  | {
+      readonly _tag: "Failure";
+      readonly error: ApplicationError | TerminalCliError;
+      readonly message?: string;
+    }
+  | {
+      readonly _tag: "Success";
+      readonly message?: string;
+    };
+
+export function runAttachedTerminalSession(input: { readonly terminal: TerminalAttachTarget }) {
+  return Effect.scoped(
+    Effect.gen(function* () {
+      const application = yield* T3Application;
+      const io = yield* TerminalIo;
+      const { cols, rows } = yield* io.getWindowSize.pipe(
+        Effect.mapError((error) => mapTerminalIoError(error, input.terminal)),
+      );
+      const session = yield* io.openRawSession.pipe(
+        Effect.mapError((error) => mapTerminalIoError(error, input.terminal)),
+      );
+      const completion = yield* Deferred.make<AttachSessionResult>();
+      const stream = application.attachTerminal({
+        terminal: input.terminal,
+        cols,
+        rows,
+      });
+
+      yield* Stream.runForEach(stream, applyAttachEvent).pipe(
+        Effect.match({
+          onFailure: (error) => completeAttachSession(completion, { _tag: "Failure", error }),
+          onSuccess: () => completeAttachSession(completion, { _tag: "Success" }),
+        }),
+        Effect.forkScoped,
+      );
+
+      yield* Stream.runForEach(session.resize, ({ cols: nextCols, rows: nextRows }) =>
+        application.resizeTerminal({
+          terminal: input.terminal,
+          cols: nextCols,
+          rows: nextRows,
+        }),
+      ).pipe(
+        Effect.match({
+          onFailure: (error) => completeAttachSession(completion, { _tag: "Failure", error }),
+          onSuccess: () => completeAttachSession(completion, { _tag: "Success" }),
+        }),
+        Effect.forkScoped,
+      );
+
+      yield* Stream.runForEach(session.input, (chunk) =>
+        handleSessionInput({
+          completion,
+          terminal: input.terminal,
+          chunk,
+        }),
+      ).pipe(
+        Effect.match({
+          onFailure: (error) => completeAttachSession(completion, { _tag: "Failure", error }),
+          onSuccess: () => completeAttachSession(completion, { _tag: "Success" }),
+        }),
+        Effect.forkScoped,
+      );
+
+      const result = yield* Deferred.await(completion);
+      if (result.message !== undefined) {
+        yield* writeSystemMessage(result.message);
+      }
+      return yield* Match.value(result).pipe(
+        Match.tag("Failure", ({ error }) => Effect.fail(error)),
+        Match.orElse(() => Effect.void),
+      );
+    }),
+  );
+}
+
+function completeAttachSession(
+  completion: Deferred.Deferred<AttachSessionResult>,
+  result: AttachSessionResult,
+) {
+  return Deferred.succeed(completion, result).pipe(Effect.ignore);
+}
+
+function handleSessionInput(input: {
+  readonly completion: Deferred.Deferred<AttachSessionResult>;
+  readonly terminal: TerminalRef;
+  readonly chunk: Uint8Array;
+}) {
+  const detachOffset = input.chunk.indexOf(DETACH_BYTE);
+  const payload = detachOffset === -1 ? input.chunk : input.chunk.slice(0, detachOffset);
+
+  if (payload.length === 0 && detachOffset === -1) {
+    return Effect.void;
+  }
+
+  return Effect.gen(function* () {
+    const application = yield* T3Application;
+    if (payload.length > 0) {
+      yield* application.writeTerminal({
+        terminal: input.terminal,
+        data: bytesToLatin1String(payload),
+      });
+    }
+
+    if (detachOffset !== -1) {
+      yield* completeAttachSession(input.completion, {
+        _tag: "Success",
+        message: "detached",
+      });
+    }
+  });
+}
+
+function mapTerminalIoError(
+  error: TerminalIoError,
+  terminal: TerminalAttachTarget,
+): TerminalCliError {
+  return new TerminalCliError({
+    message: error.message,
+    threadId: terminal.threadId,
+    terminalId: terminal.terminalId,
+  });
+}
+
+function applyAttachEvent(event: TerminalAttachStreamEvent) {
+  return Effect.gen(function* () {
+    const io = yield* TerminalIo;
+    yield* Match.value(event).pipe(
+      Match.when({ type: "activity" }, () => Effect.void),
+      Match.when({ type: "snapshot" }, ({ snapshot }) => writeSnapshot(snapshot.history)),
+      Match.when({ type: "restarted" }, ({ snapshot }) => writeSnapshot(snapshot.history)),
+      Match.when({ type: "output" }, ({ data }) => io.writeOutput(data)),
+      Match.when({ type: "cleared" }, () => io.writeOutput(ANSI_CLEAR_SCREEN)),
+      Match.when({ type: "error" }, ({ message }) => writeSystemMessage(message)),
+      Match.when({ type: "closed" }, () => writeSystemMessage("Terminal closed")),
+      Match.orElse((next) => {
+        const details = [
+          typeof next.exitCode === "number" ? `code ${next.exitCode}` : null,
+          typeof next.exitSignal === "number" ? `signal ${next.exitSignal}` : null,
+        ]
+          .filter((value): value is string => value !== null)
+          .join(", ");
+        return writeSystemMessage(
+          details.length > 0 ? `Process exited (${details})` : "Process exited",
+        );
+      }),
+    );
+  });
+}
+
+function writeSnapshot(history: string) {
+  return Effect.gen(function* () {
+    const io = yield* TerminalIo;
+    yield* io.writeOutput(ANSI_CLEAR_SCREEN);
+    if (history.length > 0) {
+      yield* io.writeOutput(history);
+    }
+  });
+}
+
+function writeSystemMessage(message: string) {
+  return Effect.gen(function* () {
+    const io = yield* TerminalIo;
+    yield* io.writeOutput(`\r\n[terminal] ${message}\r\n`);
+  });
+}
+
+export function toTerminalAttachTarget(terminal: TerminalSummary): TerminalAttachTarget {
+  return {
+    threadId: terminal.threadId,
+    terminalId: terminal.terminalId,
+    cwd: terminal.cwd,
+    worktreePath: terminal.worktreePath,
+  };
+}
+
+export function snapshotToTerminalAttachTarget(
+  snapshot: TerminalSessionSnapshot,
+): TerminalAttachTarget {
+  return {
+    threadId: snapshot.threadId,
+    terminalId: snapshot.terminalId,
+    cwd: snapshot.cwd,
+    worktreePath: snapshot.worktreePath,
+  };
+}
+
+export function toTerminalRef(terminal: TerminalSummary): TerminalRef {
+  return {
+    threadId: terminal.threadId,
+    terminalId: terminal.terminalId,
+  };
+}
+
+export function filterAttachStreamEvent(
+  event: TerminalAttachStreamEvent,
+  options: {
+    readonly includeHistory: boolean;
+    readonly fromSequence?: number;
+  },
+): TerminalAttachStreamEvent | null {
+  if (event.type === "snapshot" || event.type === "restarted") {
+    if (
+      options.fromSequence !== undefined &&
+      event.type === "restarted" &&
+      typeof event.snapshot.sequence === "number" &&
+      event.snapshot.sequence < options.fromSequence
+    ) {
+      return null;
+    }
+    return {
+      ...event,
+      snapshot: {
+        ...event.snapshot,
+        history: options.includeHistory ? event.snapshot.history : "",
+      },
+    };
+  }
+
+  if (
+    options.fromSequence !== undefined &&
+    typeof event.sequence === "number" &&
+    event.sequence < options.fromSequence
+  ) {
+    return null;
+  }
+
+  return event;
+}

package/src/cli/terminal/stream.ts

@@ -0,0 +1,64 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Stream from "effect/Stream";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { T3Application } from "../../application/service.ts";
+import { Environment } from "../../environment/service.ts";
+import { InvalidLimitError } from "../error.ts";
+import { threadFlag } from "../flags.ts";
+import { T3Output } from "../output/service.ts";
+import { requireCommandThreadId } from "./scope.ts";
+import { filterAttachStreamEvent, toTerminalAttachTarget } from "./shared.ts";
+
+const ndjsonOnlyFormatChoices = ["ndjson"] as const;
+
+export const streamTerminalCommand = Command.make(
+  "stream",
+  {
+    thread: threadFlag,
+    terminalId: Argument.string("terminal-id"),
+    fromSequence: Flag.integer("from-sequence").pipe(Flag.optional),
+    format: Flag.choice("format", ndjsonOnlyFormatChoices).pipe(Flag.withDefault("ndjson")),
+  },
+  ({ thread, terminalId, fromSequence }) =>
+    Effect.gen(function* () {
+      const output = yield* T3Output;
+      const application = yield* T3Application;
+      const environment = yield* Environment;
+      const threadId = yield* requireCommandThreadId({
+        thread,
+        env: environment.env,
+      });
+      const fromSequenceValue = Option.getOrUndefined(fromSequence);
+
+      if (fromSequenceValue !== undefined && fromSequenceValue < 0) {
+        yield* Effect.fail(
+          new InvalidLimitError({
+            message: "from-sequence must be a non-negative integer",
+            value: String(fromSequenceValue),
+          }),
+        );
+      }
+
+      const terminal = yield* application.getTerminal({
+        threadId,
+        terminalId,
+      });
+      const stream = application
+        .attachTerminal({
+          terminal: toTerminalAttachTarget(terminal),
+        })
+        .pipe(
+          Stream.map((event) =>
+            filterAttachStreamEvent(event, {
+              includeHistory: true,
+              ...(fromSequenceValue !== undefined ? { fromSequence: fromSequenceValue } : {}),
+            }),
+          ),
+          Stream.filter((event): event is NonNullable<typeof event> => event !== null),
+        );
+
+      yield* Stream.runForEach(stream, (event) => output.printNdjson(event));
+    }),
+).pipe(Command.withDescription("stream terminal attach events as ndjson"));

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",
+          );
+        }
+      }),
+    );
+  });
+});