@prover-coder-ai/context-doc 1.0.11 → 1.0.13

package/src/shell/services/file-system.ts

@@ -0,0 +1,142 @@
+import * as FileSystem from "@effect/platform/FileSystem"
+import * as Path from "@effect/platform/Path"
+import { Context, Effect, Layer, pipe } from "effect"
+
+import { type SyncError, syncError } from "../sync/types.js"
+
+export type DirectoryEntryKind = "file" | "directory" | "other"
+
+export interface DirectoryEntry {
+  readonly name: string
+  readonly path: string
+  readonly kind: DirectoryEntryKind
+}
+
+export class FileSystemService extends Context.Tag("FileSystemService")<
+  FileSystemService,
+  {
+    readonly readFileString: (pathValue: string) => Effect.Effect<string, SyncError>
+    readonly readDirectory: (
+      pathValue: string
+    ) => Effect.Effect<ReadonlyArray<DirectoryEntry>, SyncError>
+    readonly makeDirectory: (pathValue: string) => Effect.Effect<void, SyncError>
+    readonly copyFile: (
+      sourcePath: string,
+      destinationPath: string
+    ) => Effect.Effect<void, SyncError>
+    readonly exists: (pathValue: string) => Effect.Effect<boolean, SyncError>
+  }
+>() {}
+
+const forEach = Effect.forEach
+
+const resolveEntryPath = (
+  path: Path.Path,
+  root: string,
+  entry: string
+): string => (path.isAbsolute(entry) ? entry : path.join(root, entry))
+
+const entryKindFromInfo = (
+  info: FileSystem.File.Info
+): DirectoryEntryKind => {
+  if (info.type === "Directory") {
+    return "directory"
+  }
+  if (info.type === "File") {
+    return "file"
+  }
+  return "other"
+}
+
+const toDirectoryEntry = (
+  path: Path.Path,
+  entryPath: string,
+  info: FileSystem.File.Info
+): DirectoryEntry => ({
+  name: path.basename(entryPath),
+  path: entryPath,
+  kind: entryKindFromInfo(info)
+})
+
+const readEntry = (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  entryPath: string
+): Effect.Effect<DirectoryEntry, SyncError> =>
+  pipe(
+    fs.stat(entryPath),
+    Effect.map((info) => toDirectoryEntry(path, entryPath, info)),
+    Effect.mapError(() => syncError(entryPath, "Cannot read directory entry"))
+  )
+
+const resolveEntry = (
+  fs: FileSystem.FileSystem,
+  path: Path.Path,
+  root: string,
+  entry: string
+): Effect.Effect<DirectoryEntry, SyncError> => {
+  const entryPath = resolveEntryPath(path, root, entry)
+  return readEntry(fs, path, entryPath)
+}
+
+// CHANGE: wrap filesystem access behind a service for typed errors and testing
+// WHY: enforce shell boundary and avoid raw fs usage in logic
+// QUOTE(TZ): "Внешние зависимости: только через типизированные интерфейсы"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall p: exists(p) -> readable(p)
+// PURITY: SHELL
+// EFFECT: Effect<FileSystemService, SyncError, never>
+// INVARIANT: readDirectory returns absolute entry paths
+// COMPLEXITY: O(n)/O(n)
+export const FileSystemLive = Layer.effect(
+  FileSystemService,
+  Effect.gen(function*(_) {
+    const fs = yield* _(FileSystem.FileSystem)
+    const path = yield* _(Path.Path)
+
+    const readFileString = (pathValue: string): Effect.Effect<string, SyncError> =>
+      pipe(
+        fs.readFileString(pathValue, "utf8"),
+        Effect.mapError(() => syncError(pathValue, "Cannot read file"))
+      )
+
+    const readDirectory = (
+      pathValue: string
+    ): Effect.Effect<ReadonlyArray<DirectoryEntry>, SyncError> =>
+      pipe(
+        fs.readDirectory(pathValue),
+        Effect.mapError(() => syncError(pathValue, "Cannot read directory")),
+        Effect.flatMap((entries) => forEach(entries, (entry) => resolveEntry(fs, path, pathValue, entry)))
+      )
+
+    const makeDirectory = (pathValue: string): Effect.Effect<void, SyncError> =>
+      pipe(
+        fs.makeDirectory(pathValue, { recursive: true }),
+        Effect.mapError(() => syncError(pathValue, "Cannot create destination directory structure"))
+      )
+
+    const copyFile = (
+      sourcePath: string,
+      destinationPath: string
+    ): Effect.Effect<void, SyncError> =>
+      pipe(
+        fs.copyFile(sourcePath, destinationPath),
+        Effect.mapError(() => syncError(sourcePath, "Cannot copy file into destination"))
+      )
+
+    const exists = (pathValue: string): Effect.Effect<boolean, SyncError> =>
+      pipe(
+        fs.exists(pathValue),
+        Effect.mapError(() => syncError(pathValue, "Cannot check path existence"))
+      )
+
+    return {
+      readFileString,
+      readDirectory,
+      makeDirectory,
+      copyFile,
+      exists
+    }
+  })
+)

package/src/shell/services/runtime-env.ts

@@ -0,0 +1,54 @@
+import { Context, Effect, Layer, Option } from "effect"
+
+export class RuntimeEnv extends Context.Tag("RuntimeEnv")<
+  RuntimeEnv,
+  {
+    readonly argv: Effect.Effect<ReadonlyArray<string>>
+    readonly cwd: Effect.Effect<string>
+    readonly homedir: Effect.Effect<string>
+    readonly envVar: (key: string) => Effect.Effect<Option.Option<string>>
+  }
+>() {}
+
+const readProcess = (): NodeJS.Process | undefined => typeof process === "undefined" ? undefined : process
+
+const readEnv = (): NodeJS.ProcessEnv => readProcess()?.env ?? {}
+
+const resolveHomeDir = (env: NodeJS.ProcessEnv, cwdFallback: string): string => {
+  const direct = env["HOME"] ?? env["USERPROFILE"]
+  if (direct !== undefined) {
+    return direct
+  }
+
+  const drive = env["HOMEDRIVE"]
+  const path = env["HOMEPATH"]
+  if (drive !== undefined && path !== undefined) {
+    return `${drive}${path}`
+  }
+
+  return cwdFallback
+}
+
+// CHANGE: wrap process/os access behind a typed Effect service
+// WHY: keep shell dependencies injectable and testable
+// QUOTE(TZ): "Внешние зависимости: только через типизированные интерфейсы"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall k: env(k) -> Option<string>
+// PURITY: SHELL
+// EFFECT: Effect<RuntimeEnv, never, never>
+// INVARIANT: argv/cwd/homedir are read once per effect
+// COMPLEXITY: O(1)/O(1)
+export const RuntimeEnvLive = Layer.succeed(RuntimeEnv, {
+  argv: Effect.sync(() => {
+    const proc = readProcess()
+    return proc === undefined ? [] : [...proc.argv]
+  }),
+  cwd: Effect.sync(() => readProcess()?.cwd() ?? "."),
+  homedir: Effect.sync(() => {
+    const proc = readProcess()
+    const cwdFallback = proc?.cwd() ?? "."
+    return resolveHomeDir(readEnv(), cwdFallback)
+  }),
+  envVar: (key) => Effect.sync(() => Option.fromNullable(readEnv()[key]))
+})

package/src/shell/sync/index.ts

@@ -0,0 +1,35 @@
+import type * as Path from "@effect/platform/Path"
+import { Effect } from "effect"
+
+import type { CryptoService } from "../services/crypto.js"
+import type { FileSystemService } from "../services/file-system.js"
+import type { RuntimeEnv } from "../services/runtime-env.js"
+import { syncClaude } from "./sources/claude.js"
+import { syncCodex } from "./sources/codex.js"
+import { syncQwen } from "./sources/qwen.js"
+import type { SyncOptions } from "./types.js"
+
+type SyncProgramEnv = RuntimeEnv | FileSystemService | CryptoService | Path.Path
+
+// CHANGE: compose multi-source sync into a single Effect program
+// WHY: centralize orchestration while keeping each source isolated
+// QUOTE(TZ): "монодическая композиция"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall s in Sources: run(s) -> synced(s)
+// PURITY: SHELL
+// EFFECT: Effect<void, never, FileSystemService | RuntimeEnv | CryptoService | Path>
+// INVARIANT: sources run sequentially in fixed order
+// COMPLEXITY: O(n)/O(n)
+export const buildSyncProgram = (
+  options: SyncOptions
+): Effect.Effect<
+  void,
+  never,
+  SyncProgramEnv
+> =>
+  Effect.gen(function*(_) {
+    yield* _(syncClaude(options))
+    yield* _(syncCodex(options))
+    yield* _(syncQwen(options))
+  })

package/src/shell/sync/shared.ts

@@ -0,0 +1,229 @@
+import * as Path from "@effect/platform/Path"
+import { Console, Effect, Match, pipe } from "effect"
+
+import { type DirectoryEntry, FileSystemService } from "../services/file-system.js"
+import { type SyncError, syncError, type SyncOptions, type SyncSource } from "./types.js"
+
+const forEach = Effect.forEach
+
+type FilteredSourceEnv<R> = R | FileSystemService | Path.Path
+
+const ensureDirectory = (
+  directory: string
+): Effect.Effect<void, SyncError, FileSystemService> =>
+  Effect.gen(function*(_) {
+    const fs = yield* _(FileSystemService)
+    yield* _(fs.makeDirectory(directory))
+  })
+
+// CHANGE: expose recursive traversal for callers that filter by entry
+// WHY: reuse traversal logic across sources without duplicating Match logic
+// QUOTE(TZ): "минимальный корректный diff"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall f: collectFiles(root, p) -> p(f) => exists(f)
+// PURITY: SHELL
+// EFFECT: Effect<ReadonlyArray<string>, SyncError, FileSystemService>
+// INVARIANT: returned paths are absolute and exist in traversal
+// COMPLEXITY: O(n)/O(n)
+export const collectFiles = (
+  root: string,
+  isRelevant: (entry: DirectoryEntry) => boolean
+): Effect.Effect<ReadonlyArray<string>, SyncError, FileSystemService> =>
+  Effect.gen(function*(_) {
+    const fs = yield* _(FileSystemService)
+    const entries = yield* _(fs.readDirectory(root))
+    const chunks = yield* _(
+      forEach(entries, (entry) =>
+        Match.value(entry.kind).pipe(
+          Match.when("directory", () => collectFiles(entry.path, isRelevant)),
+          Match.when("file", () => isRelevant(entry) ? Effect.succeed([entry.path]) : Effect.succeed([])),
+          Match.when("other", () => Effect.succeed([])),
+          Match.exhaustive
+        ))
+    )
+    return chunks.flat()
+  })
+
+// CHANGE: share relative path copy for multiple sync sources
+// WHY: avoid repeating path math in each source
+// QUOTE(TZ): "SHELL → CORE (but not наоборот)"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall f: copy(f) -> relative(f) preserved
+// PURITY: SHELL
+// EFFECT: Effect<void, SyncError, FileSystemService | Path>
+// INVARIANT: destination preserves source-relative path
+// COMPLEXITY: O(1)/O(1)
+export const copyFilePreservingRelativePath = (
+  sourceRoot: string,
+  destinationRoot: string,
+  filePath: string
+): Effect.Effect<void, SyncError, FileSystemService | Path.Path> =>
+  Effect.gen(function*(_) {
+    const fs = yield* _(FileSystemService)
+    const path = yield* _(Path.Path)
+    const relative = path.relative(sourceRoot, filePath)
+    const targetPath = path.join(destinationRoot, relative)
+    yield* _(fs.makeDirectory(path.dirname(targetPath)))
+    yield* _(fs.copyFile(filePath, targetPath))
+  })
+
+// CHANGE: expose reusable first-match search with effectful predicate
+// WHY: remove duplicated recursive search logic across sources
+// QUOTE(TZ): "минимальный корректный diff"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall c: match(c) -> returns first c
+// PURITY: SHELL
+// EFFECT: Effect<string | undefined, SyncError, R>
+// INVARIANT: result is undefined iff no candidate matches
+// COMPLEXITY: O(n)/O(1)
+export const findFirstMatching = <R>(
+  candidates: ReadonlyArray<string>,
+  matches: (candidate: string) => Effect.Effect<boolean, SyncError, R>
+): Effect.Effect<string | undefined, SyncError, R> => {
+  const loop = (
+    remaining: ReadonlyArray<string>
+  ): Effect.Effect<string | undefined, SyncError, R> =>
+    Effect.gen(function*(_) {
+      const [candidate, ...rest] = remaining
+      if (candidate === undefined) {
+        return
+      }
+      const matched = yield* _(matches(candidate))
+      if (!matched) {
+        return yield* _(loop(rest))
+      }
+      return candidate
+    })
+
+  return loop(candidates)
+}
+
+// CHANGE: ensure destination directory is created through Effect-typed fs
+// WHY: keep IO effects inside SHELL and reuse in sync flows
+// QUOTE(TZ): "SHELL: Все эффекты изолированы в тонкой оболочке"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall d: ensureDirectory(d) -> exists(d)
+// PURITY: SHELL
+// EFFECT: Effect<void, SyncError, FileSystemService>
+// INVARIANT: directory exists after successful effect
+// COMPLEXITY: O(1)/O(1)
+export const ensureDestination = ensureDirectory
+
+// CHANGE: resolve project root for cwd-based matching and destination paths
+// WHY: allow running from sub-packages while targeting the repo root
+// QUOTE(TZ): "передай root-path на основную папку"
+// REF: user-2026-01-19-project-root
+// SOURCE: n/a
+// FORMAT THEOREM: forall o: root(o) = resolve(o.projectRoot ?? o.cwd)
+// PURITY: SHELL
+// EFFECT: n/a
+// INVARIANT: resolved root is absolute
+// COMPLEXITY: O(1)/O(1)
+export const resolveProjectRoot = (
+  path: Path.Path,
+  options: SyncOptions
+): string => path.resolve(options.projectRoot ?? options.cwd)
+
+// CHANGE: copy filtered files with typed errors and deterministic traversal
+// WHY: reuse shared traversal logic for Qwen/Claude syncs
+// QUOTE(TZ): "FUNCTIONAL CORE, IMPERATIVE SHELL"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall f: relevant(f) -> copied(f)
+// PURITY: SHELL
+// EFFECT: Effect<number, SyncError, FileSystemService | Path>
+// INVARIANT: copied count equals length of relevant files
+// COMPLEXITY: O(n)/O(n)
+export const copyFilteredFiles = (
+  sourceRoot: string,
+  destinationRoot: string,
+  isRelevant: (entry: DirectoryEntry, fullPath: string) => boolean,
+  errorReason: string
+): Effect.Effect<number, SyncError, FileSystemService | Path.Path> =>
+  pipe(
+    Effect.gen(function*(_) {
+      const files = yield* _(collectFiles(sourceRoot, (entry) => isRelevant(entry, entry.path)))
+      yield* _(
+        forEach(files, (filePath) => copyFilePreservingRelativePath(sourceRoot, destinationRoot, filePath))
+      )
+      return files.length
+    }),
+    Effect.mapError(() => syncError(sourceRoot, errorReason))
+  )
+
+// CHANGE: build a SyncSource using shared filtered copy logic
+// WHY: eliminate repeated source definitions for file-extension based syncs
+// QUOTE(TZ): "минимальный корректный diff"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall s: createFilteredSource(s) -> copyFilteredFiles(s)
+// PURITY: SHELL
+// EFFECT: Effect<number, SyncError, R>
+// INVARIANT: copy uses shared filter predicate
+// COMPLEXITY: O(n)/O(n)
+export const createFilteredSource = <R>(params: {
+  readonly name: SyncSource<FilteredSourceEnv<R>>["name"]
+  readonly destSubdir: SyncSource<FilteredSourceEnv<R>>["destSubdir"]
+  readonly resolveSource: SyncSource<FilteredSourceEnv<R>>["resolveSource"]
+  readonly filter: (entry: DirectoryEntry, fullPath: string) => boolean
+  readonly errorReason: string
+}): SyncSource<FilteredSourceEnv<R>> => ({
+  name: params.name,
+  destSubdir: params.destSubdir,
+  resolveSource: params.resolveSource,
+  copy: (sourceDir, destinationDir) => copyFilteredFiles(sourceDir, destinationDir, params.filter, params.errorReason)
+})
+
+// CHANGE: standardize per-source sync orchestration with skip-on-error logging
+// WHY: keep the shell thin and consistent for all sources
+// QUOTE(TZ): "SHELL → CORE (but not наоборот)"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall s: runSyncSource(s) -> logs(s)
+// PURITY: SHELL
+// EFFECT: Effect<void, never, FileSystemService | Path>
+// INVARIANT: source==destination implies no copy
+// COMPLEXITY: O(n)/O(n)
+export const runSyncSource = <R>(
+  source: SyncSource<R>,
+  options: SyncOptions
+): Effect.Effect<void, never, R | FileSystemService | Path.Path> =>
+  pipe(
+    Effect.gen(function*(_) {
+      const path = yield* _(Path.Path)
+      const resolvedSource = yield* _(source.resolveSource(options))
+      const destination = path.join(
+        resolveProjectRoot(path, options),
+        ".knowledge",
+        source.destSubdir
+      )
+
+      if (path.resolve(resolvedSource) === path.resolve(destination)) {
+        yield* _(
+          Console.log(
+            `${source.name}: source equals destination; skipping copy to avoid duplicates`
+          )
+        )
+        return
+      }
+
+      yield* _(ensureDirectory(destination))
+      const copied = yield* _(source.copy(resolvedSource, destination, options))
+      yield* _(
+        Console.log(
+          `${source.name}: copied ${copied} files from ${resolvedSource} to ${destination}`
+        )
+      )
+    }),
+    Effect.matchEffect({
+      onFailure: (error: SyncError) =>
+        Console.log(
+          `${source.name}: source not found; skipped syncing (${error.reason})`
+        ),
+      onSuccess: () => Effect.void
+    })
+  )

package/src/shell/sync/sources/claude.ts

@@ -0,0 +1,54 @@
+import * as Path from "@effect/platform/Path"
+import { Effect } from "effect"
+
+import { FileSystemService } from "../../services/file-system.js"
+import { RuntimeEnv } from "../../services/runtime-env.js"
+import { createFilteredSource, resolveProjectRoot, runSyncSource } from "../shared.js"
+import { type SyncError, syncError, type SyncOptions, type SyncSource } from "../types.js"
+
+type ClaudeEnv = RuntimeEnv | FileSystemService | Path.Path
+
+const slugFromCwd = (cwd: string): string => `-${cwd.replace(/^\/+/, "").replaceAll("\\", "-").replaceAll("/", "-")}`
+
+const resolveClaudeProjectDir = (
+  options: SyncOptions
+): Effect.Effect<string, SyncError, ClaudeEnv> =>
+  Effect.gen(function*(_) {
+    const env = yield* _(RuntimeEnv)
+    const homeDir = yield* _(env.homedir)
+    const path = yield* _(Path.Path)
+    const base = options.claudeProjectsRoot ??
+      path.join(homeDir, ".claude", "projects")
+    const candidate = path.join(base, slugFromCwd(resolveProjectRoot(path, options)))
+    const fs = yield* _(FileSystemService)
+    const exists = yield* _(fs.exists(candidate))
+    if (!exists) {
+      return yield* _(
+        Effect.fail(syncError(".claude", "Claude project directory is missing"))
+      )
+    }
+
+    return candidate
+  })
+
+const claudeSource: SyncSource<ClaudeEnv> = createFilteredSource({
+  name: "Claude",
+  destSubdir: ".claude",
+  resolveSource: resolveClaudeProjectDir,
+  filter: (entry, fullPath) => entry.kind === "file" && fullPath.endsWith(".jsonl"),
+  errorReason: "Cannot traverse Claude project"
+})
+
+// CHANGE: sync Claude dialog files through shared sync runner
+// WHY: keep Claude-specific path resolution isolated from other sources
+// QUOTE(TZ): "SHELL: Все эффекты (IO, сеть, БД, env/process) изолированы"
+// REF: user-2026-01-19-sync-rewrite
+// SOURCE: n/a
+// FORMAT THEOREM: forall f: jsonl(f) -> copied(f)
+// PURITY: SHELL
+// EFFECT: Effect<void, never, FileSystemService | RuntimeEnv | Path>
+// INVARIANT: only .jsonl files are copied
+// COMPLEXITY: O(n)/O(n)
+export const syncClaude = (
+  options: SyncOptions
+): Effect.Effect<void, never, ClaudeEnv> => runSyncSource(claudeSource, options)