orynacode-ai 1.16.2

package/specs/effect/guide.md

@@ -0,0 +1,247 @@
+# Effect Guide
+
+How we write Effect code in `packages/opencode`. The companion roadmap is
+[`todo.md`](./todo.md).
+
+This guide describes the preferred shape for new work and migrations. If a
+legacy file differs, migrate it only when it is already in scope.
+
+## Service Shape
+
+Use one module per service: flat top-level exports, traced Effect methods,
+explicit layers, and a self-reexport at the bottom.
+
+```ts
+export interface Interface {
+  readonly get: (id: FooID) => Effect.Effect<FooInfo, FooError>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@opencode/Foo") {}
+
+export const layer = Layer.effect(
+  Service,
+  Effect.gen(function* () {
+    const state = yield* InstanceState.make<State>(Effect.fn("Foo.state")(() => Effect.succeed({})))
+
+    const get = Effect.fn("Foo.get")(function* (id: FooID) {
+      const s = yield* InstanceState.get(state)
+      return yield* loadFoo(s, id)
+    })
+
+    return Service.of({ get })
+  }),
+)
+
+export const defaultLayer = layer.pipe(Layer.provide(FooDep.defaultLayer))
+
+export * as Foo from "./foo"
+```
+
+Rules:
+
+- Do not use `export namespace Foo { ... }`.
+- Use `Effect.fn("Foo.method")` for public service methods.
+- Use `Effect.fnUntraced` for small internal helpers that do not need a
+  span.
+- Keep helpers as non-exported top-level declarations in the same file.
+- Self-reexport with `export * as Foo from "."` for `index.ts`, otherwise
+  `export * as Foo from "./foo"`.
+- In `src/config`, keep the existing top-of-file self-export pattern.
+
+## Runtime Boundaries
+
+Most code should run through [`AppRuntime`](../../src/effect/app-runtime.ts).
+It hosts `AppLayer`, shares the global `memoMap`, and restores the current
+instance/workspace refs when crossing from non-Effect code.
+
+Use `AppRuntime.runPromise(effect)` at app boundaries such as CLI commands,
+HTTP handlers, or plain async adapters.
+
+`makeRuntime(...)` still exists for a few intentional service-local
+boundaries and migration leftovers. Do not add a new service-local runtime
+unless the service truly cannot live in `AppLayer`.
+
+## Runtime Flags
+
+Read opencode runtime flags through
+[`RuntimeFlags.Service`](../../src/effect/runtime-flags.ts), not through
+mutable `Flag` or late `process.env` reads.
+
+Tests should vary behavior with explicit layer variants:
+
+```ts
+const it = testEffect(MyService.defaultLayer.pipe(Layer.provide(RuntimeFlags.layer({ experimentalReferences: true }))))
+```
+
+Do not mutate `process.env` or `Flag` after services/layers are built.
+
+## Per-Instance State
+
+Use [`InstanceState`](../../src/effect/instance-state.ts) when two open
+directories should not share one copy of a service's state. It is backed by
+a `ScopedCache`, keyed by directory, and disposed automatically when an
+instance is unloaded.
+
+Put subscriptions, finalizers, and scoped background work inside the
+`InstanceState.make(...)` initializer:
+
+```ts
+const cache =
+  yield *
+  InstanceState.make<State>(
+    Effect.fn("Foo.state")(function* () {
+      const bus = yield* Bus.Service
+
+      yield* bus.subscribeAll().pipe(
+        Stream.runForEach((event) => handleEvent(event)),
+        Effect.forkScoped,
+      )
+
+      yield* Effect.acquireRelease(openResource, closeResource)
+
+      return yield* loadInitialState()
+    }),
+  )
+```
+
+Do not add separate `started` flags on top of `InstanceState`. Let
+`ScopedCache` handle run-once and deduplication.
+
+To make `init()` non-blocking, fork at the caller/bootstrap boundary. Do
+not fork inside `InstanceState.make(...)` just to return early with
+partially initialized state.
+
+## Errors
+
+Expected domain failures belong on the Effect error channel. Defects are
+for bugs, impossible states, and final unknown-boundary fallbacks.
+
+```ts
+export class SessionBusyError extends Schema.TaggedErrorClass<SessionBusyError>()("SessionBusyError", {
+  sessionID: SessionID,
+  message: Schema.String,
+}) {}
+
+export type Error = Storage.Error | SessionBusyError
+
+export interface Interface {
+  readonly get: (id: SessionID) => Effect.Effect<Info, Error>
+}
+```
+
+Rules:
+
+- Use `Schema.TaggedErrorClass` for new expected domain errors.
+- Export a domain-level `Error` union from service modules.
+- In `Effect.gen` / `Effect.fn`, prefer `yield* new MyError(...)` for
+  direct expected failures.
+- Use `Schema.Defect` for unknown cause fields.
+- Use `Effect.try(...)`, `Effect.tryPromise(...)`, `Effect.mapError`,
+  `Effect.catchTag`, and `Effect.catchTags` to translate external
+  failures into domain errors.
+- Do not use `Effect.die(...)` for user, IO, validation, missing-resource,
+  auth, provider, or busy-state failures.
+
+## HTTP Error Boundaries
+
+Service modules stay HTTP-agnostic. They should not import HTTP status
+codes, `HttpApiError`, `HttpServerResponse`, or route-specific error
+schemas.
+
+HTTP handlers translate service errors into endpoint-declared public error
+schemas. Keep mappings inline when they are one-off; extract tiny shared
+helpers only when the same translation repeats.
+
+Do not turn generic middleware into a registry of domain errors. Middleware
+should handle cross-cutting concerns and the final unknown-defect fallback.
+
+Preserve legacy public wire shapes, such as `{ name, data }`, until a
+deliberate breaking API change.
+
+## Schemas
+
+Use Effect Schema as the source of truth.
+
+- Use `Schema.Class` for exported data objects with a clear identity.
+- Use `Schema.Struct` for local shapes and simple nested objects.
+- Use `Schema.brand` for single-value IDs.
+- Reuse named refinements instead of re-spelling constraints.
+- Prefer narrow boundary helpers over generic Schema-to-Zod bridges.
+
+Intentional boundaries:
+
+- Public plugin tools still expose Zod through `tool.schema = z`.
+- Tool parameter JSON Schema is generated through tool-specific helpers.
+- Public config and TUI schemas are generated through the schema script.
+
+## Preferred Services
+
+In effectified code, yield existing services instead of dropping to ad hoc
+platform APIs.
+
+- Use `FSUtil.Service` instead of raw `fs/promises` for app file IO.
+- Use `AppProcess.Service` instead of direct `ChildProcessSpawner.spawn` or
+  legacy process helpers.
+- Use `HttpClient.HttpClient` instead of raw `fetch` inside Effect code.
+- Use `Path.Path`, `Config`, `Clock`, and `DateTime` when already inside
+  Effect.
+- Use `Effect.callback` for callback-based APIs.
+- Use `Effect.void` instead of `Effect.succeed(undefined)`.
+- Use `Effect.cached` when concurrent callers should share one in-flight
+  computation.
+
+For background loops, use `Effect.repeat` or `Effect.schedule` with
+`Effect.forkScoped` in the owning layer/state scope.
+
+## Promise And ALS Bridges
+
+[`EffectBridge`](../../src/effect/bridge.ts) is the sanctioned helper for
+Promise/callback interop that needs to preserve instance/workspace context.
+It preserves explicit `InstanceRef` / `WorkspaceRef` context for effects run
+through the bridge. Plain JS callbacks that need instance data should receive
+that data explicitly.
+
+## Testing
+
+Detailed test migration rules live in
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md).
+
+Core pattern:
+
+```ts
+const it = testEffect(Layer.mergeAll(MyService.defaultLayer))
+
+describe("my service", () => {
+  it.instance("does the thing", () =>
+    Effect.gen(function* () {
+      const svc = yield* MyService.Service
+      expect(yield* svc.run()).toEqual("ok")
+    }),
+  )
+})
+```
+
+Rules:
+
+- Use `it.effect(...)` for TestClock/TestConsole tests.
+- Use `it.live(...)` for real timers, filesystem mtimes, child processes,
+  git, locks, or other live integration behavior.
+- Use `it.instance(...)` for service tests that need a scoped instance.
+- Prefer Effect-aware fixtures from `test/fixture/fixture.ts`.
+- Avoid sleeps; wait for real events or deterministic state transitions.
+- Avoid mutable `process.env`, `Flag`, or module-global changes after
+  layers are built.
+- Use `Layer.mock` for partial service stubs.
+- Avoid custom `ManagedRuntime`, `attach(...)`, or ad hoc `run(...)` test
+  wrappers.
+
+## Verification
+
+From `packages/opencode`:
+
+```bash
+bun run typecheck
+bun run test -- path/to/test.ts
+```
+
+Do not run tests from the repo root; the repo has a guard for that.

package/specs/effect/instance-context.md

@@ -0,0 +1,13 @@
+# Instance Context
+
+Instance selection is now Effect-provided context.
+
+Use these APIs:
+
+- `InstanceRef` for the current project context.
+- `WorkspaceRef` for the current workspace id.
+- `InstanceState.context` / `InstanceState.directory` inside Effect services that require an instance.
+- `InstanceStore` at entry boundaries that need to load, reload, or dispose project contexts.
+- `EffectBridge` for native, plugin, or plain JavaScript callback boundaries that need to re-enter Effect with captured refs.
+
+Do not add new ambient instance globals. Promise and callback boundaries should either stay in Effect, use `EffectBridge`, or pass the required context explicitly.

package/specs/effect/loose-ends.md

@@ -0,0 +1,30 @@
+# Effect loose ends
+
+Small follow-ups that do not fit neatly into the main facade, route, tool, or schema migration checklists.
+
+## Config / TUI
+
+- [ ] `cli/cmd/tui/config/tui.ts` - finish the internal Effect migration.
+      Keep the current precedence and migration semantics intact while converting the remaining internal async helpers (`loadState`, `mergeFile`, `loadFile`, `load`) to `Effect.gen(...)` / `Effect.fn(...)`.
+- [ ] `cli/cmd/tui/config/tui.ts` callers - once the internal service is stable, migrate plain async callers to use `TuiConfig.Service` directly where that actually simplifies the code.
+      Likely first callers: `cli/cmd/tui/attach.ts`, `cli/cmd/tui/thread.ts`, `cli/cmd/tui/plugin/runtime.ts`.
+- [x] `env/index.ts` - already uses `InstanceState.make(...)`.
+
+## ConfigPaths
+
+- [ ] `config/paths.ts` - split pure helpers from effectful helpers.
+      Keep `fileInDirectory(...)` as a plain function.
+- [ ] `config/paths.ts` - add a `ConfigPaths.Service` for the effectful operations so callers do not inherit `FSUtil.Service` directly.
+      Initial service surface should cover:
+  - `projectFiles(...)`
+  - `directories(...)`
+  - `readFile(...)`
+  - `parseText(...)`
+- [ ] `config/config.ts` - switch internal config loading from `Effect.promise(() => ConfigPaths.*(...))` to `yield* paths.*(...)` once the service exists.
+- [ ] `cli/cmd/tui/config/tui.ts` - switch TUI config loading from async `ConfigPaths.*` wrappers to the `ConfigPaths.Service` once that service exists.
+- [ ] `cli/cmd/tui/config/tui-migrate.ts` - decide whether to leave this as a plain async module using wrapper functions or effectify it fully after `ConfigPaths.Service` lands.
+
+## Notes
+
+- Prefer small, semantics-preserving config migrations. Config precedence, legacy key migration, and plugin origin tracking are easy to break accidentally.
+- When changing config loading internals, rerun the config and TUI suites first before broad package sweeps.

package/specs/effect/migration.md

@@ -0,0 +1,62 @@
+# Effect Migration Patterns
+
+This is the compact reference for moving code toward the current Effect
+shape. The high-level roadmap is [`todo.md`](./todo.md); examples and
+rules are in [`guide.md`](./guide.md).
+
+## Default Shape
+
+- Service methods return `Effect`.
+- Service methods are named with `Effect.fn("Domain.method")`.
+- Expected failures are typed errors on the error channel.
+- Dependencies are yielded once at layer construction and closed over by
+  methods.
+- `defaultLayer` wires production dependencies; tests can use open layers
+  when replacing dependencies.
+
+## Instance State
+
+Use `InstanceState` for per-directory state, subscriptions, scoped
+background work, and per-instance cleanup.
+
+Do not add ad hoc `started` flags on top of `InstanceState`; the scoped
+cache handles run-once and concurrent deduplication.
+
+## Runtime Boundaries
+
+Prefer `AppRuntime` for crossing from non-Effect code into the shared app
+layer.
+
+`makeRuntime(...)` exists for intentional service-local boundaries and
+legacy facades. Do not add new service-local runtimes unless the service is
+genuinely outside `AppLayer`.
+
+## Platform Edges
+
+- Use `FSUtil.Service` instead of raw filesystem APIs in
+  effectified services.
+- Use `AppProcess.Service` instead of raw process wrappers.
+- Use `HttpClient.HttpClient` instead of raw `fetch` in Effect code.
+- Use `Effect.cached` for shared in-flight work.
+- Use `Effect.callback` for callback APIs.
+
+## Tests During Migration
+
+When migrating code, migrate touched tests toward
+[`test/EFFECT_TEST_MIGRATION.md`](../../test/EFFECT_TEST_MIGRATION.md):
+
+- `testEffect(...)`
+- `it.effect`, `it.live`, or `it.instance`
+- explicit layers for behavior changes
+- deterministic waits instead of sleeps
+- no mutable env/global flags after layers are built
+
+## Migration Checklist
+
+- [ ] The code has a single Effect body instead of Promise wrappers around
+      service calls.
+- [ ] Expected failures are typed errors, not thrown exceptions or defects.
+- [ ] Layer requirements are explicit.
+- [ ] Tests use Effect-aware fixtures and focused layers.
+- [ ] Public behavior and wire shapes are preserved unless intentionally
+      changed.

package/specs/effect/routes.md

@@ -0,0 +1,61 @@
+# HTTP Route Patterns
+
+Current guidance for `packages/opencode/src/server/routes/instance/httpapi`.
+
+## Handler Shape
+
+Use `HttpApiBuilder.group(...)` for normal JSON and streaming HTTP API
+endpoints. Yield stable services once while building the handler layer,
+then close over those services in endpoint implementations.
+
+```ts
+export const sessionHandlers = HttpApiBuilder.group(InstanceHttpApi, "session", (handlers) =>
+  Effect.gen(function* () {
+    const session = yield* Session.Service
+
+    return handlers.handle("list", () => session.list())
+  }),
+)
+```
+
+Use raw `HttpRouter` only for routes that do not fit the request/response
+HttpApi model, such as WebSocket upgrades or catch-all fallback routes.
+
+Do not rebuild stable layers inside request handlers. Provide stable
+services at the route/layer boundary and use request-level provisioning
+only for request-derived context.
+
+## Error Boundaries
+
+Expected service errors should be mapped at the handler boundary to
+endpoint-declared public HTTP errors. Keep one-off mappings inline. Extract
+small helpers when the same mapping repeats.
+
+Generic middleware should not become a domain-error mapper. It should
+handle cross-cutting concerns and final unknown-defect fallback.
+
+Public JSON errors should be explicit schema contracts declared on each
+endpoint or group. Built-in `HttpApiError.*` is fine only when its generated
+body is intentionally the public wire shape.
+
+Preserve existing `{ name, data }` error bodies until a deliberate breaking
+API change.
+
+## OpenAPI Compatibility
+
+`public.ts` still owns SDK/OpenAPI compatibility transforms. Shrink those
+transforms by tightening source schemas one workaround at a time.
+
+When an OpenAPI-visible source schema changes:
+
+- verify the generated SDK diff is intentional
+- preserve legacy compatibility unless the PR explicitly changes it
+- prefer source-schema fixes over new post-processing rules
+
+## Checklist For Route PRs
+
+- [ ] Stable services are yielded at handler-layer construction.
+- [ ] Expected domain errors are translated at the route boundary.
+- [ ] Endpoint/group error schemas describe the public body and status.
+- [ ] Middleware does not gain new domain-specific name checks.
+- [ ] Raw routes are used only when HttpApi is the wrong abstraction.

package/specs/effect/schema.md

@@ -0,0 +1,88 @@
+# Schema Migration
+
+Use Effect Schema as the source of truth for domain models, DTOs, IDs,
+inputs, outputs, and typed errors.
+
+This is guidance, not an inventory. Do not use this file to track which
+schema modules are complete; verify current state with `git grep` before
+starting a migration.
+
+## Preferred Shapes
+
+Use `Schema.Class` for exported data objects with a clear domain identity:
+
+```ts
+export class Info extends Schema.Class<Info>("Foo.Info")({
+  id: FooID,
+  name: Schema.String,
+  enabled: Schema.Boolean,
+}) {}
+```
+
+Use `Schema.Struct` for local shapes and simple nested objects:
+
+```ts
+const Payload = Schema.Struct({
+  id: FooID,
+  value: Schema.String,
+})
+```
+
+Use `Schema.TaggedErrorClass` for expected domain errors:
+
+```ts
+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()("FooNotFoundError", {
+  id: FooID,
+}) {}
+```
+
+Use branded schema-backed IDs for single-value domain identifiers.
+
+## Boundary Rule
+
+Effect Schema should own the type. Boundaries should consume Effect Schema
+directly or use narrow boundary-specific helpers. Avoid reintroducing a
+generic Effect Schema -> Zod bridge.
+
+Current intentional boundaries:
+
+- Public plugin tools still expose Zod through `tool.schema = z`.
+- Tool parameters use tool-specific JSON Schema helpers.
+- Public config and TUI schema generation goes through the schema script.
+- AI SDK object generation uses Standard Schema / JSON Schema helpers.
+
+When Zod must stay temporarily, leave a short note explaining the boundary
+or compatibility reason.
+
+## Refinements
+
+Reuse named refinements instead of re-spelling constraints:
+
+```ts
+const PositiveInt = Schema.Number.check(Schema.isInt()).check(Schema.isGreaterThan(0))
+const NonNegativeInt = Schema.Number.check(Schema.isInt()).check(Schema.isGreaterThanOrEqualTo(0))
+```
+
+Prefer domain-named leaf schemas when the name improves callers or error
+messages. Avoid adding brands purely for novelty.
+
+## Migration Order
+
+For a domain that still has mixed schemas:
+
+1. Shared leaf models and branded IDs.
+2. Exported `Info`, `Input`, `Output`, and event payload types.
+3. Expected domain errors.
+4. Service-local internal models.
+5. HTTP/tool/AI boundary validators.
+
+Keep public wire shapes stable unless the PR is explicitly a breaking API
+change.
+
+## Checklist For A PR
+
+- [ ] There is one schema source of truth for each migrated type.
+- [ ] Remaining Zod is an intentional boundary choice.
+- [ ] Public JSON/OpenAPI output is unchanged or intentionally updated.
+- [ ] Derived helpers are narrow and boundary-specific.
+- [ ] Tests assert behavior, not duplicated schema implementation details.

package/specs/effect/server-package.md

@@ -0,0 +1,58 @@
+# Server Package Extraction
+
+Practical reference for a future `packages/server` split after the opencode
+server moved to the Effect HttpApi backend.
+
+## Current State
+
+- The server still lives in `packages/opencode`.
+- The runtime and app layer are centralized in `src/effect/app-runtime.ts` and
+  `src/effect/run-service.ts`.
+- The route tree lives under `src/server/routes/instance/httpapi` and is hosted
+  from `src/server/server.ts`.
+- OpenAPI generation is based on the HttpApi contract plus compatibility
+  translation in `src/server/routes/instance/httpapi/public.ts`.
+- There is no standalone `packages/server` workspace yet.
+
+## Future State
+
+Target package layout:
+
+- `packages/core` - shared domain services and schemas
+- `packages/server` - HTTP contracts, handlers, OpenAPI generation, and an
+  embeddable server API
+- `packages/cli` - TUI and CLI entrypoints
+- `packages/sdk` - generated from the server OpenAPI spec
+- `packages/plugin` - plugin authoring surface
+
+## Extraction Rule
+
+Do not create a package cycle.
+
+Until enough shared service code lives outside `packages/opencode`, a future
+`packages/server` should either:
+
+- own pure HttpApi contracts only, or
+- accept host-provided services/layers/callbacks from `packages/opencode`
+
+It should not import `packages/opencode` services while `packages/opencode`
+imports it to host routes.
+
+## Suggested PR Sequence
+
+1. Keep shrinking OpenAPI compatibility shims in `httpapi/public.ts`.
+2. Move stable domain schemas into shared packages only when they no longer
+   depend on opencode-local runtime modules.
+3. Extract pure HttpApi contract modules into `packages/server` once the contract
+   can compile without importing `packages/opencode` implementation details.
+4. Extract handler factories after their service dependencies can be supplied by
+   a host layer instead of imported directly.
+5. Move server hosting last, after package ownership is clear.
+
+## Non-Goals
+
+- Do not revive the old dual-backend migration shape.
+- Do not split server hosting before service dependencies have a clean package
+  boundary.
+- Do not switch SDK generation to a new package until generated output is known
+  to remain compatible.