fix(effect): align API and session-sync compliance boundaries

- add API and session-sync lint:effect gates and wire them into the root script
- decode session-sync boundary payloads with schemas and run the CLI entrypoint through Effect NodeRuntime
- move API agent snapshot persistence and terminal persistence queue toward Effect/platform primitives
- keep command builder core pure by passing clonedOnHostname explicitly

Proof of fix:
- rtk bun run lint
- rtk bun run typecheck
- rtk bun run --cwd packages/api typecheck
- rtk bun run --cwd packages/api lint
- rtk bun run test
- rtk bun run --cwd packages/api test
- rtk bun run lint:effect

Author: skulidropek

bun.lock

@@ -46,7 +46,7 @@
     "web:serve": "bun run --cwd packages/app serve:web",
     "lint": "bun run --filter @prover-coder-ai/docker-git-terminal lint && bun run --filter @prover-coder-ai/docker-git lint && bun run --filter @effect-template/lib lint",
     "lint:tests": "bun run --filter @prover-coder-ai/docker-git lint:tests",
-    "lint:effect": "bun run --filter @prover-coder-ai/docker-git-terminal lint:effect && bun run --filter @prover-coder-ai/docker-git lint:effect && bun run --filter @effect-template/lib lint:effect",
+    "lint:effect": "bun run --filter @prover-coder-ai/docker-git-session-sync lint:effect && bun run --filter @prover-coder-ai/docker-git-terminal lint:effect && bun run --filter @prover-coder-ai/docker-git lint:effect && bun run --filter @prover-coder-ai/docker-git-container lint:effect && bun run --filter @effect-template/lib lint:effect && bun run --filter @effect-template/api lint:effect",
     "test": "bun run --filter @prover-coder-ai/docker-git-session-sync test && bun run --filter @prover-coder-ai/docker-git-terminal test && bun run --filter @prover-coder-ai/docker-git test && bun run --filter @effect-template/lib test",
     "typecheck": "bun run --filter @prover-coder-ai/docker-git-session-sync typecheck && bun run --filter @prover-coder-ai/docker-git-terminal typecheck && bun run --filter @prover-coder-ai/docker-git typecheck && bun run --filter @effect-template/lib typecheck",
     "start": "bun run --cwd packages/app build:docker-git && bun ./packages/app/dist/src/docker-git/main.js"

package.json

@@ -0,0 +1,78 @@
+// CHANGE: add API-local Effect-TS compliance lint profile.
+// WHY: expose Effect migration blockers in the API package, which previously only ran baseline ESLint.
+// QUOTE(TZ): "packages/api не защищён lint:effect"
+// REF: user-request-2026-06-17-effect-compliance-api
+// SOURCE: n/a
+// FORMAT THEOREM: lint(api) = hard unsafe bypass errors + visible Effect migration blockers
+// PURITY: SHELL
+// EFFECT: eslint config
+// INVARIANT: config does not alter runtime behavior.
+// COMPLEXITY: O(1)/O(1)
+import eslintComments from "@eslint-community/eslint-plugin-eslint-comments"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+const migrationBlockers = [
+  {
+    selector: "SwitchStatement",
+    message: "Effect migration blocker: use Match.exhaustive instead of switch."
+  },
+  {
+    selector: "TryStatement",
+    message: "Effect migration blocker: use Effect.try / Effect.catch* instead of try/catch."
+  },
+  {
+    selector: "AwaitExpression",
+    message: "Effect migration blocker: use Effect.gen / Effect.flatMap instead of await."
+  },
+  {
+    selector: "FunctionDeclaration[async=true], FunctionExpression[async=true], ArrowFunctionExpression[async=true]",
+    message: "Effect migration blocker: use Effect.gen / Effect.tryPromise instead of async functions."
+  },
+  {
+    selector: "NewExpression[callee.name='Promise']",
+    message: "Effect migration blocker: use Effect.async / Effect.tryPromise instead of new Promise."
+  },
+  {
+    selector: "CallExpression[callee.object.name='Promise']",
+    message: "Effect migration blocker: use Effect combinators instead of Promise.*."
+  }
+]
+
+export default tseslint.config({
+  name: "api-effect-ts-compliance",
+  files: ["src/**/*.ts", "tests/**/*.ts"],
+  languageOptions: {
+    parser: tseslint.parser,
+    globals: { ...globals.node }
+  },
+  plugins: {
+    "@typescript-eslint": tseslint.plugin,
+    "eslint-comments": eslintComments
+  },
+  rules: {
+    "@typescript-eslint/ban-ts-comment": ["error", {
+      "ts-check": false,
+      "ts-expect-error": true,
+      "ts-ignore": true,
+      "ts-nocheck": true
+    }],
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-restricted-types": ["warn", {
+      types: {
+        Promise: {
+          message: "Avoid Promise in public types. Use Effect.Effect<A, E, R>."
+        },
+        "Promise<*>": {
+          message: "Avoid Promise<T>. Use Effect.Effect<T, E, R>."
+        }
+      }
+    }],
+    "eslint-comments/disable-enable-pair": "error",
+    "eslint-comments/no-unlimited-disable": "error",
+    "eslint-comments/no-unused-disable": "error",
+    "eslint-comments/no-use": "error",
+    "no-console": "error",
+    "no-restricted-syntax": ["warn", ...migrationBlockers]
+  }
+})

packages/api/eslint.effect-ts-check.config.mjs

@@ -15,6 +15,7 @@
     "pretypecheck": "bun run --cwd ../terminal build && bun run --cwd ../container build && bun run --cwd ../lib build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "lint": "eslint .",
+    "lint:effect": "eslint --config eslint.effect-ts-check.config.mjs .",
     "pretest": "bun run --cwd ../terminal build && bun run --cwd ../container build && bun run --cwd ../lib build",
     "test": "vitest run"
   },
@@ -41,6 +42,7 @@
   "homepage": "https://github.com/ProverCoderAI/docker-git#readme",
   "devDependencies": {
     "@effect/vitest": "^0.29.0",
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.7.2",
     "@eslint/js": "10.0.1",
     "@types/node": "^25.9.3",
     "@types/ws": "^8.18.1",
@@ -50,6 +52,7 @@
     "fast-check": "4.8.0",
     "globals": "^17.6.0",
     "typescript": "^6.0.3",
+    "typescript-eslint": "^8.61.1",
     "vitest": "^4.1.9"
   }
 }

packages/api/package.json

@@ -480,6 +480,7 @@ export type CreateProjectRequest = {
   readonly forceEnv?: boolean | undefined
   readonly waitForClone?: boolean | undefined
   readonly async?: boolean | undefined
+  readonly clonedOnHostname?: string | undefined
 }
 
 export type AgentEnvVar = {

packages/api/src/api/contracts.ts

@@ -51,7 +51,8 @@ export const CreateProjectRequestSchema = Schema.Struct({
   force: OptionalBoolean,
   forceEnv: OptionalBoolean,
   waitForClone: OptionalBoolean,
-  async: OptionalBoolean
+  async: OptionalBoolean,
+  clonedOnHostname: OptionalString
 })
 
 export const GithubAuthLoginRequestSchema = Schema.Struct({

packages/api/src/api/schema.ts

@@ -2,19 +2,23 @@ import { recordProjectRuntimeActivity } from "@effect-template/lib"
 import { runCommandWithExitCodes } from "@effect-template/lib/shell/command-runner"
 import { CommandFailedError } from "@effect-template/lib/shell/errors"
 import { defaultProjectsRoot } from "@effect-template/lib/usecases/path-helpers"
+import type { PlatformError } from "@effect/platform/Error"
+import * as FileSystem from "@effect/platform/FileSystem"
 import { NodeContext } from "@effect/platform-node"
-import { Effect } from "effect"
+import { Effect, Either } from "effect"
+import * as ParseResult from "effect/ParseResult"
+import * as Schema from "effect/Schema"
 import { spawn, type ChildProcess } from "node:child_process"
 import { randomUUID } from "node:crypto"
-import { promises as fs } from "node:fs"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 
 import type {
   AgentLogLine,
   AgentSession,
   CreateAgentRequest,
   ProjectDetails
 } from "../api/contracts.js"
+import { AgentSessionSchema } from "../api/schema.js"
 import { ApiBadRequestError, ApiConflictError, ApiNotFoundError } from "../api/errors.js"
 import { emitProjectEvent } from "./events.js"
 
@@ -31,11 +35,28 @@ type SnapshotFile = {
   readonly sessions: ReadonlyArray<AgentSession>
 }
 
+const SnapshotFileSchema = Schema.Struct({
+  sessions: Schema.Array(AgentSessionSchema)
+})
+
+const SnapshotFileJsonSchema = Schema.parseJson(SnapshotFileSchema)
+
 const records: Map<string, AgentRecord> = new Map()
 const projectIndex: Map<string, Set<string>> = new Map()
 const maxLogLines = 5000
 let initialized = false
 
+export const clearAgentRuntimeForTest = (): void => {
+  for (const record of records.values()) {
+    if (record.process !== null && !record.process.killed) {
+      record.process.kill("SIGTERM")
+    }
+  }
+  records.clear()
+  projectIndex.clear()
+  initialized = false
+}
+
 const nowIso = (): string => new Date().toISOString()
 
 const stateFilePath = (): string =>
@@ -184,19 +205,32 @@ export const buildAgentDockerExecArgs = (
 const trimLogs = (logs: Array<AgentLogLine>): Array<AgentLogLine> =>
   logs.length <= maxLogLines ? logs : logs.slice(logs.length - maxLogLines)
 
-const persistSnapshot = async (): Promise<void> => {
-  const filePath = stateFilePath()
-  await fs.mkdir(join(filePath, ".."), { recursive: true })
-  const payload: SnapshotFile = {
-    sessions: [...records.values()].map((record) => record.session)
-  }
-  await fs.writeFile(filePath, JSON.stringify(payload, null, 2), "utf8")
-}
+const emptySnapshotFile = (): SnapshotFile => ({
+  sessions: []
+})
 
-const persistSnapshotBestEffort = (): void => {
-  void persistSnapshot().catch(() => {
-    // best effort snapshot persistence
+const decodeSnapshotFile = (input: string): SnapshotFile | null =>
+  Either.match(ParseResult.decodeUnknownEither(SnapshotFileJsonSchema)(input), {
+    onLeft: () => null,
+    onRight: (value) => value
   })
+
+const persistSnapshot = (): Effect.Effect<void, PlatformError, FileSystem.FileSystem> =>
+  Effect.gen(function*(_) {
+    const fs = yield* _(FileSystem.FileSystem)
+    const filePath = stateFilePath()
+    const payload: SnapshotFile = {
+      sessions: [...records.values()].map((record) => record.session)
+    }
+    yield* _(fs.makeDirectory(dirname(filePath), { recursive: true }))
+    yield* _(fs.writeFileString(filePath, `${JSON.stringify(payload, null, 2)}\n`))
+  })
+
+const persistSnapshotBestEffort = (): void => {
+  Effect.runFork(persistSnapshot().pipe(
+    Effect.provide(NodeContext.layer),
+    Effect.catchAll(() => Effect.void)
+  ))
 }
 
 const recordAgentActivityBestEffort = (projectId: string): void => {
@@ -321,50 +355,61 @@ const killAgentScript = (sessionId: string): string => {
   ].join("\n")
 }
 
-const hydrateFromSnapshot = async (): Promise<void> => {
-  const filePath = stateFilePath()
-  const exists = await fs.stat(filePath).then(() => true).catch(() => false)
-  if (!exists) {
-    return
-  }
-
-  const raw = await fs.readFile(filePath, "utf8")
-  const parsed = JSON.parse(raw) as SnapshotFile
-  for (const session of parsed.sessions ?? []) {
-    const restored: AgentSession = {
-      ...session,
-      status: endedStatuses.has(session.status) ? session.status : "exited",
-      hostPid: null,
-      stoppedAt: session.stoppedAt ?? nowIso(),
-      updatedAt: nowIso()
+const readSnapshotFile = (): Effect.Effect<SnapshotFile, never, FileSystem.FileSystem> =>
+  Effect.gen(function*(_) {
+    const fs = yield* _(FileSystem.FileSystem)
+    const filePath = stateFilePath()
+    const exists = yield* _(Effect.either(fs.exists(filePath)))
+    const fileExists = Either.match(exists, {
+      onLeft: () => false,
+      onRight: (value) => value
+    })
+    if (!fileExists) {
+      return emptySnapshotFile()
     }
+    const contents = yield* _(Effect.either(fs.readFileString(filePath)))
+    return Either.match(contents, {
+      onLeft: () => emptySnapshotFile(),
+      onRight: (value) => decodeSnapshotFile(value) ?? emptySnapshotFile()
+    })
+  }).pipe(Effect.catchAll(() => Effect.succeed(emptySnapshotFile())))
 
-    const record: AgentRecord = {
-      session: restored,
-      projectDir: "",
-      logs: [],
-      process: null,
-      stdoutRemainder: "",
-      stderrRemainder: ""
-    }
+const hydrateFromSnapshot = (): Effect.Effect<void, never, FileSystem.FileSystem> =>
+  Effect.gen(function*(_) {
+    const parsed = yield* _(readSnapshotFile())
+    for (const session of parsed.sessions) {
+      const restored: AgentSession = {
+        ...session,
+        status: endedStatuses.has(session.status) ? session.status : "exited",
+        hostPid: null,
+        stoppedAt: session.stoppedAt ?? nowIso(),
+        updatedAt: nowIso()
+      }
 
-    records.set(restored.id, record)
-    upsertProjectIndex(restored.projectId, restored.id)
-  }
-}
+      const record: AgentRecord = {
+        session: restored,
+        projectDir: "",
+        logs: [],
+        process: null,
+        stdoutRemainder: "",
+        stderrRemainder: ""
+      }
+
+      records.set(restored.id, record)
+      upsertProjectIndex(restored.projectId, restored.id)
+    }
+  })
 
 export const initializeAgentState = () =>
-  Effect.tryPromise({
-    try: async () => {
-      if (initialized) {
-        return
-      }
-      await hydrateFromSnapshot()
-      initialized = true
-    },
-    catch: (error) => new Error(String(error))
+  Effect.gen(function*(_) {
+    if (initialized) {
+      return
+    }
+    yield* _(hydrateFromSnapshot())
+    initialized = true
   }).pipe(
     Effect.catchAll(() => Effect.void),
+    Effect.provide(NodeContext.layer),
     Effect.asVoid
   )