@filen/sync 0.2.1 → 0.3.2

package/tests/unit/tasks-dispatch-order-regression.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, localMutate } from "../harness/runner"
+import { messagesOfType } from "../harness/snapshot"
+import { writeLocal, rmLocal } from "../harness/mutations"
+
+/**
+ * Added regression test pinning the tasks.process dispatch ORDER after the bucketing optimization (the
+ * 12 filter-passes were replaced with a single partition-then-drain). The fixed type order — deletes
+ * before directory creations before uploads — is load-bearing: an upload into a not-yet-created
+ * directory would fail. This drives a mixed one-cycle batch and asserts the completion order, on top of
+ * convergence.
+ *
+ * NEW FILE — does not touch the existing scenario tests.
+ */
+describe("tasks.process — dispatch order preserved by bucketing", () => {
+	it("completes deleteRemoteFile before createRemoteDirectory before uploadFile in one cycle", async () => {
+		const result = await runScenario({
+			name: "dispatch-order",
+			mode: "twoWay",
+			initialLocal: { "/local/old.txt": "old", "/local/keep.txt": "k" },
+			steps: [
+				runCycle(),
+				localMutate(world => {
+					// One cycle that produces a delete, a directory creation, and an upload into it.
+					rmLocal(world, "old.txt")
+					writeLocal(world, "newdir/new.txt", "new-content")
+				}),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		const opCycle = result.cycles[1]!.messages
+		const completions: string[] = messagesOfType(opCycle, "transfer")
+			.filter(message => message.data.type === "success")
+			.map(message => message.data.of)
+
+		const firstIndex = (of: string): number => completions.indexOf(of)
+
+		expect(firstIndex("deleteRemoteFile")).toBeGreaterThanOrEqual(0)
+		expect(firstIndex("createRemoteDirectory")).toBeGreaterThanOrEqual(0)
+		expect(firstIndex("uploadFile")).toBeGreaterThanOrEqual(0)
+
+		// Deletes run before directory creations, which run before uploads.
+		expect(firstIndex("deleteRemoteFile")).toBeLessThan(firstIndex("createRemoteDirectory"))
+		expect(firstIndex("createRemoteDirectory")).toBeLessThan(firstIndex("uploadFile"))
+
+		// And the cycle still converges.
+		expect(result.finalLocal).toEqual(result.finalRemote)
+		expect(result.finalRemote["/newdir/new.txt"]).toMatchObject({ type: "file" })
+		expect(result.finalRemote["/old.txt"]).toBeUndefined()
+	})
+})

package/tests/unit/worker-api.test.ts

@@ -0,0 +1,379 @@
+import { describe, it, expect, vi } from "vitest"
+import { PauseSignal } from "@filen/sdk"
+import SyncWorker from "../../src/index"
+import Sync from "../../src/lib/sync"
+import { promiseAllChunked, promiseAllSettledChunked, isPathSyncedByICloud, pathSyncedByICloud } from "../../src/utils"
+import { type LocalTreeError } from "../../src/lib/filesystems/local"
+import { createWorld, BASE_TIME, DB_ROOT, type CreateWorldOptions, type World } from "../harness/world"
+import { makeErrnoError } from "../fakes/virtual-fs"
+
+/**
+ * Targeted unit tests for the {@link SyncWorker} public control surface in `src/index.ts` and the
+ * remaining uncovered helpers in `src/utils.ts`. The behavioral scenario suite (Category I in
+ * particular) already drives the match/effect paths of the lifecycle methods; this file fills the
+ * gaps: the constructor option handling, the methods the scenarios do not touch
+ * (`resetLocalTreeErrors`, `toggleLocalTrash`, `updateRequireConfirmationOnLargeDeletion`,
+ * `fetchIgnorerContent`), the per-transfer pause-signal fan-out inside `updatePaused`, and the
+ * "unknown uuid / absent Sync" no-op branches shared by the whole control surface.
+ *
+ * World-backed tests run under vitest fake timers (matching {@link createWorld}'s contract); the
+ * pure helper tests do not need them.
+ */
+const FAKE_TIMERS = ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] as const
+
+async function withWorld(options: CreateWorldOptions, body: (world: World) => Promise<void>): Promise<void> {
+	vi.useFakeTimers({ toFake: [...FAKE_TIMERS] })
+	vi.setSystemTime(BASE_TIME)
+
+	try {
+		const world = await createWorld(options)
+
+		await body(world)
+	} finally {
+		vi.useRealTimers()
+	}
+}
+
+/**
+ * Run `fn` with `process.platform` temporarily stubbed (async variant of the helper used in
+ * `n-unit.test.ts`). `process.platform` is non-writable but configurable, so it is replaced via
+ * `defineProperty` and restored from its original descriptor.
+ */
+async function withPlatformAsync(platform: NodeJS.Platform, fn: () => Promise<void>): Promise<void> {
+	const original = Object.getOwnPropertyDescriptor(process, "platform")
+
+	Object.defineProperty(process, "platform", { value: platform, configurable: true })
+
+	try {
+		await fn()
+	} finally {
+		if (original) {
+			Object.defineProperty(process, "platform", original)
+		}
+	}
+}
+
+describe("SyncWorker public API — constructor", () => {
+	it("throws when neither an sdk instance nor an sdkConfig is provided", () => {
+		expect(() => new SyncWorker({ syncPairs: [], dbPath: DB_ROOT })).toThrow(
+			"Either pass a configured SDK instance OR a SDKConfig object."
+		)
+	})
+
+	it("falls back to the default environment, defaults runOnce to false, and tolerates a missing onMessage", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			// No `environment` => defaultEnvironment(); no `onMessage` => the process.onMessage assignment
+			// is skipped; `runOnce` is omitted => defaults to false.
+			const worker = new SyncWorker({
+				syncPairs: [world.syncPair],
+				dbPath: DB_ROOT,
+				sdk: world.cloud.sdk,
+				disableLogging: true
+			})
+
+			expect(worker.runOnce).toBe(false)
+			expect(worker.environment.fs).toBeDefined()
+			expect(worker.environment.globFs).toBeDefined()
+			expect(typeof worker.environment.writeFileAtomic).toBe("function")
+			expect(typeof worker.environment.createWatcher).toBe("function")
+
+			// It registered nothing and started nothing: initialize() was never called.
+			expect(Object.keys(worker.syncs)).toEqual([])
+		})
+	})
+})
+
+describe("SyncWorker public API — updateSyncPairs error handling", () => {
+	it("surfaces and rethrows an initialization failure for a newly registered pair", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			// A brand-new pair (not yet in `syncs`) makes updateSyncPairs construct a Sync and initialize
+			// it. A throwaway Sync over the same pair exposes the exact state directory the real one will
+			// `ensureDir()` during initialize(); failing that fs op makes initialize() reject and forces
+			// updateSyncPairs into its catch/rethrow.
+			const newPair = { ...world.syncPair, uuid: "worker-api-second-pair" }
+			const probe = new Sync({ syncPair: newPair, worker: world.worker })
+
+			world.vfs.controls.setError(probe.state.statePath, makeErrnoError("EACCES", "EACCES: permission denied"))
+
+			await expect(world.worker.updateSyncPairs([newPair])).rejects.toThrow("EACCES")
+		})
+	})
+})
+
+describe("SyncWorker public API — per-pair control methods", () => {
+	it("resetLocalTreeErrors clears the matching pair's local-tree errors and ignores an unknown uuid", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+			const treeError: LocalTreeError = {
+				localPath: `${world.localPath}/broken.txt`,
+				relativePath: "/broken.txt",
+				error: new Error("stat failed"),
+				uuid: "node-uuid"
+			}
+
+			world.sync.localTreeErrors = [treeError]
+
+			// Unknown uuid: the loop `continue`s past the (mismatched) pair, leaving the errors intact.
+			world.worker.resetLocalTreeErrors("not-this-pair")
+			expect(world.sync.localTreeErrors).toEqual([treeError])
+
+			// Matching uuid: the errors are reset to an empty array.
+			world.worker.resetLocalTreeErrors(uuid)
+			expect(world.sync.localTreeErrors).toEqual([])
+		})
+	})
+
+	it("toggleLocalTrash flips localTrashDisabled for the matching pair and ignores an unknown uuid", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			expect(world.sync.localTrashDisabled).toBe(false)
+
+			// Unknown uuid: no change.
+			world.worker.toggleLocalTrash("not-this-pair", true)
+			expect(world.sync.localTrashDisabled).toBe(false)
+
+			// Matching uuid: disable, then re-enable.
+			world.worker.toggleLocalTrash(uuid, true)
+			expect(world.sync.localTrashDisabled).toBe(true)
+
+			world.worker.toggleLocalTrash(uuid, false)
+			expect(world.sync.localTrashDisabled).toBe(false)
+		})
+	})
+
+	it("updateRequireConfirmationOnLargeDeletion toggles the flag for the matching pair and ignores an unknown uuid", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			expect(world.sync.requireConfirmationOnLargeDeletion).toBe(false)
+
+			world.worker.updateRequireConfirmationOnLargeDeletion("not-this-pair", true)
+			expect(world.sync.requireConfirmationOnLargeDeletion).toBe(false)
+
+			world.worker.updateRequireConfirmationOnLargeDeletion(uuid, true)
+			expect(world.sync.requireConfirmationOnLargeDeletion).toBe(true)
+		})
+	})
+
+	it("fetchIgnorerContent returns the matching pair's ignorer content and an empty string for an unknown uuid", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			// Unknown uuid short-circuits to an empty string (no pair matched).
+			expect(await world.worker.fetchIgnorerContent("not-this-pair")).toBe("")
+
+			// After setting the ignorer content it round-trips through the physical .filenignore.
+			await world.worker.updateIgnorerContent(uuid, "node_modules\n*.log")
+			expect(await world.worker.fetchIgnorerContent(uuid)).toBe("node_modules\n*.log")
+		})
+	})
+
+	it("updatePaused pauses and resumes each registered per-transfer signal, skipping ones already in the target state", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+			const running = new PauseSignal()
+			const alreadyPaused = new PauseSignal()
+
+			alreadyPaused.pause()
+
+			world.sync.pauseSignals["upload:/running.txt"] = running
+			world.sync.pauseSignals["upload:/already.txt"] = alreadyPaused
+
+			// Pausing the pair pauses the running signal and leaves the already-paused one untouched.
+			world.worker.updatePaused(uuid, true)
+
+			expect(world.sync.paused).toBe(true)
+			expect(running.isPaused()).toBe(true)
+			expect(alreadyPaused.isPaused()).toBe(true)
+
+			// Add a freshly-registered, still-running signal: the resume pass must resume the paused ones
+			// and skip the running one.
+			const stillRunning = new PauseSignal()
+
+			world.sync.pauseSignals["download:/fresh.txt"] = stillRunning
+
+			world.worker.updatePaused(uuid, false)
+
+			expect(world.sync.paused).toBe(false)
+			expect(running.isPaused()).toBe(false)
+			expect(alreadyPaused.isPaused()).toBe(false)
+			expect(stillRunning.isPaused()).toBe(false)
+		})
+	})
+
+	it("updateRemoved with removed=false clears the removed flag without running cleanup", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			world.sync.removed = true
+
+			const mark = world.messages.length
+
+			await world.worker.updateRemoved(uuid, false)
+
+			expect(world.sync.removed).toBe(false)
+			// The removed=false branch does NOT call cleanup(), so no cycleExited is emitted.
+			expect(world.messages.slice(mark).some(message => message.type === "cycleExited")).toBe(false)
+		})
+	})
+})
+
+describe("SyncWorker public API — unknown uuid / absent Sync no-ops", () => {
+	it("resetCache and resetTaskErrors do nothing for an unknown uuid", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const cacheBefore = world.sync.localFileSystem.getDirectoryTreeCache
+			const timestampBefore = world.sync.localFileSystem.lastDirectoryChangeTimestamp
+			const taskErrorsBefore = world.sync.taskErrors
+
+			world.worker.resetCache("not-this-pair")
+			world.worker.resetTaskErrors("not-this-pair")
+
+			// The mismatched-uuid branch `continue`s without touching any state (same references/values).
+			expect(world.sync.localFileSystem.getDirectoryTreeCache).toBe(cacheBefore)
+			expect(world.sync.localFileSystem.lastDirectoryChangeTimestamp).toBe(timestampBefore)
+			expect(world.sync.taskErrors).toBe(taskErrorsBefore)
+		})
+	})
+
+	it("update* controls leave the pair untouched when called with an unknown uuid", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const ignorePath = `${world.localPath}/.filenignore`
+
+			expect(world.sync.paused).toBe(false)
+			expect(world.sync.excludeDotFiles).toBe(false)
+			expect(world.sync.mode).toBe("twoWay")
+			expect(world.sync.deletionConfirmationResult).toBe("waiting")
+			expect(world.vfs.controls.exists(ignorePath)).toBe(false)
+
+			world.worker.updatePaused("not-this-pair", true)
+			world.worker.updateExcludeDotFiles("not-this-pair", true)
+			world.worker.updateMode("not-this-pair", "localBackup")
+			world.worker.confirmDeletion("not-this-pair", "delete")
+			await world.worker.updateIgnorerContent("not-this-pair", "secret")
+			await world.worker.updateRemoved("not-this-pair", true)
+
+			expect(world.sync.paused).toBe(false)
+			expect(world.sync.excludeDotFiles).toBe(false)
+			expect(world.sync.mode).toBe("twoWay")
+			expect(world.sync.deletionConfirmationResult).toBe("waiting")
+			expect(world.sync.removed).toBe(false)
+			// updateIgnorerContent for an unknown uuid wrote nothing to the physical .filenignore.
+			expect(world.vfs.controls.exists(ignorePath)).toBe(false)
+		})
+	})
+
+	it("transfer controls are safe no-ops for unknown uuids and unknown transfer keys", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			// Unknown uuid: the per-sync lookup never matches, so nothing is registered.
+			world.worker.stopTransfer("not-this-pair", "upload", "/a.txt")
+			world.worker.pauseTransfer("not-this-pair", "upload", "/a.txt")
+			world.worker.resumeTransfer("not-this-pair", "upload", "/a.txt")
+
+			// Known uuid but a transfer key that was never registered: still a no-op, no controller or
+			// signal is conjured into existence.
+			world.worker.stopTransfer(uuid, "download", "/missing.txt")
+			world.worker.resumeTransfer(uuid, "download", "/missing.txt")
+			world.worker.pauseTransfer(uuid, "download", "/missing.txt")
+
+			expect(world.sync.abortControllers["upload:/a.txt"]).toBeUndefined()
+			expect(world.sync.abortControllers["download:/missing.txt"]).toBeUndefined()
+			expect(world.sync.pauseSignals["upload:/a.txt"]).toBeUndefined()
+			expect(world.sync.pauseSignals["download:/missing.txt"]).toBeUndefined()
+		})
+	})
+
+	it("control methods skip a registered pair that has no active Sync instance", async () => {
+		await withWorld({ mode: "twoWay" }, async world => {
+			const uuid = world.syncPair.uuid
+
+			// A pair present in `syncPairs` but with no instantiated Sync (e.g. before initialize() or after
+			// a teardown): the `!sync` guard must skip it safely rather than dereferencing undefined.
+			Reflect.deleteProperty(world.worker.syncs, uuid)
+
+			expect(() => {
+				world.worker.resetCache(uuid)
+				world.worker.resetTaskErrors(uuid)
+				world.worker.resetLocalTreeErrors(uuid)
+				world.worker.toggleLocalTrash(uuid, true)
+			}).not.toThrow()
+
+			// None of the calls recreated a Sync for the pair.
+			expect(world.worker.syncs[uuid]).toBeUndefined()
+		})
+	})
+})
+
+describe("utils — promiseAllChunked", () => {
+	it("withResults=true returns the fulfilled values in order across a chunk boundary", async () => {
+		const promises = [1, 2, 3, 4, 5].map(n => Promise.resolve(n * 10))
+
+		// chunkSize=2 < 5 forces multiple chunks; the concatenated result preserves input order.
+		const result = await promiseAllChunked(promises, 2, true)
+
+		expect(result).toEqual([10, 20, 30, 40, 50])
+	})
+
+	it("withResults=false awaits every promise but resolves to an empty array", async () => {
+		const order: number[] = []
+		const make = (n: number): Promise<void> =>
+			Promise.resolve().then(() => {
+				order.push(n)
+			})
+
+		const result = await promiseAllChunked([make(1), make(2), make(3), make(4), make(5)], 2, false)
+
+		expect(result).toEqual([])
+		// Every promise still ran even though no results were collected.
+		expect([...order].sort((a, b) => a - b)).toEqual([1, 2, 3, 4, 5])
+	})
+})
+
+describe("utils — promiseAllSettledChunked", () => {
+	it("withResults=true keeps fulfilled values in order and swallows rejections in the reducer", async () => {
+		const promises = [
+			Promise.resolve("a"),
+			Promise.reject(new Error("nope")),
+			Promise.resolve("b"),
+			Promise.reject(new Error("nope2")),
+			Promise.resolve("c")
+		]
+
+		const result = await promiseAllSettledChunked(promises, 2, true)
+
+		// Rejections are dropped by the reduce; only fulfilled values survive, in order.
+		expect(result).toEqual(["a", "b", "c"])
+	})
+
+	it("withResults=false awaits all settlements but resolves to an empty array", async () => {
+		const order: number[] = []
+		const make = (n: number): Promise<number> =>
+			Promise.resolve().then(() => {
+				order.push(n)
+
+				return n
+			})
+
+		const result = await promiseAllSettledChunked([make(1), make(2), make(3)], 2, false)
+
+		expect(result).toEqual([])
+		expect([...order].sort((a, b) => a - b)).toEqual([1, 2, 3])
+	})
+})
+
+describe("utils — isPathSyncedByICloud / pathSyncedByICloud", () => {
+	it("both resolve to false immediately on a non-darwin platform (no xattr exec, no dirname walk)", async () => {
+		await withPlatformAsync("linux", async () => {
+			expect(await pathSyncedByICloud("/home/me/Documents/file.txt")).toBe(false)
+			// isPathSyncedByICloud returns at the platform guard, never entering the dirname-walk loop.
+			expect(await isPathSyncedByICloud("/home/me/Documents/deeply/nested/file.txt")).toBe(false)
+		})
+
+		await withPlatformAsync("win32", async () => {
+			expect(await pathSyncedByICloud("C:/Users/me/file.txt")).toBe(false)
+			expect(await isPathSyncedByICloud("C:/Users/me/file.txt")).toBe(false)
+		})
+	})
+})

package/tsconfig.json

@@ -14,7 +14,16 @@
 		"skipLibCheck": true,
 		"declaration": true,
 		"resolveJsonModule": true,
-		"noUncheckedIndexedAccess": true
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		"noFallthroughCasesInSwitch": true,
+		"noImplicitReturns": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"exactOptionalPropertyTypes": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"allowUnreachableCode": false,
+		"allowUnusedLabels": false
 	},
 	"ts-node": {
 		"files": true

package/tsconfig.test.json

@@ -0,0 +1,12 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"rootDir": ".",
+		"noEmit": true,
+		"declaration": false,
+		"sourceMap": false,
+		"types": ["node", "vitest/globals"]
+	},
+	"include": ["src/**/*.ts", "tests/**/*.ts", "index.d.ts"],
+	"exclude": ["node_modules", "dist", "docs", ".github", "dev", ".vscode"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/constants.ts","./src/ignorer.ts","./src/index.ts","./src/semaphore.ts","./src/types.ts","./src/utils.ts","./src/lib/deltas.ts","./src/lib/environment.ts","./src/lib/ipc.ts","./src/lib/lock.ts","./src/lib/logger.ts","./src/lib/state.ts","./src/lib/sync.ts","./src/lib/tasks.ts","./src/lib/filesystems/dirTree.ts","./src/lib/filesystems/local.ts","./src/lib/filesystems/remote.ts","./index.d.ts"],"version":"5.9.3"}

package/vitest.bench.config.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from "vitest/config"
+
+/**
+ * Benchmark config — completely separate from the deterministic mocked suite (vitest.config.ts) and the
+ * live e2e suite (vitest.e2e.config.ts). Bench files are `tests/bench/**\/*.bench.ts`, which the mocked
+ * suite's include (`tests/**\/*.test.ts`) does NOT match, so they never run in `npm test` / CI.
+ *
+ * Run with NODE_OPTIONS so the measure harness can force GC for stable retained-heap numbers and large
+ * trees fit:
+ *   NODE_OPTIONS='--expose-gc --max-old-space-size=120000' npx vitest run --config vitest.bench.config.ts
+ * then render the report (see docs/perf/02-benchmarks.md). NODE_OPTIONS is inherited by the worker forks
+ * (verified) — Vitest 4 removed per-pool execArgv config.
+ *
+ * - REAL timers + REAL clock (we measure wall time).
+ * - Serial, no file parallelism: clean memory measurements + ordered JSONL appends.
+ * - Huge timeout: million-node trees take a while to build + process.
+ */
+export default defineConfig({
+	test: {
+		globals: true,
+		environment: "node",
+		include: ["tests/bench/**/*.bench.ts"],
+		testTimeout: 3_600_000,
+		hookTimeout: 3_600_000,
+		teardownTimeout: 600_000,
+		pool: "forks",
+		fileParallelism: false,
+		sequence: {
+			concurrent: false
+		}
+	}
+})

package/vitest.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig, configDefaults } from "vitest/config"
+
+export default defineConfig({
+	test: {
+		globals: true,
+		environment: "node",
+		include: ["tests/**/*.test.ts"],
+		// The live e2e suite has its own config (vitest.e2e.config.ts): real network, real clock, no
+		// coverage gate. Keep it out of the deterministic suite + its coverage gate.
+		exclude: [...configDefaults.exclude, "tests/e2e/**"],
+		coverage: {
+			provider: "v8",
+			include: ["src/**/*.ts"],
+			// Excluded from the gate: the real-I/O DI seams the suite intentionally bypasses
+			// (environment wiring, the enabled-logger path that writes to the user filesystem) and the
+			// declaration-only modules. The engine logic itself is gated below.
+			exclude: ["src/lib/environment.ts", "src/lib/logger.ts", "src/constants.ts", "src/types.ts"],
+			reporter: ["text", "html", "lcov"],
+			thresholds: {
+				statements: 90,
+				branches: 85,
+				functions: 90,
+				lines: 90
+			}
+		}
+	}
+})

package/vitest.e2e.config.ts

@@ -0,0 +1,68 @@
+import { defineConfig } from "vitest/config"
+import fs from "fs"
+import pathModule from "path"
+
+/**
+ * Load credentials from a gitignored `.env.e2e` at the repo root (KEY=VALUE lines) into process.env
+ * WITHOUT overriding anything already set (CI passes real GitHub secrets via env). This keeps the
+ * account creds out of the repo and out of any command line during local runs.
+ */
+function loadDotEnvE2E(): void {
+	const file = pathModule.join(__dirname, ".env.e2e")
+
+	if (!fs.existsSync(file)) {
+		return
+	}
+
+	for (const rawLine of fs.readFileSync(file, "utf-8").split("\n")) {
+		const line = rawLine.trim()
+
+		if (!line || line.startsWith("#")) {
+			continue
+		}
+
+		const eq = line.indexOf("=")
+
+		if (eq === -1) {
+			continue
+		}
+
+		const key = line.slice(0, eq).trim()
+		const value = line
+			.slice(eq + 1)
+			.trim()
+			.replace(/^["']|["']$/g, "")
+
+		if (key && process.env[key] === undefined) {
+			process.env[key] = value
+		}
+	}
+}
+
+loadDotEnvE2E()
+
+/**
+ * E2E config — real @filen/sdk against a live test account. Completely separate from the deterministic
+ * unit/scenario suite: a REAL clock (no fake timers), generous network timeouts, and serial execution
+ * (one world at a time against the shared account). No coverage gate — these validate live behavior, not
+ * lines. The suite skips itself when FILEN_TEST_EMAIL / FILEN_TEST_PASSWORD are absent.
+ */
+export default defineConfig({
+	test: {
+		globals: true,
+		environment: "node",
+		include: ["tests/e2e/**/*.test.ts"],
+		// Very generous: CI runners can be slow and real transfers + tree fetches add up. Better to wait
+		// than to flake on a slow-but-healthy run.
+		testTimeout: 3600_000,
+		hookTimeout: 3600_000,
+		teardownTimeout: 3600_000,
+		// One retry absorbs a transient network blip without masking a persistent failure.
+		retry: 1,
+		// Never run e2e files concurrently — they share one account.
+		fileParallelism: false,
+		sequence: {
+			concurrent: false
+		}
+	}
+})

package/.eslintrc

@@ -1,16 +0,0 @@
-{
-	"root": true,
-	"parser": "@typescript-eslint/parser",
-	"plugins": ["@typescript-eslint"],
-	"extends": ["eslint:recommended", "plugin:@typescript-eslint/eslint-recommended", "plugin:@typescript-eslint/recommended"],
-	"rules": {
-		"eqeqeq": 2,
-		"quotes": ["error", "double"],
-		"no-mixed-spaces-and-tabs": 0,
-		"no-duplicate-imports": "error"
-	},
-	"env": {
-		"browser": true,
-		"node": true
-	}
-}

package/jest.config.js

@@ -1,5 +0,0 @@
-module.exports = {
-	preset: "ts-jest",
-	testEnvironment: "node",
-	testMatch: ["**/tests/**/*.(spec|test).ts"]
-}