orynacode-ai 1.16.2

package/test/AGENTS.md

@@ -0,0 +1,204 @@
+# Test Fixtures Guide
+
+## Temporary Directory Fixture
+
+The `tmpdir` function in `fixture/fixture.ts` creates temporary directories for tests with automatic cleanup.
+
+### Basic Usage
+
+```typescript
+import { tmpdir } from "./fixture/fixture"
+
+test("example", async () => {
+  await using tmp = await tmpdir()
+  // tmp.path is the temp directory path
+  // automatically cleaned up when test ends
+})
+```
+
+### Options
+
+- `git?: boolean` - Initialize a git repo with a root commit
+- `config?: Partial<Config.Info>` - Write an `opencode.json` config file
+- `init?: (dir: string) => Promise<T>` - Custom setup function, returns value accessible as `tmp.extra`
+- `dispose?: (dir: string) => Promise<T>` - Custom cleanup function
+
+### Examples
+
+**Git repository:**
+
+```typescript
+await using tmp = await tmpdir({ git: true })
+```
+
+**With config file:**
+
+```typescript
+await using tmp = await tmpdir({
+  config: { model: "test/model", username: "testuser" },
+})
+```
+
+**Custom initialization (returns extra data):**
+
+```typescript
+await using tmp = await tmpdir<string>({
+  init: async (dir) => {
+    await Bun.write(path.join(dir, "file.txt"), "content")
+    return "extra data"
+  },
+})
+// Access extra data via tmp.extra
+console.log(tmp.extra) // "extra data"
+```
+
+**With cleanup:**
+
+```typescript
+await using tmp = await tmpdir({
+  init: async (dir) => {
+    const specialDir = path.join(dir, "special")
+    await fs.mkdir(specialDir)
+    return specialDir
+  },
+  dispose: async (dir) => {
+    // Custom cleanup logic
+    await fs.rm(path.join(dir, "special"), { recursive: true })
+  },
+})
+```
+
+### Returned Object
+
+- `path: string` - Absolute path to the temp directory (realpath resolved)
+- `extra: T` - Value returned by the `init` function
+- `[Symbol.asyncDispose]` - Enables automatic cleanup via `await using`
+
+### Notes
+
+- Directories are created in the system temp folder with prefix `opencode-test-`
+- Use `await using` for automatic cleanup when the variable goes out of scope
+- Paths are sanitized to strip null bytes (defensive fix for CI environments)
+
+## Testing With Effects
+
+Use `testEffect(...)` from `test/lib/effect.ts` for tests that exercise Effect services or Effect-based workflows.
+
+### Core Pattern
+
+```typescript
+import { describe, expect } from "bun:test"
+import { Effect, Layer } from "effect"
+import { testEffect } from "../lib/effect"
+
+const it = testEffect(Layer.mergeAll(MyService.defaultLayer))
+
+describe("my service", () => {
+  it.instance("does the thing", () =>
+    Effect.gen(function* () {
+      const svc = yield* MyService.Service
+      const out = yield* svc.run()
+      expect(out).toEqual("ok")
+    }),
+  )
+})
+```
+
+### `it.effect` vs `it.live`
+
+- Use `it.effect(...)` when the test should run with `TestClock` and `TestConsole`.
+- Use `it.live(...)` when the test depends on real time, filesystem mtimes, child processes, git, locks, or other live OS behavior.
+- Use `it.instance(...)` for live Effect tests that need a scoped temporary directory and instance context.
+- Most integration-style tests in this package use `it.live(...)`.
+
+### Effect Fixtures
+
+Prefer the Effect-aware helpers from `fixture/fixture.ts` instead of building a manual runtime in each test.
+
+- `tmpdirScoped(options?)` creates a scoped temp directory and cleans it up when the Effect scope closes.
+- `provideInstance(dir)(effect)` is the low-level helper. It does not create a directory; it runs an Effect with `InstanceRef` provided for `dir`.
+- `provideTmpdirInstance((dir) => effect, options?)` is the convenience helper. It creates a temp directory, binds it as the active instance, and disposes the instance on cleanup.
+- `provideTmpdirServer((input) => effect, options?)` does the same, but also provides the test LLM server.
+
+Use `it.instance(...)` by default when a test only needs one temp instance. Yield `TestInstance` from `fixture/fixture.ts` when the test needs the temp directory path:
+
+```typescript
+import { TestInstance } from "../fixture/fixture"
+
+it.instance("uses the temp directory", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    expect(test.directory).toContain("opencode-test-")
+  }),
+)
+```
+
+Use `provideTmpdirInstance(...)` or `tmpdirScoped()` plus `provideInstance(...)` when a test needs multiple directories, custom setup before binding, needs to switch instance context within one test, or explicitly tests instance disposal/reload lifetime.
+
+### Style
+
+- Define `const it = testEffect(...)` near the top of the file.
+- Keep the test body inside `Effect.gen(function* () { ... })`.
+- Yield services directly with `yield* MyService.Service` or `yield* MyTool`.
+- Avoid custom `ManagedRuntime`, `attach(...)`, or ad hoc `run(...)` wrappers when `testEffect(...)` already provides the runtime.
+- When a test needs instance-local state, prefer `it.instance(...)` over manual `Instance.provide(...)` inside Promise-style tests.
+
+### Partial Service Stubs
+
+When a test only needs to override one or two methods of a service, prefer `Layer.mock` over a hand-rolled `Layer.succeed(Service, Service.of({ ... }))`. `Layer.mock` lets you supply just the methods that matter — anything else throws an `UnimplementedError` defect if the test accidentally calls it, which is exactly the signal you want.
+
+```typescript
+import { Effect, Layer } from "effect"
+import { Account } from "@/account/account"
+
+const failingAccountLayer = Layer.mock(Account.Service, {
+  orgsByAccount: () => Effect.fail(new Account.AccountServiceError({ message: "simulated upstream failure" })),
+})
+```
+
+This is much shorter than stubbing every method with `Effect.void` / `Effect.succeed(...)` placeholders, and it keeps the test focused on the behaviour under test.
+
+## Synchronizing With Concurrent Work
+
+### The Anti-Pattern
+
+Using `Effect.sleep(N)` or `setTimeout` as a "wait for the forked fiber to be ready" hack races the scheduler. The forked fiber may not have reached the synchronization point within `N` ms on a slow CI host, and the test fails intermittently. See PR #27622 for a concrete flake that fell out of this exact pattern.
+
+### The Fix
+
+Wait on a **published readiness signal**, not wall-clock time. Available affordances:
+
+- `pollWithTimeout(effect, message, duration?)` from `test/lib/effect.ts` — repeatedly run a predicate effect until it returns a non-`undefined` value, with a timeout.
+- `awaitWithTimeout(effect, message, duration?)` from `test/lib/effect.ts` — wrap any effect with `Effect.timeoutOrElse` and a custom error message.
+- `llm.wait(n)` from `test/lib/llm-server.ts` — wait until the mock LLM has received `n` HTTP calls.
+- `SessionStatus.Service` `.get(sessionID)` — observable per-session state (`{ type: "busy" | "idle" | ... }`).
+- `BackgroundJob.wait({ id, timeout })` from `src/background/job.ts` — wait for a background job to complete.
+- Bus subscriptions — fork `Stream.runForEach(bus.subscribe(Event), ...)` and open a `Latch` inside the callback to signal first-event readiness.
+- `Deferred.await(deferred).pipe(Effect.timeoutOrElse(...))` for one-shot signals.
+
+### Example
+
+```ts
+// Antipattern — race
+yield * prompt.shell({ command: "sleep 30" }).pipe(Effect.forkChild)
+yield * Effect.sleep(50)
+yield * prompt.cancel(chat.id)
+
+// Fix — wait for a published readiness signal
+yield * prompt.shell({ command: "sleep 30" }).pipe(Effect.forkChild)
+yield *
+  pollWithTimeout(
+    Effect.gen(function* () {
+      const s = yield* (yield* SessionStatus.Service).get(chat.id)
+      return s.type === "busy" ? (true as const) : undefined
+    }),
+    "session never became busy",
+  )
+yield * prompt.cancel(chat.id)
+```
+
+### When Fixed Sleeps Are OK
+
+- Testing debounce or throttle behavior, where the sleep **is** the test.
+- Letting real wall-clock advance past a genuine timestamp resolution boundary (e.g. mtime granularity).
+- Simulating network latency in race-regression tests that intentionally exercise ordering.

package/test/EFFECT_TEST_MIGRATION.md

@@ -0,0 +1,169 @@
+# Effect Test Migration
+
+Move tests that exercise Effect services out of Promise-land and into the
+shared `testEffect` pattern.
+
+This file is guidance, not a live inventory. Before claiming a migration,
+search current `dev` for the exact anti-pattern and update any PR notes
+with what you actually changed.
+
+## Target Pattern
+
+Every Effect service test should have one local runner near the top:
+
+```ts
+const it = testEffect(layer)
+```
+
+Use the runner method that matches the behavior:
+
+```ts
+it.effect("pure service behavior", () =>
+  Effect.gen(function* () {
+    const service = yield* SomeService.Service
+    expect(yield* service.run()).toEqual("ok")
+  }),
+)
+
+it.instance("instance-local behavior", () =>
+  Effect.gen(function* () {
+    const test = yield* TestInstance
+    expect(test.directory).toContain("opencode-test-")
+  }),
+)
+
+it.live("live filesystem or process behavior", () =>
+  Effect.gen(function* () {
+    const dir = yield* tmpdirScoped()
+    // real clock / fs / git / process work
+  }),
+)
+```
+
+## Choosing The Runner
+
+- `it.effect(...)` — pure Effect behavior with `TestClock` and
+  `TestConsole`.
+- `it.instance(...)` — service behavior that needs one scoped opencode
+  instance.
+- `it.live(...)` — real time, filesystem mtimes, child processes, git,
+  locks, servers, watchers, or OS behavior.
+
+Most integration-style tests use `it.live(...)` or `it.instance(...)`.
+
+## Layer Rules
+
+Compose tests from open service layers when a dependency needs replacing.
+Do not use a closed `defaultLayer` and then try to override an inner
+dependency after it has already been provided.
+
+Prefer small reusable fake boundary layers in `test/fake/*`:
+
+```ts
+AuthTest.empty
+AccountTest.empty
+NpmTest.noop
+SkillTest.empty
+ProviderTest.fake().layer
+```
+
+Use `Layer.mock` for partial service stubs. Missing methods should fail
+loudly if the test accidentally calls them.
+
+Do not add generic test-layer builders until repeated local compositions
+prove the need.
+
+## Fixture Rules
+
+Use Effect-aware fixtures from `test/fixture/fixture.ts`:
+
+- `TestInstance` inside `it.instance(...)` for the current temp instance.
+- `tmpdirScoped(...)` inside `Effect.gen` for extra temp directories.
+- `provideInstance(dir)(effect)` when one test needs to switch instance
+  context.
+- `provideTmpdirInstance((dir) => effect, options)` when a live test needs
+  custom instance setup or multiple instance scopes.
+- `disposeAllInstances()` in `afterEach` only for integration tests that
+  intentionally touch shared instance registries.
+
+Avoid mutable global setup. If a global mutation is unavoidable during a
+migration, scope it with acquire/release and treat it as temporary.
+
+Long term, tests should not toggle `process.env`, `Global.Path`, or
+mutable flags when behavior can be modeled with services. Prefer layers
+such as `RuntimeFlags.layer(...)` or focused fake services.
+
+## Anti-Patterns To Remove
+
+- `test(..., async () => Effect.runPromise(...))`
+- local `run(...)`, `load(...)`, `svc(...)`, or `runtime.runPromise(...)`
+  wrappers that only provide a layer
+- `tmpdir()` plus legacy instance provision in Promise test bodies
+- custom `ManagedRuntime.make(...)` in test files
+- Promise `try/catch` around Effect failures
+- `Promise.withResolvers`, `Bun.sleep`, or `setTimeout` for synchronization
+  when events, `Deferred`, fibers, or deterministic state checks fit
+- mutable env/global/flag changes after layers are built
+
+Promise helpers are acceptable at non-Effect boundaries, but yield them from
+inside an Effect body with `Effect.promise(...)` rather than making them the
+test harness.
+
+## Conversion Recipe
+
+1. Identify the real service under test and whether its open `layer` or
+   closed `defaultLayer` is appropriate.
+2. Build one top-level `layer` with real dependencies where relevant and
+   fake layers at slow or external boundaries.
+3. Replace local Promise wrappers with Effect helpers.
+4. Convert `test(..., async () => { ... })` to `it.effect`, `it.instance`,
+   or `it.live`.
+5. Move `await` calls inside `Effect.gen` as `yield*` calls.
+6. Replace `await using tmp = await tmpdir(...)` with
+   `yield* tmpdirScoped(...)` when the temp directory lives inside the
+   Effect test.
+7. Replace Promise failure assertions with `Effect.exit`, `Effect.flip`, or
+   focused assertion helpers.
+8. Preserve concurrency with fibers, `Deferred`, and
+   `Effect.all(..., { concurrency: "unbounded" })`; do not accidentally
+   serialize formerly parallel behavior.
+9. Run the focused test file and `bun typecheck` from `packages/opencode`.
+
+## Good Examples
+
+Use current examples as patterns, but re-check them before copying because
+test migrations are active:
+
+- `test/effect/instance-state.test.ts` — scoped directories, instance
+  switching, disposal, and concurrency.
+- `test/bus/bus-effect.test.ts` — `Deferred`, streams, scoped fibers.
+- `test/agent/plugin-agent-regression.test.ts` — real service layers plus
+  fake boundary layers.
+- `test/account/service.test.ts` — service-level live tests, typed errors,
+  fake HTTP clients.
+
+## Migration Queue Policy
+
+Do not maintain a long file checklist here. It goes stale quickly.
+
+When looking for the next target, search for current anti-patterns:
+
+```bash
+git grep -n "Effect.runPromise\|ManagedRuntime\|Promise.withResolvers\|Bun.sleep\|withTestInstance" -- packages/opencode/test
+```
+
+Then choose one file or one small cluster, keep the PR focused, and mention
+the focused verification in the PR body.
+
+## Rough Edges To Watch
+
+- Failure assertions against `Exit` / `Cause` can get verbose. Add helpers
+  only after the same shape repeats across multiple files.
+- Some tests still need `Effect.promise(...)` around Node/Bun APIs. Prefer
+  Effect platform services when the surrounding code already uses them, but
+  do not block useful migrations on perfect abstraction.
+- Layer composition can be noisy when a test needs real service subtrees plus
+  fake boundaries. Extract small `test/fake/*` layers before inventing
+  larger builders.
+- Concurrency tests can get harder to read after replacing Promise
+  resolvers. Look for repeated patterns that deserve named helpers.