fix(api): address project inventory review notes

Author: skulidropek

packages/api/src/http.ts

@@ -806,7 +806,7 @@ export const makeRouter = () => {
       "/health",
       Effect.gen(function*(_) {
         const cwd = yield* _(resolveWorkspaceRoot(process.cwd()).pipe(Effect.orElseSucceed(() => process.cwd())))
-        const projectsRoot = defaultProjectsRoot(process.cwd())
+        const projectsRoot = defaultProjectsRoot(cwd)
         return yield* _(jsonResponse({ ok: true, revision: controllerRevision, cwd, projectsRoot }, 200))
       }).pipe(Effect.catchAll(errorResponse))
     ),

packages/api/tests/api-console-routes.test.ts

@@ -6,6 +6,8 @@ import type { PlatformError } from "@effect/platform/Error"
 import { NodeContext } from "@effect/platform-node"
 import { describe, expect, it } from "@effect/vitest"
 import { Effect } from "effect"
+import type * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
 import * as Scope from "effect/Scope"
 
 import { makeRouter } from "../src/http.js"
@@ -20,6 +22,29 @@ const requestApiRoute = (path: string) =>
     catch: (cause) => new Error(String(cause))
   })
 
+const HealthResponseSchema = Schema.Struct({
+  cwd: Schema.String,
+  ok: Schema.Boolean,
+  projectsRoot: Schema.String,
+  revision: Schema.NullOr(Schema.String)
+})
+
+type HealthResponse = Schema.Schema.Type<typeof HealthResponseSchema>
+
+/**
+ * Creates a scoped temporary directory and provides its path to the supplied effect.
+ *
+ * @param use - Effect factory that receives the temporary directory path.
+ * @returns Effect that yields the factory result and finalizes the temporary directory scope.
+ *
+ * @pure false
+ * @effect FileSystem service for scoped directory allocation and cleanup
+ * @invariant the temporary directory lifetime is bounded by the returned Effect scope
+ * @precondition FileSystem service is available in the environment
+ * @postcondition the temporary directory scope is finalized after success or failure
+ * @complexity O(1) allocation; cleanup is O(n) in created filesystem entries
+ * @throws Never - filesystem and user errors are represented in the Effect error channel
+ */
 const withTempDir = <A, E, R>(
   use: (tempDir: string) => Effect.Effect<A, E, R>
 ): Effect.Effect<A, E | PlatformError, FileSystem.FileSystem | Exclude<R, Scope.Scope>> =>
@@ -35,6 +60,22 @@ const withTempDir = <A, E, R>(
     })
   )
 
+/**
+ * Temporarily sets or unsets an environment variable for the duration of an effect.
+ *
+ * @param key - Environment variable name to modify.
+ * @param value - Temporary value, or undefined to remove the variable.
+ * @param effect - Effect evaluated while the temporary environment binding is active.
+ * @returns Effect that yields the supplied effect result and restores the previous binding.
+ *
+ * @pure false
+ * @effect process environment mutation inside acquire/release
+ * @invariant the previous environment value is restored exactly once during finalization
+ * @precondition key is a non-empty environment variable name accepted by the runtime
+ * @postcondition process.env[key] equals its previous value after the scope finalizes
+ * @complexity O(1) time and space
+ * @throws Never - user effect errors are represented in the Effect error channel
+ */
 const withEnvVar = <A, E, R>(
   key: string,
   value: string | undefined,
@@ -62,14 +103,11 @@ const withEnvVar = <A, E, R>(
     ).pipe(Effect.flatMap(() => effect))
   )
 
-const readResponseJson = (response: Response) =>
+const readHealthResponse = (response: Response): Effect.Effect<HealthResponse, Error | ParseResult.ParseError> =>
   Effect.tryPromise({
     try: () => response.json(),
     catch: (cause) => new Error(String(cause))
-  })
-
-const objectOrNull = (value: unknown): object | null =>
-  typeof value === "object" && value !== null && !Array.isArray(value) ? value : null
+  }).pipe(Effect.flatMap(Schema.decodeUnknown(HealthResponseSchema)))
 
 describe("api console routes", () => {
   it.effect("does not serve the legacy built-in API console", () =>
@@ -90,12 +128,10 @@ describe("api console routes", () => {
         const response = yield* _(
           withEnvVar("DOCKER_GIT_PROJECTS_ROOT", projectsRoot, requestApiRoute("/health"))
         )
-        const payload = yield* _(readResponseJson(response))
-        const objectPayload = objectOrNull(payload)
+        const payload = yield* _(readHealthResponse(response))
 
         expect(response.status).toBe(200)
-        expect(objectPayload).not.toBeNull()
-        expect(Reflect.get(objectPayload ?? {}, "projectsRoot")).toBe(projectsRoot)
+        expect(payload.projectsRoot).toBe(projectsRoot)
       })
     ).pipe(Effect.provide(NodeContext.layer)))
 })

packages/api/tests/projects.test.ts

@@ -1,3 +1,4 @@
+import type * as CommandExecutor from "@effect/platform/CommandExecutor"
 import * as FileSystem from "@effect/platform/FileSystem"
 import type { PlatformError } from "@effect/platform/Error"
 import * as Path from "@effect/platform/Path"
@@ -129,29 +130,61 @@ const gitEnv: Readonly<Record<string, string>> = {
   GIT_TERMINAL_PROMPT: "0"
 }
 
+/**
+ * Runs a git command with the deterministic test git environment.
+ *
+ * @param cwd - Working directory for the git process.
+ * @param args - Git CLI arguments passed without shell interpolation.
+ * @returns Effect that yields captured stdout or fails with a typed command/platform error.
+ *
+ * @pure false
+ * @effect CommandExecutor service for process execution
+ * @complexity O(1) process spawn plus O(git operation)
+ */
 const runGit = (
   cwd: string,
   args: ReadonlyArray<string>
-) =>
+): Effect.Effect<string, CommandFailedError | PlatformError, CommandExecutor.CommandExecutor> =>
   runCommandCapture(
     { cwd, command: "git", args, env: gitEnv },
     [0],
     (exitCode) => new CommandFailedError({ command: `git ${args[0] ?? ""}`, exitCode })
   )
 
+/**
+ * Runs a shell script with the deterministic test git environment.
+ *
+ * @param cwd - Working directory for the shell process.
+ * @param script - POSIX shell script to execute.
+ * @returns Effect that yields captured stdout or fails with a typed command/platform error.
+ *
+ * @pure false
+ * @effect CommandExecutor service for process execution
+ * @complexity O(1) process spawn plus O(script)
+ */
 const runShell = (
   cwd: string,
   script: string
-) =>
+): Effect.Effect<string, CommandFailedError | PlatformError, CommandExecutor.CommandExecutor> =>
   runCommandCapture(
     { cwd, command: "sh", args: ["-c", script], env: gitEnv },
     [0],
     (exitCode) => new CommandFailedError({ command: "sh -c", exitCode })
   )
 
+/**
+ * Creates a bare state remote and seeds an initial main branch commit.
+ *
+ * @param root - Directory that will contain the remote and seed repositories.
+ * @returns Effect that yields the bare remote path.
+ *
+ * @pure false
+ * @effect Path and CommandExecutor services for path construction and git processes
+ * @complexity O(1) filesystem paths plus O(git init + commit + push)
+ */
 const makeStateRemote = (
   root: string
-) =>
+): Effect.Effect<string, CommandFailedError | PlatformError, Path.Path | CommandExecutor.CommandExecutor> =>
   Effect.gen(function*(_) {
     const path = yield* _(Path.Path)
     const remotePath = path.join(root, "remote.git")
@@ -178,11 +211,24 @@ const makeStateRemote = (
     return remotePath
   })
 
+/**
+ * Clones a seeded state remote into a target directory.
+ *
+ * @param root - Working directory for the clone command.
+ * @param remoteUrl - Remote repository URL or path.
+ * @param target - Target clone directory.
+ * @returns Effect that yields captured git stdout or fails with a typed command/platform error.
+ *
+ * @pure false
+ * @effect CommandExecutor service for git process execution
+ * @complexity O(1) process spawn plus O(repository size)
+ */
 const cloneStateRemote = (
   root: string,
   remoteUrl: string,
   target: string
-) => runGit(root, ["clone", remoteUrl, target])
+): Effect.Effect<string, CommandFailedError | PlatformError, CommandExecutor.CommandExecutor> =>
+  runGit(root, ["clone", remoteUrl, target])
 
 describe("projects service", () => {
   it.effect("seeds host SSH keys into the controller managed authorized_keys file", () =>

packages/app/tests/docker-git/gridland-react-singleton.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, it } from "@effect/vitest"
+import { Effect } from "effect"
 
 import rootPackage from "../../../../package.json" with { type: "json" }
 import appPackage from "../../package.json" with { type: "json" }
 
 describe("Gridland React singleton contract", () => {
-  it("pins React across workspace dependencies for the Gridland renderer", () => {
-    expect(rootPackage.overrides.react).toBe(appPackage.dependencies.react.replace(/^\^/u, ""))
-  })
+  it.effect("pins React across workspace dependencies for the Gridland renderer", () =>
+    Effect.sync(() => {
+      expect(rootPackage.overrides.react).toBe(appPackage.dependencies.react.replace(/^\^/u, ""))
+    }))
 })