@miaws/miaw 1.18.5 → 1.18.7

package/specs/effect/guide.md

@@ -1,247 +0,0 @@
-# Effect Guide
-
-How we write Effect code in `packages/miaw`. 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>()("@miaw/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 miaw 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/miaw`:
-
-```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

@@ -1,13 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-# 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

@@ -1,61 +0,0 @@
-# HTTP Route Patterns
-
-Current guidance for `packages/miaw/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

@@ -1,88 +0,0 @@
-# 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

@@ -1,58 +0,0 @@
-# Server Package Extraction
-
-Practical reference for a future `packages/server` split after the miaw
-server moved to the Effect HttpApi backend.
-
-## Current State
-
-- The server still lives in `packages/miaw`.
-- 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/miaw`, a future
-`packages/server` should either:
-
-- own pure HttpApi contracts only, or
-- accept host-provided services/layers/callbacks from `packages/miaw`
-
-It should not import `packages/miaw` services while `packages/miaw`
-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 miaw-local runtime modules.
-3. Extract pure HttpApi contract modules into `packages/server` once the contract
-   can compile without importing `packages/miaw` 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.