@miaws/miaw 1.18.3 → 1.18.5

package/script/trace-imports.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env bun
+import * as path from "path"
+import * as ts from "typescript"
+
+const BASE_DIR = "/home/thdxr/dev/projects/anomalyco/miaw/packages/miaw"
+
+// Get entry file from command line arg or use default
+const ENTRY_FILE = process.argv[2] || "src/plugin/tui/runtime.ts"
+
+const visited = new Set<string>()
+
+function resolveImport(importPath: string, fromFile: string): string | null {
+  if (importPath.startsWith("@/")) {
+    return path.join(BASE_DIR, "src", importPath.slice(2))
+  }
+
+  if (importPath.startsWith("./") || importPath.startsWith("../")) {
+    const dir = path.dirname(fromFile)
+    return path.resolve(dir, importPath)
+  }
+
+  return null
+}
+
+function isInternalImport(importPath: string): boolean {
+  return importPath.startsWith("@/") || importPath.startsWith("./") || importPath.startsWith("../")
+}
+
+async function tryExtensions(filePath: string): Promise<string | null> {
+  const extensions = [".ts", ".tsx", ".js", ".jsx"]
+
+  try {
+    const file = Bun.file(filePath)
+    const stat = await file.stat()
+
+    if (stat?.isDirectory()) {
+      for (const ext of extensions) {
+        const indexPath = path.join(filePath, "index" + ext)
+        const indexFile = Bun.file(indexPath)
+        if (await indexFile.exists()) return indexPath
+      }
+      return null
+    }
+
+    // It's a file
+    return filePath
+  } catch {
+    // Path doesn't exist, try adding extensions
+    for (const ext of extensions) {
+      const withExt = filePath + ext
+      const extFile = Bun.file(withExt)
+      if (await extFile.exists()) return withExt
+    }
+    return null
+  }
+}
+
+function extractImports(sourceFile: ts.SourceFile): string[] {
+  const imports: string[] = []
+
+  function visit(node: ts.Node) {
+    // import x from "path" or import { x } from "path"
+    if (ts.isImportDeclaration(node)) {
+      // Skip type-only imports
+      if (node.importClause?.isTypeOnly) return
+
+      const moduleSpec = node.moduleSpecifier
+      if (ts.isStringLiteral(moduleSpec)) {
+        imports.push(moduleSpec.text)
+      }
+    }
+
+    // export { x } from "path"
+    if (ts.isExportDeclaration(node) && node.moduleSpecifier) {
+      if (ts.isStringLiteral(node.moduleSpecifier)) {
+        imports.push(node.moduleSpecifier.text)
+      }
+    }
+
+    // Dynamic import: import("path")
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const arg = node.arguments[0]
+      if (arg && ts.isStringLiteral(arg)) {
+        imports.push(arg.text)
+      }
+    }
+
+    ts.forEachChild(node, visit)
+  }
+
+  visit(sourceFile)
+  return imports
+}
+
+async function traceFile(filePath: string, depth = 0): Promise<void> {
+  const normalizedPath = path.relative(BASE_DIR, filePath)
+
+  if (visited.has(filePath)) {
+    return
+  }
+
+  // Only trace TypeScript/JavaScript files
+  if (!filePath.match(/\.(ts|tsx|js|jsx)$/)) {
+    return
+  }
+
+  visited.add(filePath)
+  console.log("\t".repeat(depth) + normalizedPath)
+
+  let content: string
+  try {
+    content = await Bun.file(filePath).text()
+  } catch {
+    return
+  }
+
+  const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true)
+
+  const imports = extractImports(sourceFile)
+  const internalImports = imports.filter(isInternalImport)
+  const externalImports = imports.filter((imp) => !isInternalImport(imp))
+
+  // Print external imports
+  for (const imp of externalImports) {
+    console.log("\t".repeat(depth + 1) + `[ext] ${imp}`)
+  }
+
+  for (const imp of internalImports) {
+    const resolved = resolveImport(imp, filePath)
+    if (!resolved) continue
+
+    const actualPath = await tryExtensions(resolved)
+    if (!actualPath) continue
+
+    await traceFile(actualPath, depth + 1)
+  }
+}
+
+async function main() {
+  const entryPath = path.join(BASE_DIR, ENTRY_FILE)
+
+  // Check if file exists
+  const file = Bun.file(entryPath)
+  if (!(await file.exists())) {
+    console.error(`File not found: ${ENTRY_FILE}`)
+    console.error(`Resolved to: ${entryPath}`)
+    process.exit(1)
+  }
+
+  await traceFile(entryPath)
+}
+
+main().catch(console.error)

package/specs/effect/error-boundaries-plan.md

@@ -0,0 +1,235 @@
+# Error Boundaries Plan
+
+Plan for removing `NamedError` as connective tissue while keeping public
+wire contracts stable.
+
+## Desired Shape
+
+```text
+Domain/service error
+  Schema.TaggedErrorClass
+  - catchable with catchTag / catchTags
+  - appears in service method error type
+  - no HTTP status
+  - no toObject()
+
+HTTP public error
+  Schema.ErrorClass / TaggedErrorClass with httpApiStatus
+  - endpoint-declared public contract
+  - owns legacy { name, data } only when that is the SDK wire shape
+
+CLI/user rendering
+  FormatError and small format helpers
+  - converts domain errors to text
+  - preserves useful structured fields
+
+Session/model-visible error
+  first-class session/message error schema or helper
+  - owns { name, data } event/message shape
+  - not a service error class
+```
+
+The important rule: a service error should not also be the HTTP body, CLI
+formatter, and session event body. Each seam adapts the error into the
+shape it owns.
+
+## Concrete Example: Provider Model Not Found
+
+Before:
+
+```ts
+export const ModelNotFoundError = NamedError.create("ProviderModelNotFoundError", {
+  providerID: ProviderID,
+  modelID: ModelID,
+  suggestions: Schema.optional(Schema.Array(Schema.String)),
+})
+```
+
+Problems:
+
+- Throwing it inside `Effect.fn` made it behave like a defect unless a
+  compatibility bridge caught it.
+- HTTP middleware knew that this one domain error should be a `400`.
+- Callers read `.data.*`, which couples them to the legacy `{ name, data }`
+  wire shape.
+
+After:
+
+```ts
+export class ModelNotFoundError extends Schema.TaggedErrorClass<ModelNotFoundError>()("ProviderModelNotFoundError", {
+  providerID: ProviderID,
+  modelID: ModelID,
+  suggestions: Schema.optional(Schema.Array(Schema.String)),
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+export interface Interface {
+  readonly getModel: (providerID: ProviderID, modelID: ModelID) => Effect.Effect<Model, ModelNotFoundError>
+}
+```
+
+Boundary adapters:
+
+```text
+CLI
+└─ FormatError sees _tag ProviderModelNotFoundError -> nice text
+
+Session prompt
+└─ catch ModelNotFoundError -> publish Session.Event.Error as message/session wire shape
+
+HTTP route
+└─ catch ModelNotFoundError -> declared BadRequest public API error when the endpoint needs it
+
+HTTP middleware
+└─ no Provider.ModelNotFoundError knowledge
+```
+
+## Refining Known Promise Failures
+
+Use `EffectPromise.refineRejection(...)` when a Promise boundary can reject
+with many unknown values, but only one or two rejection classes are expected
+domain failures. Unknown rejections stay defects; the helper maps only known
+rejection shapes to typed errors.
+
+```ts
+const language =
+  yield *
+  EffectPromise.refineRejection(
+    async () => loadFromProvider(),
+    (cause) => (cause instanceof NoSuchModelError ? new ModelNotFoundError({ providerID, modelID, cause }) : undefined),
+  )
+```
+
+Use this when the Promise can genuinely reject and most rejection values are
+still defects for the current module. Use `Effect.tryPromise({ try, catch })`
+when every rejection should become the same expected error type. Use
+`Effect.promise(...)` only when rejection means a defect and you do not need
+to refine known rejection classes.
+
+## Helper Modules We Probably Want
+
+Add helpers only when repeated call sites prove the seam is real.
+
+### HTTP API Errors
+
+Likely location: `src/server/routes/instance/httpapi/errors.ts`.
+
+Purpose:
+
+- construct public HTTP error bodies
+- preserve legacy `{ name, data }` where needed
+- attach `httpApiStatus`
+
+Good helpers:
+
+```ts
+notFound(message)
+badRequest(message)
+unknown()
+```
+
+Avoid:
+
+```ts
+mapAnyDomainError(error)
+```
+
+That recreates the giant middleware mapper problem.
+
+### Session / Message Error Wire Helpers
+
+Likely location: near `src/session/message-error.ts` or a new narrow
+module such as `src/session/event-error.ts`.
+
+Purpose:
+
+- construct the `{ name, data }` shape used by `Session.Event.Error` and
+  assistant message errors
+- replace `new NamedError.Unknown(...).toObject()` call sites
+- keep model-visible error bodies separate from service/domain errors
+
+Good helpers:
+
+```ts
+unknown(message)
+agentNotFound(agent, available)
+commandNotFound(command, available)
+modelNotFound(error: Provider.ModelNotFoundError)
+```
+
+### CLI Formatters
+
+Likely location: `src/cli/error.ts` until repetition demands domain-local
+format helpers.
+
+Purpose:
+
+- produce human-readable terminal messages from typed errors
+- support old `{ name, data }` shapes only while compatibility is needed
+
+## Migration Queue
+
+### Remove Domain Knowledge From HTTP Middleware
+
+- [x] Storage not found no longer maps through defect fallback.
+- [x] Worktree expected errors moved to typed errors.
+- [x] Provider auth expected errors moved to typed errors.
+- [x] Provider model not found no longer needs an HTTP middleware status
+      special case.
+- [ ] Convert `Session.BusyError` and map it at route boundaries.
+- [ ] Delete the broad `NamedError` middleware branch once no route relies
+      on defect-wrapped legacy domain errors.
+- [ ] Keep one final unknown-defect fallback that logs `Cause.pretty(cause)`
+      and returns a safe `500` body.
+
+### Remaining `NamedError.create(...)` Service Errors
+
+These should become `Schema.TaggedErrorClass` when touched:
+
+- [ ] `src/provider/provider.ts` — `ProviderInitError`.
+- [ ] `src/storage/db.ts` — database `NotFoundError`.
+- [ ] `src/mcp/index.ts` — `MCPFailed`.
+- [ ] `src/skill/index.ts` — `SkillInvalidError`,
+      `SkillNameMismatchError`.
+- [ ] `src/lsp/client.ts` — `LSPInitializeError`.
+- [ ] `src/ide/index.ts` — install errors.
+- [ ] `src/config/error.ts`, `src/config/config.ts`,
+      `src/config/markdown.ts` — config errors. These already render well
+      in the CLI, so migrate carefully and preserve diagnostics.
+
+### Session / Message Wire Errors
+
+These are not ordinary service errors. They mostly build `{ name, data }`
+objects for model-visible/session-visible output.
+
+- [ ] Add a first-class session/message error wire helper.
+- [ ] Replace `new NamedError.Unknown(...).toObject()` in
+      `src/session/prompt.ts`.
+- [ ] Replace `new NamedError.Unknown(...).toObject()` in config/skill/plugin
+      session event publishing.
+- [ ] Move `src/session/message-error.ts` and `src/session/message-v2.ts`
+      away from `NamedError.create(...)` once the wire helper exists.
+- [ ] Update retry/message tests to assert the wire schema/helper output,
+      not `NamedError` instances.
+
+### CLI Rendering
+
+- [x] Tagged config errors render with useful diagnostics.
+- [x] Provider model not found renders from both old `{ name, data }` and
+      new `_tag` shapes.
+- [ ] Add typed render cases as more `NamedError.create(...)` domains move
+      to `Schema.TaggedErrorClass`.
+- [ ] Eventually remove old-shape compatibility branches when no callers can
+      produce them.
+
+## PR Checklist
+
+For each migrated error:
+
+- [ ] Domain error is `Schema.TaggedErrorClass`.
+- [ ] Service method exposes the typed error in its error channel.
+- [ ] No service error has `toObject()` just for compatibility.
+- [ ] CLI, HTTP, and session/message adapters each own their output shape.
+- [ ] HTTP middleware gets smaller or stays unchanged.
+- [ ] Focused tests cover the domain error and any public rendering/wire
+      shape touched by the PR.

package/specs/effect/errors.md

@@ -0,0 +1,207 @@
+# Typed Error Migration
+
+This note expands the `ERR`, `RENDER`, and `HTTP` tracks from
+[`todo.md`](./todo.md). It is the current reference for expected failures,
+typed service errors, and HTTP error boundaries.
+
+For the migration architecture and queue, see
+[`error-boundaries-plan.md`](./error-boundaries-plan.md).
+
+## Goal
+
+- Expected service failures live on the Effect error channel.
+- Service interfaces expose those failures in their return types.
+- Domain errors are authored with `Schema.TaggedErrorClass`.
+- `Effect.die(...)` is reserved for defects: bugs, impossible states,
+  violated invariants, and final unknown-boundary fallbacks.
+- HTTP status codes and public wire bodies are handled at HTTP route
+  boundaries, not inside service modules.
+- User-facing boundaries render useful structured error details instead of
+  opaque `Error: SomeName` strings.
+
+## Service Error Shape
+
+```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 expected domain failures.
+- Export a domain-level `Error` union from each service module.
+- Put expected errors in service method signatures.
+- Use `yield* new DomainError(...)` for direct early failures in
+  `Effect.gen` / `Effect.fn`.
+- Use `Schema.Defect` for unknown cause fields when preserving the cause is
+  useful for logs or callers.
+- Use `Effect.try(...)`, `Effect.tryPromise(...)`, `Effect.mapError`,
+  `Effect.catchTag`, and `Effect.catchTags` to translate external
+  failures into domain errors.
+- Do not use `throw`, `Effect.die(...)`, or `catchDefect` for expected
+  user, IO, validation, missing-resource, auth, provider, worktree, or
+  busy-state failures.
+
+## HTTP Boundary Shape
+
+Service modules stay transport-agnostic. They should not import HTTP
+status codes, `HttpApiError`, `HttpServerResponse`, or route-specific
+error schemas.
+
+HTTP handlers translate service errors into public endpoint errors:
+
+```ts
+const get = Effect.fn("SessionHttpApi.get")(function* (ctx: { params: { sessionID: SessionID } }) {
+  return yield* session
+    .get(ctx.params.sessionID)
+    .pipe(Effect.catchTag("StorageNotFoundError", () => notFound("Session not found")))
+})
+```
+
+Endpoint definitions declare which public errors can be emitted. Public
+HTTP error schemas carry their response status with `httpApiStatus` or the
+equivalent HttpApi schema annotation.
+
+Effect's own HttpApi examples follow this pattern:
+
+```ts
+export class Unauthorized extends Schema.TaggedErrorClass<Unauthorized>()(
+  "Unauthorized",
+  { message: Schema.String },
+  { httpApiStatus: 401 },
+) {}
+
+export class Authorization extends HttpApiMiddleware.Service<
+  Authorization,
+  {
+    provides: CurrentUser
+  }
+>()("app/Authorization", {
+  security: { bearer: HttpApiSecurity.bearer },
+  error: Unauthorized,
+}) {}
+```
+
+Endpoint-level errors use the same idea:
+
+```ts
+export class ConfigApiError extends Schema.ErrorClass<ConfigApiError>("ConfigApiError")(
+  {
+    name: Schema.Union(Schema.Literal("ConfigInvalidError"), Schema.Literal("ConfigJsonError")),
+    data: Schema.Struct({ message: Schema.optional(Schema.String), path: Schema.String }),
+  },
+  { httpApiStatus: 400 },
+) {}
+
+HttpApiEndpoint.get("get", "/config", {
+  success: Config.Info,
+  error: ConfigApiError,
+})
+```
+
+The service error and HTTP error may be the same class only when the wire
+shape is intentionally public. Use separate HTTP error schemas when the
+service error contains internals, low-level causes, retry hints, or data
+that should not be exposed to API clients.
+
+Do not map every domain error into one universal HTTP error class. Prefer a
+small public error vocabulary by route group: shared shapes like
+`ApiNotFoundError`, route-specific shapes like `ConfigApiError`, and built-in
+empty `HttpApiError.*` only when an empty/no-content body is the intended SDK
+contract.
+
+## Mapping Guidance
+
+- Keep one-off translations inline in the handler.
+- Extract tiny shared helpers when the same translation repeats across a
+  route group.
+- Do not create one giant `unknown -> status` mapper.
+- Do not grow generic HTTP middleware into a registry of domain errors.
+- Preserve existing public `{ name, data }` bodies until a deliberate
+  breaking API change.
+- Use built-in `HttpApiError.*` only when its generated body and SDK
+  surface are intentionally the public contract.
+- Prefer `Schema.ErrorClass` for public HTTP error bodies whose wire shape is
+  not the same as the internal domain error shape.
+- Prefer `Schema.TaggedErrorClass` for service/domain errors and middleware
+  errors that are naturally tagged by `_tag`.
+- If preserving a legacy `{ name, data }` body, model that shape explicitly in
+  the public API error schema instead of relying on `NamedError.toObject()` in
+  generic middleware.
+
+## User-Facing Rendering
+
+HTTP serialization and user rendering are separate boundaries. The server
+should send structured public errors; CLI and TUI code should format those
+structures through one shared formatter.
+
+For SDK calls using `{ throwOnError: true }`, the generated client may wrap the
+decoded response body in an `Error`. The original body should remain available
+under `error.cause.body`; `FormatError` is the right place to unwrap and render
+that body. TUI aggregation helpers should call `FormatError` first, then fall
+back to generic `Error.message` / string rendering.
+
+When several parallel startup requests fail from the same underlying issue,
+group identical rendered messages and list the affected request names once.
+For example:
+
+```text
+Configuration is invalid at /path/to/miaw.json
+↳ Expected object, got "not-object" provider.bad.options
+Affected startup requests: config.providers, provider.list, app.agents, config.get
+```
+
+## Middleware Guidance
+
+HTTP middleware should be cross-cutting: auth, context, schema decode
+formatting, routing, and final unknown-defect fallback.
+
+The current compatibility middleware still knows about some legacy domain
+errors. As route groups declare expected errors and handlers map them, that
+middleware should shrink. It should not gain new name checks.
+
+Unknown `500` responses should log full details server-side with
+`Cause.pretty(cause)` and return a safe public body.
+
+The config startup regression in #27056 is the failure mode this rule is meant
+to avoid: a user-authored invalid `miaw.json` crossed the HttpApi boundary
+as a defect, so middleware replaced a useful `ConfigInvalidError` with a safe
+generic `UnknownError`. The compatibility fix is to preserve config parse and
+validation errors as client-visible `400`s. The target architecture is better:
+config loading should fail on the typed error channel, config HTTP handlers
+should map those errors to declared `ConfigApiError` responses, and the generic
+middleware should never see them.
+
+## Migration Order
+
+Prefer small vertical slices:
+
+1. Fix rendering at one user-visible boundary.
+2. Convert one service domain to `Schema.TaggedErrorClass` errors.
+3. Map those errors at the affected HTTP handlers.
+4. Remove the corresponding name-based middleware branch if possible.
+5. Add or update focused tests for both service error tags and HTTP wire
+   bodies.
+
+Good early domains are storage not-found, worktree errors, and provider
+auth validation errors because they currently drive HTTP behavior.
+
+Config parse and validation errors are also a good early slice because they
+are startup-blocking and must be rendered clearly in both CLI and TUI flows.
+
+## Checklist For A PR
+
+- [ ] Expected failures are typed errors, not defects.
+- [ ] Service method signatures expose the expected error union.
+- [ ] HTTP handlers translate domain errors at the boundary.
+- [ ] Public HTTP error bodies preserve existing wire contracts.
+- [ ] Generic middleware gets smaller or stays unchanged.
+- [ ] Focused tests cover the service error and any public HTTP response.