Commit 834e5db45843d8b5da4fbfe1999fbaa4c58e117b | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-06-20 15:14:55-07:00
committer	GitHub <noreply@github.com> 2026-06-20 15:14:55-07:00
log	834e5db45843d8b5da4fbfe1999fbaa4c58e117b
tree	6ac17380d4bea5227ad6408b91a8bf3adf7a1831
parent	8ce627ba91a6c4e5b336bc50c2fa06ebf4f4ade6
signature	Signed by PGP key B5690EEEBB952194

[codex] structure project CLI failures (#3339)

Co-authored-by: codex <codex@users.noreply.github.com>

2 files changed, 118 insertions(+), 43 deletions(-)

apps
- server
  - src
    cli
    project.test.ts
    project.ts

apps/server/src/cli/project.test.ts created+32

...	@@ -0,0 +1,32 @@
1	import { assert, it } from "@effect/vitest";
2
3	import { EnvironmentInternalError } from "@t3tools/contracts";
4
5	import { ProjectCommandError } from "./project.ts";
6
7	it("maps declared server failures into structural project command errors", () => {
8	const cause = new EnvironmentInternalError({
9	code: "internal_error",
10	reason: "orchestration_snapshot_failed",
11	traceId: "trace-123",
12	});
13
14	const error = ProjectCommandError.fromLiveServerRequest(cause);
15
16	assert.strictEqual(error.operation, "callLiveServer");
17	assert.strictEqual(error.code, "internal_error");
18	assert.strictEqual(error.traceId, "trace-123");
19	assert.strictEqual(error.message, "Server request failed (internal_error, trace trace-123).");
20	assert.strictEqual(error.cause, cause);
21	});
22
23	it("preserves unexpected server failures without deriving the message from them", () => {
24	const cause = new Error("credential abc123 was rejected");
25
26	const error = ProjectCommandError.fromLiveServerRequest(cause);
27
28	assert.strictEqual(error.operation, "callLiveServer");
29	assert.strictEqual(error.detail, "Failed to call the running server.");
30	assert.strictEqual(error.message, "Failed to call the running server.");
31	assert.strictEqual(error.cause, cause);
32	});

apps/server/src/cli/project.ts+86-43

 @@ -9,11 +9,9 @@ import {
 } from "@t3tools/contracts";
 import * as Console from "effect/Console";
 import * as Crypto from "effect/Crypto";
-import * as Data from "effect/Data";
 import * as DateTime from "effect/DateTime";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
-import * as Exit from "effect/Exit";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 @@ -52,16 +50,64 @@ type ProjectCliDispatchCommand = Extract<
   { type: "project.create" | "project.meta.update" | "project.delete" }
 >;
-class ProjectCommandError extends Data.TaggedError("ProjectCommandError")<{
+const isEnvironmentHttpCommonError = Schema.is(EnvironmentHttpCommonError);
-  readonly message: string;
+const ProjectCommandOperation = Schema.Literals([
-}> {}
+  "generateProjectCommandId",
+  "callLiveServer",
+  "validateProjectTitle",
+  "resolveProjectTarget",
+  "addProject",
+]);
+export class ProjectCommandError extends Schema.TaggedErrorClass<ProjectCommandError>()(
+  "ProjectCommandError",
+  {
+    operation: ProjectCommandOperation,
+    detail: Schema.String,
+    code: Schema.optional(Schema.String),
+    traceId: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.Number),
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  static fromLiveServerRequest(cause: unknown): ProjectCommandError {
+    if (isEnvironmentHttpCommonError(cause)) {
+      return new ProjectCommandError({
+        operation: "callLiveServer",
+        detail: `Server request failed (${cause.code}, trace ${cause.traceId}).`,
+        code: cause.code,
+        traceId: cause.traceId,
+        cause,
+      });
+    }
+    if (HttpClientError.isHttpClientError(cause) && cause.response !== undefined) {
+      return new ProjectCommandError({
+        operation: "callLiveServer",
+        detail: `Server request failed with undeclared status ${cause.response.status}.`,
+        status: cause.response.status,
+        cause,
+      });
+    }
+    return new ProjectCommandError({
+      operation: "callLiveServer",
+      detail: "Failed to call the running server.",
+      cause,
+    });
+  }
+  override get message(): string {
+    return this.detail;
+  }
+}
 const projectCommandUuid = Crypto.Crypto.pipe(
   Effect.flatMap((crypto) => crypto.randomUUIDv4),
   Effect.mapError(
-    () =>
+    (cause) =>
       new ProjectCommandError({
-        message: "Failed to generate a project command identifier.",
+        operation: "generateProjectCommandId",
+        detail: "Failed to generate a project command identifier.",
+        cause,
       }),
   ),
 );
 @@ -75,7 +121,6 @@ const ProjectCliRuntimeLive = Layer.mergeAll(
 );
 const PROJECT_CLI_LIVE_SERVER_TIMEOUT = Duration.seconds(1);
-const isEnvironmentHttpCommonError = Schema.is(EnvironmentHttpCommonError);
 const withProjectCliSessionToken = <A, E, R>(
   environmentAuth: EnvironmentAuth.EnvironmentAuth["Service"],
   run: (token: string) => Effect.Effect<A, E, R>,
 @@ -92,28 +137,6 @@ const withProjectCliSessionToken = <A, E, R>(
 const withProjectCliLiveServerTimeout = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
   effect.pipe(Effect.timeout(PROJECT_CLI_LIVE_SERVER_TIMEOUT));
-const failLiveServerRequest = (cause: unknown) => {
-  if (isEnvironmentHttpCommonError(cause)) {
-    return Effect.fail(
-      new ProjectCommandError({
-        message: `Server request failed (${cause.code}, trace ${cause.traceId}).`,
-      }),
-    );
-  }
-  if (HttpClientError.isHttpClientError(cause) && cause.response !== undefined) {
-    return Effect.fail(
-      new ProjectCommandError({
-        message: `Server request failed with undeclared status ${cause.response.status}.`,
-      }),
-    );
-  }
-  return Effect.fail(
-    new ProjectCommandError({
-      message: `Failed to call running server: ${String(cause)}.`,
-    }),
-  );
-};
 const makeLiveServerClient = (origin: string) =>
   HttpApiClient.make(EnvironmentHttpApi, {
     baseUrl: origin,
 @@ -135,7 +158,10 @@ const resolveProjectTitle = Effect.fn("resolveProjectTitle")(function* (
     if (trimmed.length > 0) {
       return trimmed;
     }
-    return yield* new ProjectCommandError({ message: "Project title cannot be empty." });
+    return yield* new ProjectCommandError({
+      operation: "validateProjectTitle",
+      detail: "Project title cannot be empty.",
+    });
   }
   const path = yield* Path.Path;
 @@ -149,7 +175,10 @@ const findActiveProjectTarget = Effect.fn("findActiveProjectTarget")(function* (
 }) {
   const trimmedIdentifier = input.identifier.trim();
   if (trimmedIdentifier.length === 0) {
-    return yield* new ProjectCommandError({ message: "Project identifier cannot be empty." });
+    return yield* new ProjectCommandError({
+      operation: "resolveProjectTarget",
+      detail: "Project identifier cannot be empty.",
+    });
   }
   const activeProjects = input.snapshot.projects.filter((project) => project.deletedAt === null);
 @@ -162,12 +191,11 @@ const findActiveProjectTarget = Effect.fn("findActiveProjectTarget")(function* (
     } satisfies ProjectMutationTarget;
   }
-  const normalizedWorkspaceRootResult = yield* Effect.exit(
+  const normalizedWorkspaceRootResult = yield* Effect.result(
     normalizeWorkspaceRootForProjectCommand(trimmedIdentifier),
   );
-  const normalizedWorkspaceRoot = Exit.isSuccess(normalizedWorkspaceRootResult)
+  const normalizedWorkspaceRoot =
-    ? normalizedWorkspaceRootResult.value
+    normalizedWorkspaceRootResult._tag === "Success" ? normalizedWorkspaceRootResult.success : null;
-    : null;
   const exactWorkspaceMatch =
     normalizedWorkspaceRoot === null
 @@ -177,7 +205,11 @@ const findActiveProjectTarget = Effect.fn("findActiveProjectTarget")(function* (
   const resolved = exactWorkspaceMatch;
   if (!resolved) {
     return yield* new ProjectCommandError({
-      message: `No active project found for '${trimmedIdentifier}'.`,
+      operation: "resolveProjectTarget",
+      detail: `No active project found for '${trimmedIdentifier}'.`,
+      ...(normalizedWorkspaceRootResult._tag === "Failure"
+        ? { cause: normalizedWorkspaceRootResult.failure }
+        : {}),
     });
   }
 @@ -194,7 +226,10 @@ const fetchLiveOrchestrationSnapshot = (origin: string, bearerToken: string) =>
     return yield* client.orchestration.snapshot({
       headers: { authorization: `Bearer ${bearerToken}` },
     });
-  }).pipe(withProjectCliLiveServerTimeout, Effect.catch(failLiveServerRequest));
+  }).pipe(
+    withProjectCliLiveServerTimeout,
+    Effect.mapError(ProjectCommandError.fromLiveServerRequest),
+  );
 const dispatchLiveOrchestrationCommand = (
   origin: string,
 @@ -207,7 +242,10 @@ const dispatchLiveOrchestrationCommand = (
       headers: { authorization: `Bearer ${bearerToken}` },
       payload: command,
     } as Parameters<typeof client.orchestration.dispatch>[0]);
-  }).pipe(withProjectCliLiveServerTimeout, Effect.catch(failLiveServerRequest));
+  }).pipe(
+    withProjectCliLiveServerTimeout,
+    Effect.mapError(ProjectCommandError.fromLiveServerRequest),
+  );
 const getOfflineSnapshot = Effect.fn("getOfflineSnapshot")(function* () {
   const projectionSnapshotQuery = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
 @@ -232,11 +270,15 @@ const tryResolveLiveProjectExecutionMode = Effect.fn("tryResolveLiveProjectExecu
       ),
     );
-    const attempted = yield* Effect.exit(attempt);
+    const attempted = yield* Effect.result(attempt);
-    if (Exit.isSuccess(attempted)) {
+    if (attempted._tag === "Success") {
-      return Option.some(attempted.value);
+      return Option.some(attempted.success);
     }
+    yield* Effect.logDebug("Failed to connect to the persisted project CLI server.", {
+      origin: runtimeState.value.origin,
+      cause: attempted.failure,
+    });
     yield* clearPersistedServerRuntimeState(config.serverRuntimeStatePath);
     return Option.none<{ readonly origin: string }>();
   },
 @@ -335,7 +377,8 @@ const projectAddCommand = Command.make("add", {
         );
         if (existingProject) {
           return yield* new ProjectCommandError({
-            message: `An active project already exists for '${workspaceRoot}'.`,
+            operation: "addProject",
+            detail: `An active project already exists for '${workspaceRoot}'.`,
           });
         }