t3code-cli 0.10.0 → 0.11.0

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

package/src/cli/thread-format.test.ts

@@ -0,0 +1,32 @@
+import "vite-plus/test/config";
+
+import { assert, describe, it } from "@effect/vitest";
+import { fromPartial } from "@total-typescript/shoehorn";
+import type { OrchestrationThreadShell } from "#t3tools/contracts";
+
+import { formatThreadsHuman } from "./thread-format.ts";
+
+describe("formatThreadsHuman", () => {
+  it("appends (archived) for archived threads", () => {
+    const threads: OrchestrationThreadShell[] = [
+      fromPartial({
+        id: "active-1",
+        title: "Active thread",
+        archivedAt: null,
+        updatedAt: "2026-01-01T00:00:00.000Z",
+        session: null,
+      }),
+      fromPartial({
+        id: "archived-1",
+        title: "Archived thread",
+        archivedAt: "2026-01-02T00:00:00.000Z",
+        updatedAt: "2026-01-02T00:00:00.000Z",
+        session: null,
+      }),
+    ];
+
+    const output = formatThreadsHuman(threads);
+    assert.include(output, "- Active thread\n");
+    assert.include(output, "- Archived thread (archived)\n");
+  });
+});

package/src/cli/thread-format.ts

@@ -53,11 +53,18 @@ export function formatThreadsHuman(threads: ReadonlyArray<OrchestrationThreadShe
   return threads
     .map(
       (thread) =>
-        `- ${thread.title}\n  id: ${thread.id}\n  status: ${threadStatus(thread)}\n  updated: ${thread.updatedAt}\n`,
+        `- ${thread.title}${thread.archivedAt !== null ? " (archived)" : ""}\n  id: ${thread.id}\n  status: ${threadStatus(thread)}\n  updated: ${thread.updatedAt}\n`,
     )
     .join("");
 }
 
+export function formatThreadDeletedHuman(input: {
+  readonly threadId: string;
+  readonly dispatch: { readonly sequence: number };
+}) {
+  return `thread deleted: ${input.threadId}\nsequence: ${input.dispatch.sequence}`;
+}
+
 export function formatThreadStartedHuman(input: {
   readonly thread: OrchestrationThread;
   readonly sequence: number;

package/src/cli/thread.ts

@@ -3,7 +3,11 @@ import { Command } from "effect/unstable/cli";
 import { approveThreadCommand } from "./threads/approve.ts";
 import { archiveThreadCommand } from "./threads/archive.ts";
 import { callbackThreadCommand } from "./threads/callback.ts";
+import { deleteThreadCommand } from "./threads/delete.ts";
+import { interruptThreadCommand } from "./threads/interrupt.ts";
 import { respondThreadCommand } from "./threads/respond.ts";
+import { unarchiveThreadCommand } from "./threads/unarchive.ts";
+import { updateThreadCommand } from "./threads/update.ts";
 
 export function createThreadCommand() {
   return Command.make("thread").pipe(
@@ -12,6 +16,10 @@ export function createThreadCommand() {
       approveThreadCommand,
       respondThreadCommand,
       archiveThreadCommand,
+      interruptThreadCommand,
+      unarchiveThreadCommand,
+      updateThreadCommand,
+      deleteThreadCommand,
       callbackThreadCommand,
     ]),
   );

package/src/cli/threads/archive.ts

@@ -1,9 +1,10 @@
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { Command, Flag } from "effect/unstable/cli";
+import { Command } from "effect/unstable/cli";
 
-import { formatFlag, threadFlag } from "../flags.ts";
-import { MissingThreadError, SelfArchiveError } from "../error.ts";
+import { formatFlag, selfActionForceFlag, threadFlag } from "../flags.ts";
+import { MissingThreadError } from "../error.ts";
+import { requireSelfActionConfirmation } from "../self-action.ts";
 import { resolveThreadId } from "../../scope/index.ts";
 import { T3Application } from "../../application/service.ts";
 import { Environment } from "../../environment/service.ts";
@@ -14,7 +15,7 @@ export const archiveThreadCommand = Command.make(
   "archive",
   {
     thread: threadFlag,
-    force: Flag.boolean("force").pipe(Flag.withAlias("f")),
+    force: selfActionForceFlag,
     format: formatFlag,
   },
   ({ thread, force, format }) =>
@@ -33,20 +34,12 @@ export const archiveThreadCommand = Command.make(
           }),
         );
       }
-      const envThreadId = environment.env.T3CODE_THREAD_ID;
-      if (
-        envThreadId !== undefined &&
-        envThreadId.length > 0 &&
-        threadId === envThreadId &&
-        !force
-      ) {
-        return yield* Effect.fail(
-          new SelfArchiveError({
-            threadId,
-            message: `cannot archive thread ${threadId}: matches T3CODE_THREAD_ID (are you trying to archive yourself?). Use --force to override.`,
-          }),
-        );
-      }
+      yield* requireSelfActionConfirmation({
+        threadId,
+        force,
+        environment,
+        action: "archive",
+      });
       const resolvedFormat = resolveOutputFormat(format, environment, "json");
       const dispatch = yield* application.archiveThread(threadId);
       if (resolvedFormat === "json") {