t3code-cli 0.10.0 → 0.11.0

package/src/cli/error.ts

@@ -22,11 +22,20 @@ export class MissingThreadError extends Schema.TaggedErrorClass<MissingThreadErr
   },
 ) {}
 
-export class SelfArchiveError extends Schema.TaggedErrorClass<SelfArchiveError>()(
-  "SelfArchiveError",
+export class SelfActionError extends Schema.TaggedErrorClass<SelfActionError>()("SelfActionError", {
+  message: Schema.String,
+  threadId: Schema.String,
+}) {}
+
+export class DestructiveConfirmationRequiredError extends Schema.TaggedErrorClass<DestructiveConfirmationRequiredError>()(
+  "DestructiveConfirmationRequiredError",
+  { message: Schema.String },
+) {}
+
+export class InvalidFlagCombinationError extends Schema.TaggedErrorClass<InvalidFlagCombinationError>()(
+  "InvalidFlagCombinationError",
   {
     message: Schema.String,
-    threadId: Schema.String,
   },
 ) {}
 
@@ -36,3 +45,17 @@ export class MissingRequestError extends Schema.TaggedErrorClass<MissingRequestE
     message: Schema.String,
   },
 ) {}
+
+export class MissingUpdateFieldsError extends Schema.TaggedErrorClass<MissingUpdateFieldsError>()(
+  "MissingUpdateFieldsError",
+  {
+    message: Schema.String,
+  },
+) {}
+
+export class ConflictingUpdateFlagsError extends Schema.TaggedErrorClass<ConflictingUpdateFlagsError>()(
+  "ConflictingUpdateFlagsError",
+  {
+    message: Schema.String,
+  },
+) {}

package/src/cli/flags.ts

@@ -30,6 +30,21 @@ export const projectPathFlag = Flag.string("path").pipe(
   Flag.withDefault("."),
 );
 
+export const yesFlag = Flag.boolean("yes").pipe(
+  Flag.withDescription("Skip interactive confirmation"),
+  Flag.withDefault(false),
+);
+
+export const forceFlag = Flag.boolean("force").pipe(
+  Flag.withDescription("Delete non-empty project (cascade thread deletes)"),
+  Flag.withDefault(false),
+);
+
+export const selfActionForceFlag = Flag.boolean("force").pipe(
+  Flag.withDescription("Confirm an action targeting the calling agent thread"),
+  Flag.withAlias("f"),
+);
+
 export const formatFlag = Flag.choice("format", humanJsonFormatChoices).pipe(
   Flag.withDefault("auto"),
 );

package/src/cli/input/layer.ts

@@ -23,8 +23,28 @@ export const makeT3Input = Effect.fn("makeT3Input")(function* () {
     );
   });
 
+  const readStdinBinary = Effect.fn("T3InputLive.readStdinBinary")(function* () {
+    return yield* stdio.stdin.pipe(
+      Stream.runFold(
+        () => new Uint8Array(0),
+        (acc, chunk) => {
+          const merged = new Uint8Array(acc.length + chunk.length);
+          merged.set(acc);
+          merged.set(chunk, acc.length);
+          return merged;
+        },
+      ),
+      Effect.map((bytes) => Buffer.from(bytes).toString("latin1")),
+      Effect.catchTags({
+        PlatformError: (error) =>
+          Effect.fail(new InputError({ message: "failed to read stdin", cause: error })),
+      }),
+    );
+  });
+
   return {
     readStdin,
+    readStdinBinary,
   };
 });
 

package/src/cli/input/service.ts

@@ -7,5 +7,6 @@ export class T3Input extends Context.Service<
   T3Input,
   {
     readonly readStdin: () => Effect.Effect<string, InputError>;
+    readonly readStdinBinary: () => Effect.Effect<string, InputError>;
   }
 >()("t3cli/T3Input") {}

package/src/cli/output-format.ts

@@ -25,13 +25,17 @@ export function canRenderLiveTerminal(environment: EnvironmentShape) {
   );
 }
 
-function isHumanTerminal(environment: EnvironmentShape) {
+export function isInteractiveHumanTerminal(environment: EnvironmentShape) {
   return (
     environment.stdoutIsTTY && !isAgentEnvironment(environment) && environment.env.TERM !== "dumb"
   );
 }
 
-function isAgentEnvironment(environment: EnvironmentShape) {
+function isHumanTerminal(environment: EnvironmentShape) {
+  return isInteractiveHumanTerminal(environment);
+}
+
+export function isAgentEnvironment(environment: EnvironmentShape) {
   return (
     environment.env.CI !== undefined ||
     environment.env.CODEX_CI !== undefined ||

package/src/cli/project-format.ts

@@ -9,3 +9,10 @@ export function formatProjectsHuman(projects: ReadonlyArray<OrchestrationProject
 export function formatProjectAddedHuman(project: OrchestrationProjectShell) {
   return `project added: ${project.title}\nid: ${project.id}\npath: ${project.workspaceRoot}`;
 }
+
+export function formatProjectDeletedHuman(input: {
+  readonly projectId: string;
+  readonly dispatch: { readonly sequence: number };
+}) {
+  return `project deleted: ${input.projectId}\nsequence: ${input.dispatch.sequence}`;
+}

package/src/cli/project.ts

@@ -4,6 +4,7 @@ import { Command, Flag } from "effect/unstable/cli";
 
 import { formatFlag, projectPathFlag } from "./flags.ts";
 import { formatProjectAddedHuman, formatProjectsHuman } from "./project-format.ts";
+import { deleteProjectCommand } from "./projects/delete.ts";
 import { T3Application } from "../application/service.ts";
 import { Environment } from "../environment/service.ts";
 import { resolveOutputFormat } from "./output-format.ts";
@@ -12,7 +13,7 @@ import { T3Output } from "./output/service.ts";
 export function createProjectCommand() {
   return Command.make("project").pipe(
     Command.withDescription("project commands"),
-    Command.withSubcommands([listCommand, addCommand]),
+    Command.withSubcommands([listCommand, addCommand, deleteProjectCommand]),
   );
 }
 

package/src/cli/projects/delete.ts

@@ -0,0 +1,50 @@
+import * as Effect from "effect/Effect";
+import { Command } from "effect/unstable/cli";
+
+import { requireDestructiveConfirmation } from "../confirm.ts";
+import { forceFlag, formatFlag, projectFlag, yesFlag } from "../flags.ts";
+import { formatProjectDeletedHuman } from "../project-format.ts";
+import { requireCommandProjectRef } from "../require.ts";
+import { T3Application } from "../../application/service.ts";
+import { Environment } from "../../environment/service.ts";
+import { resolveOutputFormat } from "../output-format.ts";
+import { T3Output } from "../output/service.ts";
+
+export const deleteProjectCommand = Command.make(
+  "delete",
+  {
+    project: projectFlag,
+    force: forceFlag,
+    yes: yesFlag,
+    format: formatFlag,
+  },
+  ({ project, force, yes, format }) =>
+    Effect.gen(function* () {
+      const application = yield* T3Application;
+      const environment = yield* Environment;
+      const output = yield* T3Output;
+      const projectRef = yield* requireCommandProjectRef({
+        project,
+        env: environment.env,
+        cwd: environment.cwd,
+      });
+      const resolvedProject = yield* application.resolveProject(projectRef);
+      yield* requireDestructiveConfirmation({
+        message: `Delete project ${resolvedProject.title} (${resolvedProject.id})?`,
+        yes,
+        environment,
+      });
+      const resolvedFormat = resolveOutputFormat(format, environment, "json");
+      const result = yield* application.deleteProject({
+        projectId: resolvedProject.id,
+        ...(force ? { force: true } : {}),
+      });
+      if (resolvedFormat === "json") {
+        return yield* output.printJson({
+          projectId: result.projectId,
+          dispatch: result.dispatch,
+        });
+      }
+      return yield* output.printInfo(formatProjectDeletedHuman(result));
+    }),
+).pipe(Command.withDescription("delete project"));

package/src/cli/self-action.ts

@@ -0,0 +1,34 @@
+import * as Effect from "effect/Effect";
+
+import { SelfActionError } from "./error.ts";
+import { isAgentEnvironment } from "./output-format.ts";
+import type { EnvironmentShape } from "../environment/service.ts";
+
+export const requireSelfActionConfirmation = Effect.fn("requireSelfActionConfirmation")(
+  function* (input: {
+    readonly threadId: string;
+    readonly force: boolean;
+    readonly environment: EnvironmentShape;
+    readonly action: string;
+  }) {
+    if (input.force) {
+      return;
+    }
+    if (!isAgentEnvironment(input.environment)) {
+      return;
+    }
+    const callerThreadId = input.environment.env.T3CODE_THREAD_ID;
+    if (callerThreadId === undefined || callerThreadId.length === 0) {
+      return;
+    }
+    if (input.threadId !== callerThreadId) {
+      return;
+    }
+    yield* Effect.fail(
+      new SelfActionError({
+        threadId: input.threadId,
+        message: `cannot ${input.action} thread ${input.threadId}: command targets the calling thread. Pass --force to confirm.`,
+      }),
+    );
+  },
+);

package/src/cli/terminal/attach.ts

@@ -0,0 +1,32 @@
+import * as Effect from "effect/Effect";
+import { Argument, Command } from "effect/unstable/cli";
+
+import { T3Application } from "../../application/service.ts";
+import { Environment } from "../../environment/service.ts";
+import { threadFlag } from "../flags.ts";
+import { requireCommandThreadId } from "./scope.ts";
+import { runAttachedTerminalSession, toTerminalAttachTarget } from "./shared.ts";
+
+export const attachTerminalCommand = Command.make(
+  "attach",
+  {
+    thread: threadFlag,
+    terminalId: Argument.string("terminal-id"),
+  },
+  ({ thread, terminalId }) =>
+    Effect.gen(function* () {
+      const application = yield* T3Application;
+      const environment = yield* Environment;
+      const threadId = yield* requireCommandThreadId({
+        thread,
+        env: environment.env,
+      });
+      const terminal = yield* application.getTerminal({
+        threadId,
+        terminalId,
+      });
+      yield* runAttachedTerminalSession({
+        terminal: toTerminalAttachTarget(terminal),
+      });
+    }),
+).pipe(Command.withDescription("attach to a terminal"));

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

@@ -0,0 +1,101 @@
+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 { assert, describe, 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 { InvalidFlagCombinationError } from "../error.ts";
+import { T3Input } from "../input/service.ts";
+import { T3Output } from "../output/service.ts";
+import { readTerminalCommand } from "./read.ts";
+import { writeTerminalCommand } from "./write.ts";
+
+const testLayer = Layer.mergeAll(
+  Layer.succeed(
+    T3Application,
+    fromPartial({
+      getTerminal: () => Effect.die("getTerminal should not be called"),
+      attachTerminal: () => Effect.die("attachTerminal should not be called"),
+      writeTerminal: () => Effect.die("writeTerminal should not be called"),
+    }),
+  ),
+  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,
+  }),
+  Layer.succeed(T3Input, {
+    readStdin: () => Effect.die("readStdin should not be called"),
+    readStdinBinary: () => Effect.die("readStdinBinary should not be called"),
+  }),
+  NodeServices.layer,
+  NodeEnvironmentLive,
+);
+
+describe("readTerminalCommand", () => {
+  it.layer(testLayer)("readTerminalCommand", (t) => {
+    t.effect("rejects --from-sequence without --follow", () =>
+      Effect.gen(function* () {
+        const run = Command.runWith(readTerminalCommand, { version: "0.0.0-test" });
+        const exit = yield* run(["--thread", "thread-1", "term-1", "--from-sequence", "1"]).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, InvalidFlagCombinationError);
+          assert.equal(error.value.message, "--from-sequence requires --follow");
+        }
+      }),
+    );
+  });
+});
+
+describe("writeTerminalCommand", () => {
+  it.layer(testLayer)("writeTerminalCommand", (t) => {
+    t.effect("rejects multiple payload sources", () =>
+      Effect.gen(function* () {
+        const run = Command.runWith(writeTerminalCommand, { version: "0.0.0-test" });
+        const exit = yield* run(["--thread", "thread-1", "term-1", "hello", "--stdin"]).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, InvalidFlagCombinationError);
+        }
+      }),
+    );
+  });
+});

package/src/cli/terminal/create.ts

@@ -0,0 +1,54 @@
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { formatTerminalCreatedHuman } 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";
+import { runAttachedTerminalSession, snapshotToTerminalAttachTarget } from "./shared.ts";
+
+export const createTerminalCommand = Command.make(
+  "create",
+  {
+    thread: threadFlag,
+    command: Argument.string("command").pipe(Argument.optional),
+    id: Flag.string("id").pipe(Flag.optional),
+    attach: Flag.boolean("attach"),
+    format: formatFlag,
+  },
+  ({ thread, command, id, attach, 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 terminalId = Option.getOrUndefined(id);
+      const commandValue = Option.getOrUndefined(command);
+      const snapshot = yield* application.createTerminal({
+        threadId,
+        ...(terminalId !== undefined ? { terminalId } : {}),
+        ...(commandValue !== undefined ? { command: commandValue } : {}),
+      });
+
+      if (attach) {
+        yield* runAttachedTerminalSession({
+          terminal: snapshotToTerminalAttachTarget(snapshot),
+        });
+        return;
+      }
+
+      const resolvedFormat = resolveOutputFormat(format, environment, "json");
+      if (resolvedFormat === "json") {
+        yield* output.printJson(snapshot);
+      } else {
+        yield* output.printInfo(formatTerminalCreatedHuman(snapshot));
+      }
+    }),
+).pipe(Command.withDescription("create a terminal for a thread"));

package/src/cli/terminal/destroy.ts

@@ -0,0 +1,60 @@
+import * as Effect from "effect/Effect";
+import { Argument, Command, Flag } from "effect/unstable/cli";
+
+import { requireDestructiveConfirmation } from "../confirm.ts";
+import { formatTerminalDestroyedHuman } from "../terminal-format.ts";
+import { T3Application } from "../../application/service.ts";
+import { Environment } from "../../environment/service.ts";
+import { formatFlag, threadFlag, yesFlag } from "../flags.ts";
+import { resolveOutputFormat } from "../output-format.ts";
+import { T3Output } from "../output/service.ts";
+import { requireCommandThreadId } from "./scope.ts";
+
+export const destroyTerminalCommand = Command.make(
+  "destroy",
+  {
+    thread: threadFlag,
+    terminalId: Argument.string("terminal-id"),
+    quiet: Flag.boolean("quiet"),
+    yes: yesFlag,
+    format: formatFlag,
+  },
+  ({ thread, terminalId, quiet, yes, format }) =>
+    Effect.gen(function* () {
+      const application = yield* T3Application;
+      const environment = yield* Environment;
+      const output = yield* T3Output;
+      const threadId = yield* requireCommandThreadId({
+        thread,
+        env: environment.env,
+      });
+      yield* requireDestructiveConfirmation({
+        message: `Destroy terminal ${terminalId} in thread ${threadId} and delete its history?`,
+        yes,
+        environment,
+      });
+      const terminal = {
+        threadId,
+        terminalId,
+      };
+      yield* application.destroyTerminal(terminal);
+      if (quiet) {
+        return;
+      }
+      const resolvedFormat = resolveOutputFormat(format, environment, "json");
+      if (resolvedFormat === "json") {
+        yield* output.printJson({
+          threadId: terminal.threadId,
+          terminalId: terminal.terminalId,
+          destroyed: true,
+        });
+        return;
+      }
+      yield* output.printInfo(
+        formatTerminalDestroyedHuman({
+          terminalId,
+          threadId,
+        }),
+      );
+    }),
+).pipe(Command.withDescription("destroy a terminal and its history"));

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

@@ -0,0 +1,63 @@
+import "vite-plus/test/config";
+
+import { describe, expect, it } from "vite-plus/test";
+
+import { decodeBase64Payload, decodeHexPayload } from "./encoding.ts";
+import { filterAttachStreamEvent } from "./shared.ts";
+
+describe("terminal encoding", () => {
+  it("preserves non-utf8 bytes in hex payloads", () => {
+    expect(decodeHexPayload("ff")).toBe("\xff");
+  });
+
+  it("preserves non-utf8 bytes in base64 payloads", () => {
+    expect(decodeBase64Payload("/w==")).toBe("\xff");
+  });
+});
+
+describe("filterAttachStreamEvent", () => {
+  const snapshotEvent = {
+    type: "snapshot" as const,
+    snapshot: {
+      threadId: "thread-1",
+      terminalId: "term-1",
+      cwd: "/tmp",
+      worktreePath: null,
+      status: "running" as const,
+      pid: 1,
+      history: "hello",
+      exitCode: null,
+      exitSignal: null,
+      label: "shell",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+      sequence: 3,
+    },
+  };
+
+  it("keeps snapshot history when --history is set with --from-sequence", () => {
+    const filtered = filterAttachStreamEvent(snapshotEvent, {
+      includeHistory: true,
+      fromSequence: 5,
+    });
+    expect(filtered?.type).toBe("snapshot");
+    if (filtered?.type === "snapshot") {
+      expect(filtered.snapshot.history).toBe("hello");
+    }
+  });
+
+  it("filters sequenced events inclusively from --from-sequence", () => {
+    const outputEvent = {
+      type: "output" as const,
+      threadId: "thread-1",
+      terminalId: "term-1",
+      sequence: 5,
+      data: "x",
+    };
+    expect(
+      filterAttachStreamEvent(outputEvent, { includeHistory: false, fromSequence: 5 }),
+    ).toEqual(outputEvent);
+    expect(
+      filterAttachStreamEvent(outputEvent, { includeHistory: false, fromSequence: 6 }),
+    ).toBeNull();
+  });
+});

package/src/cli/terminal/encoding.ts

@@ -0,0 +1,23 @@
+export function bytesToLatin1String(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("latin1");
+}
+
+export function decodeHexPayload(value: string): string | undefined {
+  const normalized = value.trim();
+  if (
+    normalized.length === 0 ||
+    normalized.length % 2 !== 0 ||
+    !/^[0-9a-fA-F]+$/.test(normalized)
+  ) {
+    return undefined;
+  }
+  return Buffer.from(normalized, "hex").toString("latin1");
+}
+
+export function decodeBase64Payload(value: string): string | undefined {
+  const normalized = value.trim();
+  if (normalized.length === 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(normalized)) {
+    return undefined;
+  }
+  return Buffer.from(normalized, "base64").toString("latin1");
+}

package/src/cli/terminal/error.ts

@@ -0,0 +1,14 @@
+import * as Schema from "effect/Schema";
+
+export class TerminalCliError extends Schema.TaggedErrorClass<TerminalCliError>()(
+  "TerminalCliError",
+  {
+    message: Schema.String,
+    threadId: Schema.optionalKey(Schema.String),
+    terminalId: Schema.optionalKey(Schema.String),
+  },
+) {}
+
+export class TerminalIoError extends Schema.TaggedErrorClass<TerminalIoError>()("TerminalIoError", {
+  message: Schema.String,
+}) {}

package/src/cli/terminal/io-node-layer.ts

@@ -0,0 +1,82 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+
+import { TerminalIoError } from "./error.ts";
+import { TerminalIo, type RawTerminalIoSession, type TerminalWindowSize } from "./io-service.ts";
+
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+const INTERACTIVE_TTY_MESSAGE = "terminal attach requires an interactive TTY on stdin and stdout";
+
+const requireInteractiveTty = Effect.gen(function* () {
+  if (!process.stdin.isTTY || !process.stdout.isTTY || process.stdin.setRawMode === undefined) {
+    return yield* Effect.fail(new TerminalIoError({ message: INTERACTIVE_TTY_MESSAGE }));
+  }
+
+  return {
+    stdin: process.stdin,
+    stdout: process.stdout,
+  };
+});
+
+export const NodeTerminalIoLive = Layer.succeed(TerminalIo, {
+  getWindowSize: requireInteractiveTty.pipe(Effect.map(readWindowSize)),
+  writeOutput: (text: string) =>
+    Effect.sync(() => {
+      process.stdout.write(text);
+    }),
+  openRawSession: Effect.acquireRelease(
+    Effect.gen(function* () {
+      const tty = yield* requireInteractiveTty;
+      const input = yield* Queue.unbounded<Uint8Array>();
+      const resize = yield* Queue.unbounded<TerminalWindowSize>();
+
+      const onResize = () => {
+        Effect.runFork(Queue.offer(resize, readWindowSize(tty)).pipe(Effect.ignore));
+      };
+
+      const onData = (chunk: Buffer | string) => {
+        Effect.runFork(
+          Queue.offer(input, typeof chunk === "string" ? Buffer.from(chunk) : chunk).pipe(
+            Effect.ignore,
+          ),
+        );
+      };
+
+      tty.stdin.resume();
+      tty.stdin.setRawMode(true);
+      process.on("SIGWINCH", onResize);
+      tty.stdin.on("data", onData);
+
+      return {
+        tty,
+        input,
+        resize,
+        onData,
+        onResize,
+        session: {
+          input: Stream.fromQueue(input),
+          resize: Stream.fromQueue(resize),
+        } satisfies RawTerminalIoSession,
+      };
+    }),
+    ({ tty, input, resize, onData, onResize }) =>
+      Effect.gen(function* () {
+        tty.stdin.off("data", onData);
+        process.off("SIGWINCH", onResize);
+        tty.stdin.setRawMode(false);
+        tty.stdin.pause();
+        yield* Queue.shutdown(input);
+        yield* Queue.shutdown(resize);
+      }),
+  ).pipe(Effect.map(({ session }) => session)),
+});
+
+function readWindowSize(tty: { readonly stdout: NodeJS.WriteStream }): TerminalWindowSize {
+  return {
+    cols: tty.stdout.columns ?? DEFAULT_COLS,
+    rows: tty.stdout.rows ?? DEFAULT_ROWS,
+  };
+}