fix(api): refresh state before project inventory reads

Serialize state repository git operations with a process-local lock.

Add regression coverage for remote inventory refresh, disabled auto-pull, mixed web/shell output directories, and health projectsRoot reporting.

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(cwd)
+        const projectsRoot = defaultProjectsRoot(process.cwd())
         return yield* _(jsonResponse({ ok: true, revision: controllerRevision, cwd, projectsRoot }, 200))
       }).pipe(Effect.catchAll(errorResponse))
     ),

packages/api/src/services/project-port-proxy.ts

@@ -4,13 +4,13 @@ import * as HttpServerRequest from "@effect/platform/HttpServerRequest"
 import * as HttpServerError from "@effect/platform/HttpServerError"
 import * as HttpServerResponse from "@effect/platform/HttpServerResponse"
 import type { PlatformError } from "@effect/platform/Error"
+import { listProjectItems } from "@effect-template/lib"
 import type { ListProjectsContext } from "@effect-template/lib/usecases/projects-list"
 import { Effect } from "effect"
 import * as Stream from "effect/Stream"
 
 import { ApiBadRequestError, ApiConflictError, ApiInternalError, ApiNotFoundError } from "../api/errors.js"
 import { listProjectPortForwards } from "./project-port-forwards.js"
-import { listProjects } from "./projects.js"
 import {
   normalizeForwardedPrefix,
   parseLinuxDefaultGatewayIp,
@@ -134,21 +134,21 @@ const fetchUpstream = (
 
 const resolveProxyProjectId = (
   target: ProjectPortProxyPath
-): Effect.Effect<string, ApiConflictError | ApiNotFoundError, ListProjectsContext> => {
+): Effect.Effect<string, ApiConflictError | ApiNotFoundError | PlatformError, ListProjectsContext> => {
   if (target._tag === "ProjectId") {
     return Effect.succeed(target.projectId)
   }
 
   return Effect.gen(function*(_) {
-    const projects = yield* _(listProjects())
-    const matches = projects.filter((project) => projectShortKey(project.id) === target.projectKey)
+    const projects = yield* _(listProjectItems)
+    const matches = projects.filter((project) => projectShortKey(project.projectDir) === target.projectKey)
     if (matches.length === 0) {
       return yield* _(Effect.fail(new ApiNotFoundError({ message: `Project key not found: ${target.projectKey}` })))
     }
     if (matches.length > 1) {
       return yield* _(Effect.fail(new ApiConflictError({ message: `Project key is ambiguous: ${target.projectKey}` })))
     }
-    return matches[0]!.id
+    return matches[0]!.projectDir
   })
 }
 

packages/api/src/services/projects.ts

@@ -20,6 +20,7 @@ import { runCommandCapture } from "@effect-template/lib/shell/command-runner"
 import { CommandFailedError } from "@effect-template/lib/shell/errors"
 import { defaultProjectsRoot, resolvePathFromCwd } from "@effect-template/lib/usecases/path-helpers"
 import { deleteDockerGitProject } from "@effect-template/lib/usecases/projects"
+import { autoPullState } from "@effect-template/lib/usecases/state-repo"
 import type { RawOptions } from "@effect-template/lib/core/command-options"
 import type { CreateCommand as LibCreateCommand } from "@effect-template/lib/core/domain"
 import type { ProjectItem } from "@effect-template/lib/usecases/projects"
@@ -216,6 +217,43 @@ const toProjectDetails = (
 
 const dbProjectDetails = (project: ProjectItem): ProjectDetails => toProjectDetails(project, dbProjectSummary(project))
 
+const toProjectInventoryReadError = (error: unknown): ApiInternalError =>
+  new ApiInternalError({
+    message: `Failed to read docker-git project inventory: ${String(error)}`,
+    cause: error
+  })
+
+/**
+ * Refreshes controller project inventory from the shared state repository.
+ *
+ * @returns Effect that completes after best-effort state auto-pull.
+ *
+ * @pure false
+ * @effect FileSystem, Path, CommandExecutor through autoPullState.
+ * @invariant Respects DOCKER_GIT_STATE_AUTO_PULL=false and never fails.
+ * @precondition Controller state root may or may not be a git repository.
+ * @postcondition If auto-pull is enabled and succeeds, local inventory includes latest remote state.
+ * @complexity O(1) git remote round-trip when enabled.
+ * @throws Never - failures are logged by autoPullState.
+ */
+// CHANGE: refresh shared state before project inventory reads
+// WHY: shell and web both read `/projects`; stale controller state caused issue #372
+// QUOTE(ТЗ): "project not synchronized"
+// REF: issue-372
+// SOURCE: https://github.com/ProverCoderAI/docker-git/issues/372
+// FORMAT THEOREM: remote_has(p) and pull_enabled -> p in inventory_after_refresh
+// PURITY: SHELL
+// EFFECT: Effect<void, never, FileSystem | Path | CommandExecutor>
+// INVARIANT: refresh failure cannot masquerade as an empty project list
+// COMPLEXITY: O(git pull)
+export const refreshProjectStateForInventory = () => autoPullState
+
+const readProjectItemsForInventory = () =>
+  refreshProjectStateForInventory().pipe(
+    Effect.zipRight(listProjectItems),
+    Effect.mapError(toProjectInventoryReadError)
+  )
+
 const runtimeProjectDetails = (project: ProjectItem) =>
   Effect.gen(function*(_) {
     const runtimeByProject = yield* _(loadProjectRuntimeByProject([project]))
@@ -255,7 +293,7 @@ const findProjectById = (projectId: string) =>
   Effect.gen(function*(_) {
     const path = yield* _(Path.Path)
     const aliases = projectIdAliases(path, projectId)
-    const projects = yield* _(listProjectItems)
+    const projects = yield* _(readProjectItemsForInventory())
     const project = projects.find((item) => item.projectDir === projectId)
       ?? projects.find((item) => aliases.has(item.projectDir) || aliases.has(path.resolve(item.projectDir)))
     if (project) {
@@ -268,7 +306,7 @@ export const getProjectItemById = (projectId: string) => findProjectById(project
 
 const findProjectByKey = (projectKey: string) =>
   Effect.gen(function*(_) {
-    const projects = yield* _(listProjectItems)
+    const projects = yield* _(readProjectItemsForInventory())
     const matches = projects.filter((item) => projectShortKey(item.projectDir) === projectKey)
     if (matches.length === 0) {
       return yield* _(Effect.fail(new ApiNotFoundError({ message: `Project key not found: ${projectKey}` })))
@@ -587,9 +625,8 @@ const startCreateProjectJob = (
   })
 
 export const listProjects = () =>
-  listProjectItems.pipe(
-    Effect.map((projects) => projects.map((project) => dbProjectSummary(project))),
-    Effect.catchAll(() => Effect.succeed([] as ReadonlyArray<ProjectSummary>))
+  readProjectItemsForInventory().pipe(
+    Effect.map((projects) => projects.map((project) => dbProjectSummary(project)))
   )
 
 export const applyAllProjects = (activeOnly: boolean) =>
@@ -650,6 +687,7 @@ export const createProjectFromRequest = (
   request: CreateProjectRequest
 ) =>
   Effect.gen(function*(_) {
+    yield* _(refreshProjectStateForInventory())
     const prepared = yield* _(prepareCreateProjectRequest(request).pipe(Effect.mapError(toProjectApiError)))
     if (request.async === true) {
       return yield* _(startCreateProjectJob(prepared))

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

@@ -1,8 +1,12 @@
 import * as HttpApp from "@effect/platform/HttpApp"
 import * as HttpRouter from "@effect/platform/HttpRouter"
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Path from "@effect/platform/Path"
+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 * as Scope from "effect/Scope"
 
 import { makeRouter } from "../src/http.js"
 
@@ -16,6 +20,57 @@ const requestApiRoute = (path: string) =>
     catch: (cause) => new Error(String(cause))
   })
 
+const withTempDir = <A, E, R>(
+  use: (tempDir: string) => Effect.Effect<A, E, R>
+): Effect.Effect<A, E | PlatformError, FileSystem.FileSystem | Exclude<R, Scope.Scope>> =>
+  Effect.scoped(
+    Effect.gen(function*(_) {
+      const fs = yield* _(FileSystem.FileSystem)
+      const tempDir = yield* _(
+        fs.makeTempDirectoryScoped({
+          prefix: "docker-git-api-routes-"
+        })
+      )
+      return yield* _(use(tempDir))
+    })
+  )
+
+const withEnvVar = <A, E, R>(
+  key: string,
+  value: string | undefined,
+  effect: Effect.Effect<A, E, R>
+): Effect.Effect<A, E, R> =>
+  Effect.scoped(
+    Effect.acquireRelease(
+      Effect.sync(() => {
+        const previous = process.env[key]
+        if (value === undefined) {
+          delete process.env[key]
+        } else {
+          process.env[key] = value
+        }
+        return previous
+      }),
+      (previous) =>
+        Effect.sync(() => {
+          if (previous === undefined) {
+            delete process.env[key]
+          } else {
+            process.env[key] = previous
+          }
+        })
+    ).pipe(Effect.flatMap(() => effect))
+  )
+
+const readResponseJson = (response: Response) =>
+  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
+
 describe("api console routes", () => {
   it.effect("does not serve the legacy built-in API console", () =>
     Effect.gen(function*(_) {
@@ -26,4 +81,21 @@ describe("api console routes", () => {
         expect(response.status).toBe(404)
       }
     }))
+
+  it.effect("reports the same configured projects root used by inventory reads", () =>
+    withTempDir((root) =>
+      Effect.gen(function*(_) {
+        const path = yield* _(Path.Path)
+        const projectsRoot = path.join(root, ".docker-git")
+        const response = yield* _(
+          withEnvVar("DOCKER_GIT_PROJECTS_ROOT", projectsRoot, requestApiRoute("/health"))
+        )
+        const payload = yield* _(readResponseJson(response))
+        const objectPayload = objectOrNull(payload)
+
+        expect(response.status).toBe(200)
+        expect(objectPayload).not.toBeNull()
+        expect(Reflect.get(objectPayload ?? {}, "projectsRoot")).toBe(projectsRoot)
+      })
+    ).pipe(Effect.provide(NodeContext.layer)))
 })