imposters 0.1.0

package/src/repositories/ImposterRepository.ts

@@ -0,0 +1,145 @@
+import { Context, Data, Effect, HashMap, Layer, Ref } from "effect"
+import type { ImposterConfig } from "../domain/imposter"
+import { ImposterNotFoundError } from "../domain/imposter"
+import type { Stub } from "../schemas/StubSchema"
+
+export class StubNotFoundError extends Data.TaggedError("StubNotFoundError")<{
+  readonly imposterId: string
+  readonly stubId: string
+}> {}
+
+export interface ImposterRecord {
+  readonly config: ImposterConfig
+  readonly stubs: ReadonlyArray<Stub>
+}
+
+export interface ImposterRepositoryShape {
+  readonly create: (config: ImposterConfig) => Effect.Effect<ImposterRecord>
+  readonly get: (id: string) => Effect.Effect<ImposterRecord, ImposterNotFoundError>
+  readonly getAll: Effect.Effect<ReadonlyArray<ImposterRecord>>
+  readonly update: (
+    id: string,
+    fn: (r: ImposterRecord) => ImposterRecord
+  ) => Effect.Effect<ImposterRecord, ImposterNotFoundError>
+  readonly remove: (id: string) => Effect.Effect<ImposterRecord, ImposterNotFoundError>
+  readonly addStub: (imposterId: string, stub: Stub) => Effect.Effect<Stub, ImposterNotFoundError>
+  readonly getStubs: (imposterId: string) => Effect.Effect<ReadonlyArray<Stub>, ImposterNotFoundError>
+  readonly updateStub: (
+    imposterId: string,
+    stubId: string,
+    fn: (s: Stub) => Stub
+  ) => Effect.Effect<Stub, ImposterNotFoundError | StubNotFoundError>
+  readonly removeStub: (
+    imposterId: string,
+    stubId: string
+  ) => Effect.Effect<Stub, ImposterNotFoundError | StubNotFoundError>
+}
+
+export class ImposterRepository extends Context.Tag("ImposterRepository")<
+  ImposterRepository,
+  ImposterRepositoryShape
+>() {}
+
+export const ImposterRepositoryLive = Layer.effect(
+  ImposterRepository,
+  Effect.gen(function*() {
+    const storeRef = yield* Ref.make(HashMap.empty<string, ImposterRecord>())
+
+    const getRecord = (id: string): Effect.Effect<ImposterRecord, ImposterNotFoundError> =>
+      Ref.get(storeRef).pipe(
+        Effect.flatMap((store) => {
+          const record = HashMap.get(store, id)
+          return record._tag === "Some"
+            ? Effect.succeed(record.value)
+            : Effect.fail(new ImposterNotFoundError({ id }))
+        })
+      )
+
+    type Store = HashMap.HashMap<string, ImposterRecord>
+    type ModifyRecord<A, E> = readonly [Effect.Effect<A, E>, Store]
+    type RecordResult = ModifyRecord<ImposterRecord, ImposterNotFoundError>
+    type StubResult = ModifyRecord<Stub, ImposterNotFoundError>
+    type StubOrNotFound = ModifyRecord<Stub, ImposterNotFoundError | StubNotFoundError>
+
+    const create = (config: ImposterConfig): Effect.Effect<ImposterRecord> => {
+      const record: ImposterRecord = { config, stubs: [] }
+      return Ref.modify(
+        storeRef,
+        (store): ModifyRecord<ImposterRecord, never> => [Effect.succeed(record), HashMap.set(store, config.id, record)]
+      ).pipe(Effect.flatten)
+    }
+
+    const get = (id: string) => getRecord(id)
+
+    const getAll: Effect.Effect<ReadonlyArray<ImposterRecord>> = Ref.get(storeRef).pipe(
+      Effect.map((store) => Array.from(HashMap.values(store)))
+    )
+
+    const update = (id: string, fn: (r: ImposterRecord) => ImposterRecord) =>
+      Ref.modify(storeRef, (store): RecordResult => {
+        const existing = HashMap.get(store, id)
+        if (existing._tag === "None") {
+          return [Effect.fail(new ImposterNotFoundError({ id })), store]
+        }
+        const updated = fn(existing.value)
+        return [Effect.succeed(updated), HashMap.set(store, id, updated)]
+      }).pipe(Effect.flatten)
+
+    const remove = (id: string) =>
+      Ref.modify(storeRef, (store): RecordResult => {
+        const existing = HashMap.get(store, id)
+        if (existing._tag === "None") {
+          return [Effect.fail(new ImposterNotFoundError({ id })), store]
+        }
+        return [Effect.succeed(existing.value), HashMap.remove(store, id)]
+      }).pipe(Effect.flatten)
+
+    const addStub = (imposterId: string, stub: Stub) =>
+      Ref.modify(storeRef, (store): StubResult => {
+        const existing = HashMap.get(store, imposterId)
+        if (existing._tag === "None") {
+          return [Effect.fail(new ImposterNotFoundError({ id: imposterId })), store]
+        }
+        const updated: ImposterRecord = { ...existing.value, stubs: [...existing.value.stubs, stub] }
+        return [Effect.succeed(stub), HashMap.set(store, imposterId, updated)]
+      }).pipe(Effect.flatten)
+
+    const getStubs = (imposterId: string) => getRecord(imposterId).pipe(Effect.map((r) => r.stubs))
+
+    const updateStub = (imposterId: string, stubId: string, fn: (s: Stub) => Stub) =>
+      Ref.modify(storeRef, (store): StubOrNotFound => {
+        const existing = HashMap.get(store, imposterId)
+        if (existing._tag === "None") {
+          return [Effect.fail(new ImposterNotFoundError({ id: imposterId })), store]
+        }
+        const stubIndex = existing.value.stubs.findIndex((s) => s.id === stubId)
+        if (stubIndex === -1) {
+          return [Effect.fail(new StubNotFoundError({ imposterId, stubId })), store]
+        }
+        const updatedStub = fn(existing.value.stubs[stubIndex]!)
+        const newStubs = [...existing.value.stubs]
+        newStubs[stubIndex] = updatedStub
+        const updated: ImposterRecord = { ...existing.value, stubs: newStubs }
+        return [Effect.succeed(updatedStub), HashMap.set(store, imposterId, updated)]
+      }).pipe(Effect.flatten)
+
+    const removeStub = (imposterId: string, stubId: string) =>
+      Ref.modify(storeRef, (store): StubOrNotFound => {
+        const existing = HashMap.get(store, imposterId)
+        if (existing._tag === "None") {
+          return [Effect.fail(new ImposterNotFoundError({ id: imposterId })), store]
+        }
+        const stub = existing.value.stubs.find((s) => s.id === stubId)
+        if (!stub) {
+          return [Effect.fail(new StubNotFoundError({ imposterId, stubId })), store]
+        }
+        const updated: ImposterRecord = {
+          ...existing.value,
+          stubs: existing.value.stubs.filter((s) => s.id !== stubId)
+        }
+        return [Effect.succeed(stub), HashMap.set(store, imposterId, updated)]
+      }).pipe(Effect.flatten)
+
+    return { create, get, getAll, update, remove, addStub, getStubs, updateStub, removeStub }
+  })
+)

package/src/schemas/ConfigFileSchema.ts

@@ -0,0 +1,32 @@
+import * as Schema from "effect/Schema"
+import { NonEmptyString, PortNumber } from "./common"
+import { CreateStubRequest, ProxyConfig } from "./StubSchema"
+
+export const ImposterConfig = Schema.Struct({
+  name: Schema.optional(NonEmptyString),
+  port: PortNumber,
+  stubs: Schema.optionalWith(Schema.Array(CreateStubRequest), { default: () => [] }),
+  proxy: Schema.optional(ProxyConfig)
+})
+export type ImposterConfig = Schema.Schema.Type<typeof ImposterConfig>
+
+export const AdminConfig = Schema.Struct({
+  port: Schema.optionalWith(PortNumber, { default: () => 2525 as Schema.Schema.Type<typeof PortNumber> }),
+  portRangeMin: Schema.optionalWith(PortNumber, { default: () => 3000 as Schema.Schema.Type<typeof PortNumber> }),
+  portRangeMax: Schema.optionalWith(PortNumber, { default: () => 4000 as Schema.Schema.Type<typeof PortNumber> }),
+  maxImposters: Schema.optionalWith(
+    Schema.Number.pipe(Schema.int(), Schema.positive()),
+    { default: () => 100 }
+  ),
+  logLevel: Schema.optionalWith(
+    Schema.Literal("debug", "info", "warn", "error"),
+    { default: () => "info" as const }
+  )
+})
+export type AdminConfig = Schema.Schema.Type<typeof AdminConfig>
+
+export const ConfigFile = Schema.Struct({
+  admin: Schema.optionalWith(AdminConfig, { default: () => Schema.decodeSync(AdminConfig)({}) }),
+  imposters: Schema.optionalWith(Schema.Array(ImposterConfig), { default: () => [] })
+})
+export type ConfigFile = Schema.Schema.Type<typeof ConfigFile>

package/src/schemas/ImposterSchema.ts

@@ -0,0 +1,232 @@
+import * as Schema from "effect/Schema"
+import {
+  ImposterStatus,
+  NonEmptyString,
+  PaginationMeta,
+  PaginationQuery,
+  PortNumber,
+  Protocol,
+  ProtocolFilter,
+  StatusFilter
+} from "./common"
+import { ProxyConfig } from "./StubSchema"
+
+// Create Imposter Request Schema - POST /imposters
+export const CreateImposterRequest = Schema.Struct({
+  name: Schema.optional(NonEmptyString),
+  port: Schema.optional(PortNumber),
+  protocol: Schema.optionalWith(Protocol, { default: () => "HTTP" as const }),
+  adminPath: Schema.optionalWith(
+    Schema.String.pipe(Schema.startsWith("/")),
+    { default: () => "/_admin" }
+  ),
+  proxy: Schema.optional(ProxyConfig)
+})
+export type CreateImposterRequest = Schema.Schema.Type<typeof CreateImposterRequest>
+
+// Update Imposter Request Schema - PATCH /imposters/{id}
+export const UpdateImposterRequest = Schema.Struct({
+  name: Schema.optional(NonEmptyString),
+  status: Schema.optional(ImposterStatus),
+  port: Schema.optional(PortNumber),
+  adminPath: Schema.optional(Schema.String.pipe(Schema.startsWith("/"))),
+  proxy: Schema.optional(Schema.NullOr(ProxyConfig))
+})
+export type UpdateImposterRequest = Schema.Schema.Type<typeof UpdateImposterRequest>
+
+// List Imposters Query Schema - GET /imposters query params
+export const ListImpostersQuery = Schema.Struct({
+  ...PaginationQuery.fields,
+  status: StatusFilter,
+  protocol: ProtocolFilter
+})
+export type ListImpostersQuery = Schema.Schema.Type<typeof ListImpostersQuery>
+
+// Route API Schemas
+export const CreateRouteRequest = Schema.Struct({
+  path: Schema.String.pipe(Schema.startsWith("/")),
+  method: Schema.optionalWith(
+    Schema.Literal("GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"),
+    { default: () => "GET" as const }
+  ),
+  response: Schema.Struct({
+    status: Schema.optionalWith(
+      Schema.Number.pipe(Schema.int(), Schema.between(100, 599)),
+      { default: () => 200 }
+    ),
+    headers: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+    body: Schema.optional(Schema.Unknown)
+  }),
+  delay: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.between(0, 60000)))
+})
+export type CreateRouteRequest = Schema.Schema.Type<typeof CreateRouteRequest>
+
+export const RouteResponse = Schema.Struct({
+  id: NonEmptyString,
+  path: NonEmptyString,
+  method: Schema.Literal("GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"),
+  response: Schema.Struct({
+    status: Schema.Number.pipe(Schema.int(), Schema.between(100, 599)),
+    headers: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+    body: Schema.optional(Schema.Unknown)
+  }),
+  delay: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.between(0, 60000))),
+  createdAt: Schema.DateTimeUtc
+})
+export type RouteResponse = Schema.Schema.Type<typeof RouteResponse>
+
+export const ListRoutesResponse = Schema.Struct({
+  routes: Schema.Array(RouteResponse),
+  pagination: PaginationMeta
+})
+export type ListRoutesResponse = Schema.Schema.Type<typeof ListRoutesResponse>
+
+// Endpoint Summary Schema (for imposter responses)
+export const EndpointSummary = Schema.Struct({
+  id: NonEmptyString,
+  path: NonEmptyString,
+  method: NonEmptyString,
+  status: Schema.Number.pipe(Schema.int(), Schema.between(100, 599)),
+  hasDelay: Schema.Boolean,
+  delayMs: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.nonNegative()))
+})
+export type EndpointSummary = Schema.Schema.Type<typeof EndpointSummary>
+
+// Statistics Schema
+export const Statistics = Schema.Struct({
+  totalRequests: Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+  requestsPerMinute: Schema.Number.pipe(Schema.nonNegative()),
+  averageResponseTime: Schema.Number.pipe(Schema.nonNegative()),
+  errorRate: Schema.Number.pipe(Schema.between(0, 1)),
+  requestsByMethod: Schema.optionalWith(
+    Schema.Record({ key: Schema.String, value: Schema.Number }),
+    { default: () => ({}) }
+  ),
+  requestsByStatusCode: Schema.optionalWith(
+    Schema.Record({ key: Schema.String, value: Schema.Number }),
+    { default: () => ({}) }
+  ),
+  lastRequestAt: Schema.optional(Schema.DateTimeUtc),
+  p50ResponseTime: Schema.optional(Schema.Number),
+  p95ResponseTime: Schema.optional(Schema.Number),
+  p99ResponseTime: Schema.optional(Schema.Number)
+})
+export type Statistics = Schema.Schema.Type<typeof Statistics>
+
+// Core Imposter Response Schema
+export const ImposterResponse = Schema.Struct({
+  id: NonEmptyString,
+  name: NonEmptyString,
+  port: PortNumber,
+  protocol: Protocol,
+  status: ImposterStatus,
+  endpointCount: Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+  createdAt: Schema.DateTimeUtc,
+  adminUrl: NonEmptyString,
+  adminPath: NonEmptyString,
+  uptime: Schema.optional(Schema.String), // Formatted duration string
+  endpoints: Schema.optional(Schema.Array(EndpointSummary)),
+  statistics: Schema.optional(Statistics),
+  proxy: Schema.optional(ProxyConfig)
+})
+export type ImposterResponse = Schema.Schema.Type<typeof ImposterResponse>
+
+// List Imposters Response Schema - GET /imposters
+export const ListImpostersResponse = Schema.Struct({
+  imposters: Schema.Array(ImposterResponse),
+  pagination: PaginationMeta
+})
+export type ListImpostersResponse = Schema.Schema.Type<typeof ListImpostersResponse>
+
+// Delete Imposter Query Schema - DELETE /imposters/{id}
+export const DeleteImposterQuery = Schema.Struct({
+  force: Schema.optionalWith(Schema.Boolean, { default: () => false })
+})
+export type DeleteImposterQuery = Schema.Schema.Type<typeof DeleteImposterQuery>
+
+// Delete Imposter Response Schema
+export const DeleteImposterResponse = Schema.Struct({
+  message: NonEmptyString,
+  id: NonEmptyString,
+  deletedAt: Schema.DateTimeUtc
+})
+export type DeleteImposterResponse = Schema.Schema.Type<typeof DeleteImposterResponse>
+
+// System Memory Info Schema
+export const MemoryInfo = Schema.Struct({
+  used: NonEmptyString,
+  free: NonEmptyString
+})
+export type MemoryInfo = Schema.Schema.Type<typeof MemoryInfo>
+
+// System Imposters Summary Schema
+export const ImpostersSummary = Schema.Struct({
+  total: Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+  running: Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+  stopped: Schema.Number.pipe(Schema.int(), Schema.nonNegative())
+})
+export type ImpostersSummary = Schema.Schema.Type<typeof ImpostersSummary>
+
+// System Ports Summary Schema
+export const PortsSummary = Schema.Struct({
+  available: Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+  allocated: Schema.Number.pipe(Schema.int(), Schema.nonNegative())
+})
+export type PortsSummary = Schema.Schema.Type<typeof PortsSummary>
+
+// System Info Schema (for health endpoint)
+export const SystemInfo = Schema.Struct({
+  memory: MemoryInfo,
+  imposters: ImpostersSummary,
+  ports: PortsSummary
+})
+export type SystemInfo = Schema.Schema.Type<typeof SystemInfo>
+
+// Health Response Schema - GET /health
+export const HealthResponse = Schema.Struct({
+  status: Schema.Literal("healthy", "unhealthy"),
+  timestamp: Schema.DateTimeUtc,
+  version: NonEmptyString,
+  uptime: Schema.String, // Formatted duration
+  system: SystemInfo
+})
+export type HealthResponse = Schema.Schema.Type<typeof HealthResponse>
+
+// Server Configuration Schema
+export const ServerConfiguration = Schema.Struct({
+  maxImposters: Schema.Number.pipe(Schema.int(), Schema.positive()),
+  portRange: Schema.Struct({
+    min: PortNumber,
+    max: PortNumber
+  }),
+  defaultTimeout: Schema.Number.pipe(Schema.int(), Schema.positive()),
+  logLevel: Schema.Literal("debug", "info", "warn", "error")
+})
+export type ServerConfiguration = Schema.Schema.Type<typeof ServerConfiguration>
+
+// Server Features Schema
+export const ServerFeatures = Schema.Struct({
+  openApiGeneration: Schema.Boolean,
+  clientGeneration: Schema.Boolean,
+  authentication: Schema.Boolean,
+  clustering: Schema.Boolean
+})
+export type ServerFeatures = Schema.Schema.Type<typeof ServerFeatures>
+
+// Server Info Schema
+export const ServerInfo = Schema.Struct({
+  name: NonEmptyString,
+  version: NonEmptyString,
+  buildTime: Schema.DateTimeUtc,
+  platform: NonEmptyString,
+  protocols: Schema.Array(Protocol)
+})
+export type ServerInfo = Schema.Schema.Type<typeof ServerInfo>
+
+// Server Info Response Schema - GET /info
+export const ServerInfoResponse = Schema.Struct({
+  server: ServerInfo,
+  configuration: ServerConfiguration,
+  features: ServerFeatures
+})
+export type ServerInfoResponse = Schema.Schema.Type<typeof ServerInfoResponse>

package/src/schemas/RequestLogSchema.ts

@@ -0,0 +1,38 @@
+import * as Schema from "effect/Schema"
+import { NonEmptyString } from "./common"
+
+export const RequestLogEntry = Schema.Struct({
+  id: NonEmptyString,
+  imposterId: NonEmptyString,
+  timestamp: Schema.DateTimeUtc,
+  request: Schema.Struct({
+    method: Schema.String,
+    path: Schema.String,
+    headers: Schema.Record({ key: Schema.String, value: Schema.String }),
+    query: Schema.Record({ key: Schema.String, value: Schema.String }),
+    body: Schema.optional(Schema.Unknown)
+  }),
+  response: Schema.Struct({
+    status: Schema.Number,
+    headers: Schema.optionalWith(
+      Schema.Record({ key: Schema.String, value: Schema.String }),
+      { default: () => ({}) }
+    ),
+    body: Schema.optional(Schema.String),
+    matchedStubId: Schema.optional(NonEmptyString),
+    proxied: Schema.optionalWith(Schema.Boolean, { default: () => false })
+  }),
+  duration: Schema.Number
+})
+export type RequestLogEntry = Schema.Schema.Type<typeof RequestLogEntry>
+
+export const ListRequestsUrlParams = Schema.Struct({
+  limit: Schema.optionalWith(
+    Schema.NumberFromString.pipe(Schema.int(), Schema.positive()),
+    { default: () => 50 }
+  ),
+  method: Schema.optional(Schema.String),
+  path: Schema.optional(Schema.String),
+  status: Schema.optional(Schema.NumberFromString)
+})
+export type ListRequestsUrlParams = Schema.Schema.Type<typeof ListRequestsUrlParams>

package/src/schemas/StubSchema.ts

@@ -0,0 +1,90 @@
+import * as Schema from "effect/Schema"
+import { NonEmptyString } from "./common"
+
+// Proxy Mode
+export const ProxyMode = Schema.Literal("passthrough", "record")
+export type ProxyMode = Schema.Schema.Type<typeof ProxyMode>
+
+// Proxy Configuration
+export const ProxyConfig = Schema.Struct({
+  targetUrl: Schema.String.pipe(Schema.pattern(/^https?:\/\//)),
+  mode: Schema.optionalWith(ProxyMode, { default: () => "passthrough" as const }),
+  addHeaders: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+  removeHeaders: Schema.optionalWith(Schema.Array(Schema.String), { default: () => [] as const }),
+  followRedirects: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+  timeout: Schema.optionalWith(
+    Schema.Number.pipe(Schema.int(), Schema.between(100, 60000)),
+    { default: () => 10000 }
+  )
+})
+export type ProxyConfig = Schema.Schema.Type<typeof ProxyConfig>
+
+// Predicate operators for matching incoming requests
+export const PredicateOperator = Schema.Literal(
+  "equals",
+  "contains",
+  "startsWith",
+  "matches",
+  "exists"
+)
+export type PredicateOperator = Schema.Schema.Type<typeof PredicateOperator>
+
+// Which part of the request to match against
+export const PredicateField = Schema.Literal(
+  "method",
+  "path",
+  "headers",
+  "query",
+  "body"
+)
+export type PredicateField = Schema.Schema.Type<typeof PredicateField>
+
+// A single predicate matcher
+export const Predicate = Schema.Struct({
+  field: PredicateField,
+  operator: PredicateOperator,
+  value: Schema.Unknown,
+  caseSensitive: Schema.optionalWith(Schema.Boolean, { default: () => true })
+})
+export type Predicate = Schema.Schema.Type<typeof Predicate>
+
+// How to cycle through responses
+export const ResponseMode = Schema.Literal("sequential", "random", "repeat")
+export type ResponseMode = Schema.Schema.Type<typeof ResponseMode>
+
+// A single response configuration
+export const ResponseConfig = Schema.Struct({
+  status: Schema.optionalWith(
+    Schema.Number.pipe(Schema.int(), Schema.between(100, 599)),
+    { default: () => 200 }
+  ),
+  headers: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.String })),
+  body: Schema.optional(Schema.Unknown),
+  delay: Schema.optional(Schema.Number.pipe(Schema.int(), Schema.between(0, 60000)))
+})
+export type ResponseConfig = Schema.Schema.Type<typeof ResponseConfig>
+
+// A stub: predicates (AND-combined) + responses (cycled)
+export const Stub = Schema.Struct({
+  id: NonEmptyString,
+  predicates: Schema.Array(Predicate),
+  responses: Schema.NonEmptyArray(ResponseConfig),
+  responseMode: Schema.optionalWith(ResponseMode, { default: () => "sequential" as const })
+})
+export type Stub = Schema.Schema.Type<typeof Stub>
+
+// API request to create a stub (id is auto-generated)
+export const CreateStubRequest = Schema.Struct({
+  predicates: Schema.optionalWith(Schema.Array(Predicate), { default: () => [] as const }),
+  responses: Schema.NonEmptyArray(ResponseConfig),
+  responseMode: Schema.optionalWith(ResponseMode, { default: () => "sequential" as const })
+})
+export type CreateStubRequest = Schema.Schema.Type<typeof CreateStubRequest>
+
+// API request to update a stub
+export const UpdateStubRequest = Schema.Struct({
+  predicates: Schema.optional(Schema.Array(Predicate)),
+  responses: Schema.optional(Schema.NonEmptyArray(ResponseConfig)),
+  responseMode: Schema.optional(ResponseMode)
+})
+export type UpdateStubRequest = Schema.Schema.Type<typeof UpdateStubRequest>

package/src/schemas/common.ts

@@ -0,0 +1,95 @@
+import { Clock, DateTime, Effect } from "effect"
+import * as Duration from "effect/Duration"
+import * as Schema from "effect/Schema"
+
+// Common enums
+export const ImposterStatus = Schema.Literal("running", "stopped", "starting", "stopping")
+export type ImposterStatus = Schema.Schema.Type<typeof ImposterStatus>
+
+export const Protocol = Schema.Literal("HTTP")
+export type Protocol = Schema.Schema.Type<typeof Protocol>
+
+// Utility schemas for validation
+export const PositiveInteger = Schema.Number.pipe(
+  Schema.int(),
+  Schema.positive(),
+  Schema.brand("PositiveInteger")
+)
+export type PositiveInteger = Schema.Schema.Type<typeof PositiveInteger>
+
+export const NonEmptyString = Schema.String.pipe(
+  Schema.minLength(1),
+  Schema.brand("NonEmptyString")
+)
+export type NonEmptyString = Schema.Schema.Type<typeof NonEmptyString>
+
+export const PortNumber = Schema.Number.pipe(
+  Schema.int(),
+  Schema.between(1024, 65535),
+  Schema.brand("PortNumber")
+)
+export type PortNumber = Schema.Schema.Type<typeof PortNumber>
+
+export const PaginationQuery = Schema.Struct({
+  // PositiveInteger.make() is safe here — 50 is a compile-time constant that always passes validation
+  limit: Schema.optionalWith(PositiveInteger, { default: () => PositiveInteger.make(50) }),
+  offset: Schema.optionalWith(
+    Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+    { default: () => 0 }
+  )
+})
+export type PaginationQuery = Schema.Schema.Type<typeof PaginationQuery>
+
+export const PaginationMeta = Schema.Struct({
+  total: Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+  limit: PositiveInteger,
+  offset: Schema.Number.pipe(Schema.int(), Schema.nonNegative()),
+  hasMore: Schema.Boolean
+})
+export type PaginationMeta = Schema.Schema.Type<typeof PaginationMeta>
+
+export const ErrorCode = Schema.Union(
+  // Validation errors
+  Schema.Literal("VALIDATION_ERROR"),
+  Schema.Literal("INVALID_ENDPOINT"),
+  // Resource errors
+  Schema.Literal("IMPOSTER_NOT_FOUND"),
+  Schema.Literal("PORT_IN_USE"),
+  Schema.Literal("IMPOSTER_BUSY"),
+  // System errors
+  Schema.Literal("SYSTEM_ERROR"),
+  Schema.Literal("CONFIRMATION_REQUIRED"),
+  // Conflict errors
+  Schema.Literal("ENDPOINT_CONFLICT")
+)
+export type ErrorCode = Schema.Schema.Type<typeof ErrorCode>
+
+export const ErrorDetails = Schema.Struct({
+  code: ErrorCode,
+  message: NonEmptyString,
+  field: Schema.optional(Schema.String),
+  value: Schema.optional(Schema.Unknown),
+  details: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown }))
+})
+export type ErrorDetails = Schema.Schema.Type<typeof ErrorDetails>
+
+export const ErrorResponse = Schema.Struct({
+  error: ErrorDetails
+})
+export type ErrorResponse = Schema.Schema.Type<typeof ErrorResponse>
+
+// Common query filters
+export const StatusFilter = Schema.optional(ImposterStatus)
+export const ProtocolFilter = Schema.optional(Protocol)
+
+// DateTime schemas using Effect's DateTime
+export const DateTimeSchema = Schema.DateTimeUtc
+export type DateTimeSchema = Schema.Schema.Type<typeof DateTimeSchema>
+
+// Helper to create current DateTime
+export const currentDateTime = Effect.map(Clock.currentTimeMillis, (ms) => DateTime.unsafeMake(ms))
+
+// Helper to format duration as uptime string (HH:MM:SS)
+export const formatDurationAsUptime = (duration: Duration.Duration): string => {
+  return Duration.format(duration)
+}

package/src/server/AdminServer.ts

@@ -0,0 +1,22 @@
+import { HttpApiBuilder } from "@effect/platform"
+import * as Layer from "effect/Layer"
+import { ApiLayer } from "../layers/ApiLayer"
+import { MainLayer } from "../layers/MainLayer"
+import { makeAdminUiRouter } from "../ui/admin/AdminUiRouter"
+
+export const FullLayer = ApiLayer.pipe(Layer.provide(MainLayer))
+
+export const makeWebHandler = () => HttpApiBuilder.toWebHandler(FullLayer)
+
+export const makeCompositeHandler = (adminPort: number) => {
+  const { dispose, handler: apiHandler } = HttpApiBuilder.toWebHandler(FullLayer)
+  const adminUiRouter = makeAdminUiRouter({ apiHandler, adminPort })
+
+  const handler = async (request: Request): Promise<Response> => {
+    const uiResponse = await adminUiRouter(request)
+    if (uiResponse !== null) return uiResponse
+    return apiHandler(request)
+  }
+
+  return { handler, dispose }
+}

package/src/server/BunServer.ts

@@ -0,0 +1,19 @@
+import { Context, Layer } from "effect"
+
+export interface ServerInstance {
+  readonly port: number
+  readonly stop: (closeActive: boolean) => void
+}
+
+export interface ServerFactoryShape {
+  readonly create: (options: {
+    readonly port: number
+    readonly fetch: (request: Request) => Promise<Response>
+  }) => ServerInstance
+}
+
+export class ServerFactory extends Context.Tag("ServerFactory")<ServerFactory, ServerFactoryShape>() {}
+
+export const BunServerFactoryLive = Layer.succeed(ServerFactory, {
+  create: (options) => Bun.serve(options)
+})