From f7259617e5cf0784225c8a8919346ef5438de2ef Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Thu, 12 Mar 2026 13:05:50 -0400 Subject: [PATCH 1/5] refactor(auth): extract AuthService Move auth file I/O and key normalization into an Effect service so auth can migrate like account while the existing Auth facade stays stable for callers. Document the broader Effect rollout and instance-state migration strategy to guide follow-on extractions. --- packages/opencode/EFFECT_MIGRATION_PLAN.md | 399 +++++++++++++++++++++ packages/opencode/src/auth/index.ts | 84 ++--- packages/opencode/src/auth/service.ts | 114 ++++++ packages/opencode/src/effect/runtime.ts | 5 +- 4 files changed, 542 insertions(+), 60 deletions(-) create mode 100644 packages/opencode/EFFECT_MIGRATION_PLAN.md create mode 100644 packages/opencode/src/auth/service.ts diff --git a/packages/opencode/EFFECT_MIGRATION_PLAN.md b/packages/opencode/EFFECT_MIGRATION_PLAN.md new file mode 100644 index 00000000000..609b1954598 --- /dev/null +++ b/packages/opencode/EFFECT_MIGRATION_PLAN.md @@ -0,0 +1,399 @@ +# Effect migration + +Practical path for adopting Effect in opencode. + +## Aim + +Move `packages/opencode` toward Effect one domain at a time. Treat the migration as successful when the core path for a domain is Effect-based, even if temporary promise wrappers still exist at the edges. + +--- + +## Decide + +Use these defaults unless a domain gives us a good reason not to. + +- Migrate one module or domain at a time +- Preserve compatibility mainly at boundaries, not throughout internals +- Prefer adapter-layer-first work for mutable or request-scoped systems +- Treat CLI, server, and jobs as runtime boundaries +- Use the shared managed runtime only as a bridge during migration + +This keeps the work incremental and lets us remove compatibility code later instead of freezing it into every layer. + +--- + +## Slice work + +Pick migration units that can own a clear service boundary and a small runtime story. + +Good early candidates: + +- CRUD-like domains with stable storage and HTTP boundaries +- Modules that already have a natural service shape +- Areas where a promise facade can stay temporarily at the public edge + +Harder candidates: + +- `Instance`-like systems with async local state +- Request-scoped mutable state +- Modules that implicitly depend on ambient context or lifecycle ordering + +--- + +## Start at boundaries + +Begin by extracting an Effect service behind the existing module boundary. Keep old call sites working by adding a thin promise facade only where needed. + +Current example: + +- `packages/opencode/src/account/service.ts` holds the Effect-native service +- `packages/opencode/src/account/index.ts` keeps a promise-facing facade +- `packages/opencode/src/cli/cmd/account.ts` already uses `AccountService` directly +- `packages/opencode/src/config/config.ts` and `packages/opencode/src/share/share-next.ts` still use the facade + +This is the preferred first move for most domains. + +--- + +## Bridge runtime + +Use a shared app runtime only to help mixed code coexist while we migrate. Do not treat it as the final architecture by default. + +Current bridge: + +- `packages/opencode/src/effect/runtime.ts` + +Near-term rule: + +- Effect-native entrypoints can run effects directly +- Legacy promise namespaces can call into the shared runtime +- New domains should not depend on broad global runtime access unless they are explicitly boundary adapters + +As more boundaries become Effect-native, the shared runtime should shrink instead of becoming more central. + +--- + +## Handle state + +Treat async local state and mutable contextual systems as adapter problems first. Do not force `Instance`-style behavior directly into pure domain services on the first pass. + +Recommended approach: + +- Keep current mutable/contextual machinery behind a small adapter +- Expose a narrower Effect service above that adapter +- Move ambient reads and writes to the edge of the module +- Delay deeper context redesign until the boundary is stable + +For `Instance`-like code, the first win is usually isolating state access, not eliminating it. + +--- + +## Wrap `Instance` + +Keep `Instance` backed by AsyncLocalStorage for now. Do not force a full ALS replacement before we have a clearer service boundary. + +- Add an Effect-facing interface over the current ALS-backed implementation first +- Point new Effect code at that interface +- Let untouched legacy code keep using raw `Instance` + +We may split mutable state from read-only context as the design settles. If that happens, state can migrate on its own path and then depend on the Effect-facing context version instead of raw ALS directly. + +**Instance.state** - Most modules use `Instance.state()` for scoped mutable state, so we should not try to replace `Instance` itself too early. Start by wrapping it in an adapter and exposing an Effect service above the current machinery. Over time, state should move onto an Effectful abstraction of our own, with `ScopedCache` as the most likely fit for per-instance state that needs keyed lookup and cleanup. It can stay scoped by the current instance key during transition, usually the directory today, while domains can still add finer keys like `SessionID` inside their own state where needed. + +This keeps the first step small, lowers risk, and avoids redesigning request context too early. + +--- + +## Shape APIs + +Prefer an Effect-first core and a compatibility shell at the edge. + +Guidance: + +- Name the service after the domain, like `AccountService` +- Keep methods small and domain-shaped, not transport-shaped +- Return `Effect` from the core service +- Use promise helpers only in legacy namespaces or boundary adapters +- Keep error types explicit when the domain already has stable error shapes + +Small pattern: + +```ts +export class FooService extends ServiceMap.Service()("@opencode/Foo") { + static readonly layer = Layer.effect( + FooService, + Effect.gen(function* () { + return FooService.of({ + get: Effect.fn("FooService.get")(function* (id: FooID) { + return yield* ... + }), + }) + }), + ) +} +``` + +Temporary facade pattern: + +```ts +function runPromise(f: (service: FooService.Service) => Effect.Effect) { + return runtime.runPromise(FooService.use(f)) +} + +export namespace Foo { + export function get(id: FooID) { + return runPromise((service) => service.get(id)) + } +} +``` + +--- + +## Use Repo carefully + +A `Repo` layer is often useful, but it should stay a tool, not a rule. + +Tradeoffs: + +- `Repo` helps when storage concerns are real and reusable +- `Repo` can clarify error mapping and persistence boundaries +- `Repo` can also add ceremony for thin modules or one-step workflows + +Current leaning: + +- Use a `Repo` when it simplifies storage-heavy domains +- Skip it when a direct service implementation stays clearer +- Revisit consistency after a few more migrations, not before + +`packages/opencode/src/account/repo.ts` is a reasonable pattern for storage-backed domains, but it should not become mandatory yet. + +--- + +## Test safely + +Keep tests stable while internals move. Prefer preserving current test surfaces until a domain has fully crossed its main boundary. + +Practical guidance: + +- Keep existing promise-based tests passing first +- Add focused tests for new service behavior where it reduces risk +- Move boundary tests later, after the internal service shape settles +- Avoid rewriting test helpers and runtime wiring in the same PR as a domain extraction + +This lowers risk and makes the migration easier to review. + +--- + +## Roll out + +Use a phased roadmap. + +### Phase 0 + +Set conventions and prove the boundary pattern. + +- Keep `account` as the reference example, but not the template for every case +- Document the temporary runtime bridge and when to use it +- Prefer one or two more CRUD-like domains next + +### Phase 1 + +Migrate easy and medium domains one at a time. + +- Extract service +- Keep boundary facade if needed +- Convert one runtime entrypoint to direct Effect use +- Collapse internal promise plumbing inside the domain + +### Phase 2 + +Tackle context-heavy systems with adapters first. + +- Isolate async local state behind Effect-facing adapters +- Move lifecycle and mutable state reads to runtime edges +- Convert core domain logic before trying to redesign shared context + +### Phase 3 + +Reduce bridges and compatibility surfaces. + +- Remove facades that no longer serve external callers +- Narrow the shared runtime bridge +- Standardize remaining service and error shapes where it now feels earned + +--- + +## Check progress + +Use these signals to judge whether a domain is really migrated. + +A domain is in good shape when: + +- Its core logic runs through an Effect service +- Internal callers prefer the Effect API +- Compatibility wrappers exist only at real boundaries +- CLI, server, or job entrypoints can run the Effect path directly +- The shared runtime is only a temporary connector, not the center of the design + +A domain is not done just because it has an Effect service somewhere in the stack. + +--- + +## Candidate ranking + +Ranked by feasibility and payoff. Account is already migrated and serves as the reference. + +### Tier 1 — Easy wins + +| # | Module | Lines | Shape | Why | +| --- | -------------- | ----- | -------------------------------------- | -------------------------------------------------------------------------------------------------- | +| 1 | **Auth** | 74 | File CRUD (get/set/remove) | Zero ambient state, zero deps besides Filesystem. Trivial win to prove the pattern beyond account. | +| 2 | **Question** | 168 | ask/reply/reject + Instance.state Map | Clean service boundary, single pending Map. Nearly identical to Permission but simpler. | +| 3 | **Permission** | 210 | ask/respond/list + session-scoped Maps | Pending + approved Maps, already uses branded IDs. Session-scoped state maps to Effect context. | +| 4 | **Scheduler** | 62 | register/unregister tasks with timers | `Effect.repeat` / `Effect.schedule` is a natural fit. Tiny surface area. | + +### Tier 2 — Medium complexity, high payoff + +| # | Module | Lines | Shape | Why | +| --- | ---------------- | ----- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| 5 | **Pty** | 318 | Session lifecycle (create/remove/resize/write) | Process + subscriber cleanup maps to `Effect.acquireRelease`. Buffer/subscriber state is instance-scoped. | +| 6 | **Bus** | 106 | Pub/sub with instance-scoped subscriptions | Fiber-based subscription cleanup would eliminate manual `off()` patterns throughout the codebase. | +| 7 | **Snapshot** | 417 | Git snapshot/patch/restore | Heavy subprocess I/O. Effect error handling and retry would help. No ambient state. | +| 8 | **Worktree** | 673 | Git worktree create/remove/reset | Stateless, all subprocess-based. Good `Effect.fn` candidate but larger surface. | +| 9 | **Installation** | 304 | Version check + upgrade across package managers | Multiple fallback paths (npm/brew/choco/scoop). Effect's error channel shines here. | + +### Tier 3 — Harder, migrate after patterns are settled + +| # | Module | Lines | Shape | Why | +| --- | -------- | ----- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| 10 | **File** | 655 | File ops with cache state | Background fetch side-effects would benefit from Fiber management. Mutable cache (files/dirs Maps) adds complexity. | +| 11 | **LSP** | 487 | Client lifecycle: spawning → connected → broken | Effect resource management fits, but multi-state transitions are tricky. | +| 12 | **MCP** | 981 | Client lifecycle + OAuth flows | Largest single module. OAuth state spans multiple functions (startAuth → finishAuth). High payoff but highest risk. | + +### Avoid early + +These are too large, too foundational, or too pervasive to migrate without significant prior experience: + +- **Provider** (~1400 lines) — provider-specific branching, AI SDK abstractions, complex model selection +- **Session** (~900 lines) — complex relational queries, branching logic, many dependents +- **Config** — pervasive dependency across codebase, complex precedence rules +- **Project / Instance** — foundational bootstrap, async local state, everything depends on it + +### Patterns to watch for + +**Instance.state** — Most modules use `Instance.state()` for scoped mutable state. Don't try to replace Instance itself early; wrap it in an adapter that exposes an Effect service above the existing machinery. + +**Bus.subscribe + manual off()** — Pervasive throughout the codebase. Migrating Bus (candidate #6) unlocks Fiber-based cleanup everywhere, but it's infrastructure, not a domain win. Consider it after a few domain migrations prove the pattern. + +**Database.use / Database.transaction** — Already resembles Effect context (provide/use pattern). Could become an Effect Layer, but this is infrastructure work best deferred until multiple domains are Effect-native. + +**Process subprocess patterns** — Snapshot, Worktree, Installation all shell out to git or package managers. These are natural `Effect.tryPromise` / `Effect.fn` targets with error mapping. + +--- + +## Effect modules to use + +Effect already provides battle-tested replacements for several homegrown patterns. Prefer these over custom code as domains migrate. + +### PubSub → replaces Bus + +`PubSub` provides bounded/unbounded pub/sub with backpressure strategies. Subscriptions are scoped — cleanup is automatic when the subscriber's Scope closes, eliminating every manual `off()` call. + +```ts +const pubsub = yield * PubSub.unbounded() +yield * PubSub.publish(pubsub, event) +// subscriber — automatically cleaned up when scope ends +const dequeue = yield * PubSub.subscribe(pubsub) +const event = yield * Queue.take(dequeue) +``` + +Don't migrate Bus first. Migrate domain modules, then swap Bus once there are enough Effect-native consumers. + +### Schedule → replaces Scheduler + +The custom 62-line Scheduler reinvents `Effect.repeat`. Effect's `Schedule` is composable and supports spaced intervals, exponential backoff, cron expressions, and more. + +```ts +yield * effect.pipe(Effect.repeat(Schedule.spaced("30 seconds"))) +``` + +### SubscriptionRef → replaces state + Bus.publish on mutation + +Several modules follow the pattern: mutate `Instance.state`, then `Bus.publish` to notify listeners. `SubscriptionRef` is a `Ref` that emits changes as a `Stream`, combining both in one primitive. + +```ts +const ref = yield * SubscriptionRef.make(initialState) +// writer +yield * SubscriptionRef.update(ref, (s) => ({ ...s, count: s.count + 1 })) +// reader — stream of every state change +yield * SubscriptionRef.changes(ref).pipe(Stream.runForEach(handleUpdate)) +``` + +### Ref / SynchronizedRef → replaces Instance.state Maps + +`Ref` provides atomic read/write/update for concurrent-safe state. `SynchronizedRef` adds mutual exclusion for complex multi-step updates. Use these inside Effect services instead of raw mutable Maps. + +### Scope + acquireRelease → replaces manual resource cleanup + +Pty sessions, LSP clients, and MCP clients all have manual try/finally cleanup. `Effect.acquireRelease` ties resource lifecycle to Scope, making cleanup declarative and leak-proof. + +```ts +const pty = yield * Effect.acquireRelease(createPty(options), (session) => destroyPty(session)) +``` + +### ChildProcess → replaces shell-outs + +Effect's `ChildProcess` provides type-safe subprocess execution with template literals and stream-based stdout/stderr. Useful for Snapshot, Worktree, and Installation modules. + +```ts +const result = yield * ChildProcess.make`git diff --stat`.pipe(ChildProcess.spawn, ChildProcess.string) +``` + +Note: in `effect/unstable/process` — API may shift. + +### FileSystem → replaces custom Filesystem utils + +Cross-platform file I/O with stream support. Available via `effect/FileSystem` with a `NodeFileSystem` layer. + +### KeyValueStore → replaces file-based Auth JSON + +Abstracted key-value storage with file, memory, and browser backends. Auth's 74-line file CRUD could become a one-liner with `KeyValueStore`. + +Available via `effect/unstable/persistence` — API may shift. + +### HttpClient → replaces custom fetch calls + +Full HTTP client with typed errors, request builders, and platform-aware layers. Useful when migrating Share and ControlPlane modules. + +Available via `effect/unstable/http` — API may shift. + +### HttpApi → replaces Hono + +Effect's `HttpApi` provides schema-driven HTTP APIs with OpenAPI generation, type-safe routing, and middleware. Long-term candidate to replace the Hono server layer entirely. This is a larger lift — defer until multiple domain services are Effect-native and the boundary pattern is well-proven. + +Available via `effect/unstable/httpapi` — API may shift. + +### Schema → replaces Zod (partially) + +Effect's `Schema` provides encoding/decoding, validation, and type derivation deeply integrated with Effect. Internal code can migrate to Schema as domains move to Effect services. However, the plugin API (`@opencode-ai/plugin`) uses Zod and must continue to accept Zod schemas at the boundary. Keep Zod-to-Schema bridges at plugin/SDK edges. + +### Cache → replaces manual caching + +The File module maintains mutable Maps (files/dirs) with a fetching flag for deduplication. `Cache` provides memoization with TTL and automatic deduplication, replacing this pattern. + +### Pool → for resource-heavy clients + +LSP client management (spawning/connected/broken state machine) could benefit from `Pool` for automatic acquisition, health checking, and release. + +--- + +## Follow next + +Recommended medium-term order: + +1. Continue with CRUD-like or storage-backed modules +2. Convert boundary entrypoints in CLI, server, and jobs as services become available +3. Move into `Instance`-adjacent systems with adapter layers, not direct rewrites +4. Remove promise facades after direct callers have moved + +This keeps momentum while reserving the hardest context work for when the team has a clearer house style. diff --git a/packages/opencode/src/auth/index.ts b/packages/opencode/src/auth/index.ts index 80253a665e9..d362069f206 100644 --- a/packages/opencode/src/auth/index.ts +++ b/packages/opencode/src/auth/index.ts @@ -1,73 +1,41 @@ -import path from "path" -import { Global } from "../global" -import z from "zod" -import { Filesystem } from "../util/filesystem" - -export const OAUTH_DUMMY_KEY = "opencode-oauth-dummy-key" +import { Effect } from "effect" +import { runtime } from "@/effect/runtime" +import { + Api as ApiSchema, + AuthService, + type AuthServiceError, + Info as InfoSchema, + Oauth as OauthSchema, + WellKnown as WellKnownSchema, + type Info as AuthInfo, +} from "./service" + +export { OAUTH_DUMMY_KEY } from "./service" + +function runPromise(f: (service: AuthService.Service) => Effect.Effect) { + return runtime.runPromise(AuthService.use(f)) +} export namespace Auth { - export const Oauth = z - .object({ - type: z.literal("oauth"), - refresh: z.string(), - access: z.string(), - expires: z.number(), - accountId: z.string().optional(), - enterpriseUrl: z.string().optional(), - }) - .meta({ ref: "OAuth" }) - - export const Api = z - .object({ - type: z.literal("api"), - key: z.string(), - }) - .meta({ ref: "ApiAuth" }) - - export const WellKnown = z - .object({ - type: z.literal("wellknown"), - key: z.string(), - token: z.string(), - }) - .meta({ ref: "WellKnownAuth" }) - - export const Info = z.discriminatedUnion("type", [Oauth, Api, WellKnown]).meta({ ref: "Auth" }) - export type Info = z.infer - - const filepath = path.join(Global.Path.data, "auth.json") + export const Oauth = OauthSchema + export const Api = ApiSchema + export const WellKnown = WellKnownSchema + export const Info = InfoSchema + export type Info = AuthInfo export async function get(providerID: string) { - const auth = await all() - return auth[providerID] + return runPromise((service) => service.get(providerID)) } export async function all(): Promise> { - const data = await Filesystem.readJson>(filepath).catch(() => ({})) - return Object.entries(data).reduce( - (acc, [key, value]) => { - const parsed = Info.safeParse(value) - if (!parsed.success) return acc - acc[key] = parsed.data - return acc - }, - {} as Record, - ) + return runPromise((service) => service.all()) } export async function set(key: string, info: Info) { - const normalized = key.replace(/\/+$/, "") - const data = await all() - if (normalized !== key) delete data[key] - delete data[normalized + "/"] - await Filesystem.writeJson(filepath, { ...data, [normalized]: info }, 0o600) + return runPromise((service) => service.set(key, info)) } export async function remove(key: string) { - const normalized = key.replace(/\/+$/, "") - const data = await all() - delete data[key] - delete data[normalized] - await Filesystem.writeJson(filepath, data, 0o600) + return runPromise((service) => service.remove(key)) } } diff --git a/packages/opencode/src/auth/service.ts b/packages/opencode/src/auth/service.ts new file mode 100644 index 00000000000..c98087934c9 --- /dev/null +++ b/packages/opencode/src/auth/service.ts @@ -0,0 +1,114 @@ +import path from "path" +import { Effect, Layer, Schema, ServiceMap } from "effect" +import z from "zod" +import { Global } from "../global" +import { Filesystem } from "../util/filesystem" + +export const OAUTH_DUMMY_KEY = "opencode-oauth-dummy-key" + +export const Oauth = z + .object({ + type: z.literal("oauth"), + refresh: z.string(), + access: z.string(), + expires: z.number(), + accountId: z.string().optional(), + enterpriseUrl: z.string().optional(), + }) + .meta({ ref: "OAuth" }) + +export const Api = z + .object({ + type: z.literal("api"), + key: z.string(), + }) + .meta({ ref: "ApiAuth" }) + +export const WellKnown = z + .object({ + type: z.literal("wellknown"), + key: z.string(), + token: z.string(), + }) + .meta({ ref: "WellKnownAuth" }) + +export const Info = z.discriminatedUnion("type", [Oauth, Api, WellKnown]).meta({ ref: "Auth" }) +export type Info = z.infer + +export class AuthServiceError extends Schema.TaggedErrorClass()("AuthServiceError", { + message: Schema.String, + cause: Schema.optional(Schema.Defect), +}) {} + +const file = path.join(Global.Path.data, "auth.json") + +const fail = (message: string) => (cause: unknown) => new AuthServiceError({ message, cause }) + +export namespace AuthService { + export interface Service { + readonly get: (providerID: string) => Effect.Effect + readonly all: () => Effect.Effect, AuthServiceError> + readonly set: (key: string, info: Info) => Effect.Effect + readonly remove: (key: string) => Effect.Effect + } +} + +export class AuthService extends ServiceMap.Service()("@opencode/Auth") { + static readonly layer = Layer.effect( + AuthService, + Effect.gen(function* () { + const all = Effect.fn("AuthService.all")(() => + Effect.tryPromise({ + try: async () => { + const data = await Filesystem.readJson>(file).catch(() => ({})) + return Object.entries(data).reduce( + (acc, [key, value]) => { + const parsed = Info.safeParse(value) + if (!parsed.success) return acc + acc[key] = parsed.data + return acc + }, + {} as Record, + ) + }, + catch: fail("Failed to read auth data"), + }), + ) + + const get = Effect.fn("AuthService.get")(function* (providerID: string) { + return (yield* all())[providerID] + }) + + const set = Effect.fn("AuthService.set")(function* (key: string, info: Info) { + const norm = key.replace(/\/+$/, "") + const data = yield* all() + if (norm !== key) delete data[key] + delete data[norm + "/"] + yield* Effect.tryPromise({ + try: () => Filesystem.writeJson(file, { ...data, [norm]: info }, 0o600), + catch: fail("Failed to write auth data"), + }) + }) + + const remove = Effect.fn("AuthService.remove")(function* (key: string) { + const norm = key.replace(/\/+$/, "") + const data = yield* all() + delete data[key] + delete data[norm] + yield* Effect.tryPromise({ + try: () => Filesystem.writeJson(file, data, 0o600), + catch: fail("Failed to write auth data"), + }) + }) + + return AuthService.of({ + get, + all, + set, + remove, + }) + }), + ) + + static readonly defaultLayer = AuthService.layer +} diff --git a/packages/opencode/src/effect/runtime.ts b/packages/opencode/src/effect/runtime.ts index 1868b38a015..23acff73379 100644 --- a/packages/opencode/src/effect/runtime.ts +++ b/packages/opencode/src/effect/runtime.ts @@ -1,4 +1,5 @@ -import { ManagedRuntime } from "effect" +import { Layer, ManagedRuntime } from "effect" import { AccountService } from "@/account/service" +import { AuthService } from "@/auth/service" -export const runtime = ManagedRuntime.make(AccountService.defaultLayer) +export const runtime = ManagedRuntime.make(Layer.mergeAll(AccountService.defaultLayer, AuthService.defaultLayer)) From 7f12976ea0f5b9b5c0ca471cd98851f5882a4b32 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Thu, 12 Mar 2026 13:25:52 -0400 Subject: [PATCH 2/5] refactor(auth): use Effect Schema internally Model auth entries with Effect Schema inside AuthService and use Schema decoding when reading persisted auth data. Keep the Auth facade on Zod at the boundary so existing validators and callers stay stable during the migration. --- packages/opencode/src/auth/index.ts | 48 ++++++++++++++------- packages/opencode/src/auth/service.ts | 61 ++++++++++++--------------- 2 files changed, 60 insertions(+), 49 deletions(-) diff --git a/packages/opencode/src/auth/index.ts b/packages/opencode/src/auth/index.ts index d362069f206..79e9e615d21 100644 --- a/packages/opencode/src/auth/index.ts +++ b/packages/opencode/src/auth/index.ts @@ -1,27 +1,43 @@ import { Effect } from "effect" +import z from "zod" import { runtime } from "@/effect/runtime" -import { - Api as ApiSchema, - AuthService, - type AuthServiceError, - Info as InfoSchema, - Oauth as OauthSchema, - WellKnown as WellKnownSchema, - type Info as AuthInfo, -} from "./service" +import * as S from "./service" export { OAUTH_DUMMY_KEY } from "./service" -function runPromise(f: (service: AuthService.Service) => Effect.Effect) { - return runtime.runPromise(AuthService.use(f)) +function runPromise(f: (service: S.AuthService.Service) => Effect.Effect) { + return runtime.runPromise(S.AuthService.use(f)) } export namespace Auth { - export const Oauth = OauthSchema - export const Api = ApiSchema - export const WellKnown = WellKnownSchema - export const Info = InfoSchema - export type Info = AuthInfo + export const Oauth = z + .object({ + type: z.literal("oauth"), + refresh: z.string(), + access: z.string(), + expires: z.number(), + accountId: z.string().optional(), + enterpriseUrl: z.string().optional(), + }) + .meta({ ref: "OAuth" }) + + export const Api = z + .object({ + type: z.literal("api"), + key: z.string(), + }) + .meta({ ref: "ApiAuth" }) + + export const WellKnown = z + .object({ + type: z.literal("wellknown"), + key: z.string(), + token: z.string(), + }) + .meta({ ref: "WellKnownAuth" }) + + export const Info = z.discriminatedUnion("type", [Oauth, Api, WellKnown]).meta({ ref: "Auth" }) + export type Info = z.infer export async function get(providerID: string) { return runPromise((service) => service.get(providerID)) diff --git a/packages/opencode/src/auth/service.ts b/packages/opencode/src/auth/service.ts index c98087934c9..0898b39df7d 100644 --- a/packages/opencode/src/auth/service.ts +++ b/packages/opencode/src/auth/service.ts @@ -1,39 +1,32 @@ import path from "path" -import { Effect, Layer, Schema, ServiceMap } from "effect" -import z from "zod" +import { Effect, Layer, Option, Schema, ServiceMap } from "effect" import { Global } from "../global" import { Filesystem } from "../util/filesystem" export const OAUTH_DUMMY_KEY = "opencode-oauth-dummy-key" -export const Oauth = z - .object({ - type: z.literal("oauth"), - refresh: z.string(), - access: z.string(), - expires: z.number(), - accountId: z.string().optional(), - enterpriseUrl: z.string().optional(), - }) - .meta({ ref: "OAuth" }) - -export const Api = z - .object({ - type: z.literal("api"), - key: z.string(), - }) - .meta({ ref: "ApiAuth" }) - -export const WellKnown = z - .object({ - type: z.literal("wellknown"), - key: z.string(), - token: z.string(), - }) - .meta({ ref: "WellKnownAuth" }) - -export const Info = z.discriminatedUnion("type", [Oauth, Api, WellKnown]).meta({ ref: "Auth" }) -export type Info = z.infer +export class Oauth extends Schema.Class("OAuth")({ + type: Schema.Literal("oauth"), + refresh: Schema.String, + access: Schema.String, + expires: Schema.Number, + accountId: Schema.optional(Schema.String), + enterpriseUrl: Schema.optional(Schema.String), +}) {} + +export class Api extends Schema.Class("ApiAuth")({ + type: Schema.Literal("api"), + key: Schema.String, +}) {} + +export class WellKnown extends Schema.Class("WellKnownAuth")({ + type: Schema.Literal("wellknown"), + key: Schema.String, + token: Schema.String, +}) {} + +export const Info = Schema.Union([Oauth, Api, WellKnown]) +export type Info = Schema.Schema.Type export class AuthServiceError extends Schema.TaggedErrorClass()("AuthServiceError", { message: Schema.String, @@ -57,15 +50,17 @@ export class AuthService extends ServiceMap.Service Effect.tryPromise({ try: async () => { const data = await Filesystem.readJson>(file).catch(() => ({})) return Object.entries(data).reduce( (acc, [key, value]) => { - const parsed = Info.safeParse(value) - if (!parsed.success) return acc - acc[key] = parsed.data + const parsed = decode(value) + if (Option.isNone(parsed)) return acc + acc[key] = parsed.value return acc }, {} as Record, From 201e80956a8adf671794c8b8ef7604dbcfb50871 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Thu, 12 Mar 2026 14:23:27 -0400 Subject: [PATCH 3/5] refactor(auth): clarify auth entry filtering Use Effect Record.filterMap to keep the existing permissive auth-file semantics while making the decode path easier to read. Add service method docs that explain key normalization and why old trailing-slash variants are removed during writes. --- packages/opencode/src/auth/service.ts | 39 ++++++++++++++++++++------- 1 file changed, 29 insertions(+), 10 deletions(-) diff --git a/packages/opencode/src/auth/service.ts b/packages/opencode/src/auth/service.ts index 0898b39df7d..66d907dfb2a 100644 --- a/packages/opencode/src/auth/service.ts +++ b/packages/opencode/src/auth/service.ts @@ -1,5 +1,5 @@ import path from "path" -import { Effect, Layer, Option, Schema, ServiceMap } from "effect" +import { Effect, Layer, Record, Result, Schema, ServiceMap } from "effect" import { Global } from "../global" import { Filesystem } from "../util/filesystem" @@ -39,9 +39,36 @@ const fail = (message: string) => (cause: unknown) => new AuthServiceError({ mes export namespace AuthService { export interface Service { + /** + * Loads the auth entry stored under the given key. + * + * Keys are usually provider IDs, but some callers store URL-shaped keys. + */ readonly get: (providerID: string) => Effect.Effect + + /** + * Loads all persisted auth entries. + * + * Invalid entries are ignored instead of failing the whole file so older or + * partially-corrupt auth records do not break unrelated providers. + */ readonly all: () => Effect.Effect, AuthServiceError> + + /** + * Stores an auth entry under a normalized key. + * + * URL-shaped keys are normalized by trimming trailing slashes. Before + * writing, we delete both the original key and the normalized-with-slash + * variant so historical duplicates collapse to one canonical entry. + */ readonly set: (key: string, info: Info) => Effect.Effect + + /** + * Removes the auth entry stored under the provided key. + * + * The raw key and its normalized form are both deleted so callers can pass + * either version during cleanup. + */ readonly remove: (key: string) => Effect.Effect } } @@ -56,15 +83,7 @@ export class AuthService extends ServiceMap.Service { const data = await Filesystem.readJson>(file).catch(() => ({})) - return Object.entries(data).reduce( - (acc, [key, value]) => { - const parsed = decode(value) - if (Option.isNone(parsed)) return acc - acc[key] = parsed.value - return acc - }, - {} as Record, - ) + return Record.filterMap(data, (value) => Result.fromOption(decode(value), () => undefined)) }, catch: fail("Failed to read auth data"), }), From 11e2c85336cd79a8764b8996268469c559e6f899 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Thu, 12 Mar 2026 14:34:29 -0400 Subject: [PATCH 4/5] chore: keep effect migration plan local Remove the draft migration plan from the auth foundation branch and keep it excluded locally instead of shipping it in the PR. --- packages/opencode/EFFECT_MIGRATION_PLAN.md | 399 --------------------- 1 file changed, 399 deletions(-) delete mode 100644 packages/opencode/EFFECT_MIGRATION_PLAN.md diff --git a/packages/opencode/EFFECT_MIGRATION_PLAN.md b/packages/opencode/EFFECT_MIGRATION_PLAN.md deleted file mode 100644 index 609b1954598..00000000000 --- a/packages/opencode/EFFECT_MIGRATION_PLAN.md +++ /dev/null @@ -1,399 +0,0 @@ -# Effect migration - -Practical path for adopting Effect in opencode. - -## Aim - -Move `packages/opencode` toward Effect one domain at a time. Treat the migration as successful when the core path for a domain is Effect-based, even if temporary promise wrappers still exist at the edges. - ---- - -## Decide - -Use these defaults unless a domain gives us a good reason not to. - -- Migrate one module or domain at a time -- Preserve compatibility mainly at boundaries, not throughout internals -- Prefer adapter-layer-first work for mutable or request-scoped systems -- Treat CLI, server, and jobs as runtime boundaries -- Use the shared managed runtime only as a bridge during migration - -This keeps the work incremental and lets us remove compatibility code later instead of freezing it into every layer. - ---- - -## Slice work - -Pick migration units that can own a clear service boundary and a small runtime story. - -Good early candidates: - -- CRUD-like domains with stable storage and HTTP boundaries -- Modules that already have a natural service shape -- Areas where a promise facade can stay temporarily at the public edge - -Harder candidates: - -- `Instance`-like systems with async local state -- Request-scoped mutable state -- Modules that implicitly depend on ambient context or lifecycle ordering - ---- - -## Start at boundaries - -Begin by extracting an Effect service behind the existing module boundary. Keep old call sites working by adding a thin promise facade only where needed. - -Current example: - -- `packages/opencode/src/account/service.ts` holds the Effect-native service -- `packages/opencode/src/account/index.ts` keeps a promise-facing facade -- `packages/opencode/src/cli/cmd/account.ts` already uses `AccountService` directly -- `packages/opencode/src/config/config.ts` and `packages/opencode/src/share/share-next.ts` still use the facade - -This is the preferred first move for most domains. - ---- - -## Bridge runtime - -Use a shared app runtime only to help mixed code coexist while we migrate. Do not treat it as the final architecture by default. - -Current bridge: - -- `packages/opencode/src/effect/runtime.ts` - -Near-term rule: - -- Effect-native entrypoints can run effects directly -- Legacy promise namespaces can call into the shared runtime -- New domains should not depend on broad global runtime access unless they are explicitly boundary adapters - -As more boundaries become Effect-native, the shared runtime should shrink instead of becoming more central. - ---- - -## Handle state - -Treat async local state and mutable contextual systems as adapter problems first. Do not force `Instance`-style behavior directly into pure domain services on the first pass. - -Recommended approach: - -- Keep current mutable/contextual machinery behind a small adapter -- Expose a narrower Effect service above that adapter -- Move ambient reads and writes to the edge of the module -- Delay deeper context redesign until the boundary is stable - -For `Instance`-like code, the first win is usually isolating state access, not eliminating it. - ---- - -## Wrap `Instance` - -Keep `Instance` backed by AsyncLocalStorage for now. Do not force a full ALS replacement before we have a clearer service boundary. - -- Add an Effect-facing interface over the current ALS-backed implementation first -- Point new Effect code at that interface -- Let untouched legacy code keep using raw `Instance` - -We may split mutable state from read-only context as the design settles. If that happens, state can migrate on its own path and then depend on the Effect-facing context version instead of raw ALS directly. - -**Instance.state** - Most modules use `Instance.state()` for scoped mutable state, so we should not try to replace `Instance` itself too early. Start by wrapping it in an adapter and exposing an Effect service above the current machinery. Over time, state should move onto an Effectful abstraction of our own, with `ScopedCache` as the most likely fit for per-instance state that needs keyed lookup and cleanup. It can stay scoped by the current instance key during transition, usually the directory today, while domains can still add finer keys like `SessionID` inside their own state where needed. - -This keeps the first step small, lowers risk, and avoids redesigning request context too early. - ---- - -## Shape APIs - -Prefer an Effect-first core and a compatibility shell at the edge. - -Guidance: - -- Name the service after the domain, like `AccountService` -- Keep methods small and domain-shaped, not transport-shaped -- Return `Effect` from the core service -- Use promise helpers only in legacy namespaces or boundary adapters -- Keep error types explicit when the domain already has stable error shapes - -Small pattern: - -```ts -export class FooService extends ServiceMap.Service()("@opencode/Foo") { - static readonly layer = Layer.effect( - FooService, - Effect.gen(function* () { - return FooService.of({ - get: Effect.fn("FooService.get")(function* (id: FooID) { - return yield* ... - }), - }) - }), - ) -} -``` - -Temporary facade pattern: - -```ts -function runPromise(f: (service: FooService.Service) => Effect.Effect) { - return runtime.runPromise(FooService.use(f)) -} - -export namespace Foo { - export function get(id: FooID) { - return runPromise((service) => service.get(id)) - } -} -``` - ---- - -## Use Repo carefully - -A `Repo` layer is often useful, but it should stay a tool, not a rule. - -Tradeoffs: - -- `Repo` helps when storage concerns are real and reusable -- `Repo` can clarify error mapping and persistence boundaries -- `Repo` can also add ceremony for thin modules or one-step workflows - -Current leaning: - -- Use a `Repo` when it simplifies storage-heavy domains -- Skip it when a direct service implementation stays clearer -- Revisit consistency after a few more migrations, not before - -`packages/opencode/src/account/repo.ts` is a reasonable pattern for storage-backed domains, but it should not become mandatory yet. - ---- - -## Test safely - -Keep tests stable while internals move. Prefer preserving current test surfaces until a domain has fully crossed its main boundary. - -Practical guidance: - -- Keep existing promise-based tests passing first -- Add focused tests for new service behavior where it reduces risk -- Move boundary tests later, after the internal service shape settles -- Avoid rewriting test helpers and runtime wiring in the same PR as a domain extraction - -This lowers risk and makes the migration easier to review. - ---- - -## Roll out - -Use a phased roadmap. - -### Phase 0 - -Set conventions and prove the boundary pattern. - -- Keep `account` as the reference example, but not the template for every case -- Document the temporary runtime bridge and when to use it -- Prefer one or two more CRUD-like domains next - -### Phase 1 - -Migrate easy and medium domains one at a time. - -- Extract service -- Keep boundary facade if needed -- Convert one runtime entrypoint to direct Effect use -- Collapse internal promise plumbing inside the domain - -### Phase 2 - -Tackle context-heavy systems with adapters first. - -- Isolate async local state behind Effect-facing adapters -- Move lifecycle and mutable state reads to runtime edges -- Convert core domain logic before trying to redesign shared context - -### Phase 3 - -Reduce bridges and compatibility surfaces. - -- Remove facades that no longer serve external callers -- Narrow the shared runtime bridge -- Standardize remaining service and error shapes where it now feels earned - ---- - -## Check progress - -Use these signals to judge whether a domain is really migrated. - -A domain is in good shape when: - -- Its core logic runs through an Effect service -- Internal callers prefer the Effect API -- Compatibility wrappers exist only at real boundaries -- CLI, server, or job entrypoints can run the Effect path directly -- The shared runtime is only a temporary connector, not the center of the design - -A domain is not done just because it has an Effect service somewhere in the stack. - ---- - -## Candidate ranking - -Ranked by feasibility and payoff. Account is already migrated and serves as the reference. - -### Tier 1 — Easy wins - -| # | Module | Lines | Shape | Why | -| --- | -------------- | ----- | -------------------------------------- | -------------------------------------------------------------------------------------------------- | -| 1 | **Auth** | 74 | File CRUD (get/set/remove) | Zero ambient state, zero deps besides Filesystem. Trivial win to prove the pattern beyond account. | -| 2 | **Question** | 168 | ask/reply/reject + Instance.state Map | Clean service boundary, single pending Map. Nearly identical to Permission but simpler. | -| 3 | **Permission** | 210 | ask/respond/list + session-scoped Maps | Pending + approved Maps, already uses branded IDs. Session-scoped state maps to Effect context. | -| 4 | **Scheduler** | 62 | register/unregister tasks with timers | `Effect.repeat` / `Effect.schedule` is a natural fit. Tiny surface area. | - -### Tier 2 — Medium complexity, high payoff - -| # | Module | Lines | Shape | Why | -| --- | ---------------- | ----- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| 5 | **Pty** | 318 | Session lifecycle (create/remove/resize/write) | Process + subscriber cleanup maps to `Effect.acquireRelease`. Buffer/subscriber state is instance-scoped. | -| 6 | **Bus** | 106 | Pub/sub with instance-scoped subscriptions | Fiber-based subscription cleanup would eliminate manual `off()` patterns throughout the codebase. | -| 7 | **Snapshot** | 417 | Git snapshot/patch/restore | Heavy subprocess I/O. Effect error handling and retry would help. No ambient state. | -| 8 | **Worktree** | 673 | Git worktree create/remove/reset | Stateless, all subprocess-based. Good `Effect.fn` candidate but larger surface. | -| 9 | **Installation** | 304 | Version check + upgrade across package managers | Multiple fallback paths (npm/brew/choco/scoop). Effect's error channel shines here. | - -### Tier 3 — Harder, migrate after patterns are settled - -| # | Module | Lines | Shape | Why | -| --- | -------- | ----- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| 10 | **File** | 655 | File ops with cache state | Background fetch side-effects would benefit from Fiber management. Mutable cache (files/dirs Maps) adds complexity. | -| 11 | **LSP** | 487 | Client lifecycle: spawning → connected → broken | Effect resource management fits, but multi-state transitions are tricky. | -| 12 | **MCP** | 981 | Client lifecycle + OAuth flows | Largest single module. OAuth state spans multiple functions (startAuth → finishAuth). High payoff but highest risk. | - -### Avoid early - -These are too large, too foundational, or too pervasive to migrate without significant prior experience: - -- **Provider** (~1400 lines) — provider-specific branching, AI SDK abstractions, complex model selection -- **Session** (~900 lines) — complex relational queries, branching logic, many dependents -- **Config** — pervasive dependency across codebase, complex precedence rules -- **Project / Instance** — foundational bootstrap, async local state, everything depends on it - -### Patterns to watch for - -**Instance.state** — Most modules use `Instance.state()` for scoped mutable state. Don't try to replace Instance itself early; wrap it in an adapter that exposes an Effect service above the existing machinery. - -**Bus.subscribe + manual off()** — Pervasive throughout the codebase. Migrating Bus (candidate #6) unlocks Fiber-based cleanup everywhere, but it's infrastructure, not a domain win. Consider it after a few domain migrations prove the pattern. - -**Database.use / Database.transaction** — Already resembles Effect context (provide/use pattern). Could become an Effect Layer, but this is infrastructure work best deferred until multiple domains are Effect-native. - -**Process subprocess patterns** — Snapshot, Worktree, Installation all shell out to git or package managers. These are natural `Effect.tryPromise` / `Effect.fn` targets with error mapping. - ---- - -## Effect modules to use - -Effect already provides battle-tested replacements for several homegrown patterns. Prefer these over custom code as domains migrate. - -### PubSub → replaces Bus - -`PubSub` provides bounded/unbounded pub/sub with backpressure strategies. Subscriptions are scoped — cleanup is automatic when the subscriber's Scope closes, eliminating every manual `off()` call. - -```ts -const pubsub = yield * PubSub.unbounded() -yield * PubSub.publish(pubsub, event) -// subscriber — automatically cleaned up when scope ends -const dequeue = yield * PubSub.subscribe(pubsub) -const event = yield * Queue.take(dequeue) -``` - -Don't migrate Bus first. Migrate domain modules, then swap Bus once there are enough Effect-native consumers. - -### Schedule → replaces Scheduler - -The custom 62-line Scheduler reinvents `Effect.repeat`. Effect's `Schedule` is composable and supports spaced intervals, exponential backoff, cron expressions, and more. - -```ts -yield * effect.pipe(Effect.repeat(Schedule.spaced("30 seconds"))) -``` - -### SubscriptionRef → replaces state + Bus.publish on mutation - -Several modules follow the pattern: mutate `Instance.state`, then `Bus.publish` to notify listeners. `SubscriptionRef` is a `Ref` that emits changes as a `Stream`, combining both in one primitive. - -```ts -const ref = yield * SubscriptionRef.make(initialState) -// writer -yield * SubscriptionRef.update(ref, (s) => ({ ...s, count: s.count + 1 })) -// reader — stream of every state change -yield * SubscriptionRef.changes(ref).pipe(Stream.runForEach(handleUpdate)) -``` - -### Ref / SynchronizedRef → replaces Instance.state Maps - -`Ref` provides atomic read/write/update for concurrent-safe state. `SynchronizedRef` adds mutual exclusion for complex multi-step updates. Use these inside Effect services instead of raw mutable Maps. - -### Scope + acquireRelease → replaces manual resource cleanup - -Pty sessions, LSP clients, and MCP clients all have manual try/finally cleanup. `Effect.acquireRelease` ties resource lifecycle to Scope, making cleanup declarative and leak-proof. - -```ts -const pty = yield * Effect.acquireRelease(createPty(options), (session) => destroyPty(session)) -``` - -### ChildProcess → replaces shell-outs - -Effect's `ChildProcess` provides type-safe subprocess execution with template literals and stream-based stdout/stderr. Useful for Snapshot, Worktree, and Installation modules. - -```ts -const result = yield * ChildProcess.make`git diff --stat`.pipe(ChildProcess.spawn, ChildProcess.string) -``` - -Note: in `effect/unstable/process` — API may shift. - -### FileSystem → replaces custom Filesystem utils - -Cross-platform file I/O with stream support. Available via `effect/FileSystem` with a `NodeFileSystem` layer. - -### KeyValueStore → replaces file-based Auth JSON - -Abstracted key-value storage with file, memory, and browser backends. Auth's 74-line file CRUD could become a one-liner with `KeyValueStore`. - -Available via `effect/unstable/persistence` — API may shift. - -### HttpClient → replaces custom fetch calls - -Full HTTP client with typed errors, request builders, and platform-aware layers. Useful when migrating Share and ControlPlane modules. - -Available via `effect/unstable/http` — API may shift. - -### HttpApi → replaces Hono - -Effect's `HttpApi` provides schema-driven HTTP APIs with OpenAPI generation, type-safe routing, and middleware. Long-term candidate to replace the Hono server layer entirely. This is a larger lift — defer until multiple domain services are Effect-native and the boundary pattern is well-proven. - -Available via `effect/unstable/httpapi` — API may shift. - -### Schema → replaces Zod (partially) - -Effect's `Schema` provides encoding/decoding, validation, and type derivation deeply integrated with Effect. Internal code can migrate to Schema as domains move to Effect services. However, the plugin API (`@opencode-ai/plugin`) uses Zod and must continue to accept Zod schemas at the boundary. Keep Zod-to-Schema bridges at plugin/SDK edges. - -### Cache → replaces manual caching - -The File module maintains mutable Maps (files/dirs) with a fetching flag for deduplication. `Cache` provides memoization with TTL and automatic deduplication, replacing this pattern. - -### Pool → for resource-heavy clients - -LSP client management (spawning/connected/broken state machine) could benefit from `Pool` for automatic acquisition, health checking, and release. - ---- - -## Follow next - -Recommended medium-term order: - -1. Continue with CRUD-like or storage-backed modules -2. Convert boundary entrypoints in CLI, server, and jobs as services become available -3. Move into `Instance`-adjacent systems with adapter layers, not direct rewrites -4. Remove promise facades after direct callers have moved - -This keeps momentum while reserving the hardest context work for when the team has a clearer house style. From 1739817ee7908ad5ac929e10fce839d76ac113f7 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Thu, 12 Mar 2026 14:38:44 -0400 Subject: [PATCH 5/5] style(auth): remove service docstrings Drop the temporary auth service method comments now that the key normalization behavior has been reviewed. --- packages/opencode/src/auth/service.ts | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/packages/opencode/src/auth/service.ts b/packages/opencode/src/auth/service.ts index 66d907dfb2a..100a132b873 100644 --- a/packages/opencode/src/auth/service.ts +++ b/packages/opencode/src/auth/service.ts @@ -39,36 +39,9 @@ const fail = (message: string) => (cause: unknown) => new AuthServiceError({ mes export namespace AuthService { export interface Service { - /** - * Loads the auth entry stored under the given key. - * - * Keys are usually provider IDs, but some callers store URL-shaped keys. - */ readonly get: (providerID: string) => Effect.Effect - - /** - * Loads all persisted auth entries. - * - * Invalid entries are ignored instead of failing the whole file so older or - * partially-corrupt auth records do not break unrelated providers. - */ readonly all: () => Effect.Effect, AuthServiceError> - - /** - * Stores an auth entry under a normalized key. - * - * URL-shaped keys are normalized by trimming trailing slashes. Before - * writing, we delete both the original key and the normalized-with-slash - * variant so historical duplicates collapse to one canonical entry. - */ readonly set: (key: string, info: Info) => Effect.Effect - - /** - * Removes the auth entry stored under the provided key. - * - * The raw key and its normalized form are both deleted so callers can pass - * either version during cleanup. - */ readonly remove: (key: string) => Effect.Effect } }