operations/docs/research/migration.md

status, last_updated

status	last_updated
in-progress	2026-04-30

@alkdev/operations — Migration Plan

Extract packages/core/operations/ and packages/core/mcp/ from alkhub_ts into a standalone @alkdev/operations package. Follow patterns from @alkdev/pubsub (tsup+vitest, peer-dep isolation, sub-path exports, architecture docs).

Source Inventory

Module	Source	Lines	Status Category
types.ts	alkhub_ts/packages/core/operations/types.ts	212	Copy (zero changes)
from_schema.ts	alkhub_ts/packages/core/operations/from_schema.ts	115	Copy (zero changes)
registry.ts	alkhub_ts/packages/core/operations/registry.ts	82	Adapt (logger swap)
validation.ts	alkhub_ts/packages/core/operations/validation.ts	115	Adapt (@std/assert swap)
env.ts	alkhub_ts/packages/core/operations/env.ts	83	Adapt (logger swap, PendingRequestMap interface stays)
scanner.ts	alkhub_ts/packages/core/operations/scanner.ts	89	Adapt (inject fs, replace Deno globals, logger)
from_openapi.ts	alkhub_ts/packages/core/operations/from_openapi.ts	333	Adapt (remove Deno.env.get, inject auth, replace Deno.readTextFile, fix SSE handler)
mcp/wrapper.ts	alkhub_ts/packages/core/mcp/wrapper.ts	88	Merge → from_mcp.ts (update imports, logger)
mcp/loader.ts	alkhub_ts/packages/core/mcp/loader.ts	59	Merge → from_mcp.ts (update imports, logger)
call.ts	New	—	Build
subscribe.ts	New	—	Build
error.ts	New	—	Build

Architecture Decisions

• Logger: Direct @logtape/logtape import, no wrapper (ADR-001)
• FS injection: Scanner and from_openapi accept injected fs/env deps, no Deno.* globals (ADR-002)
• Peer deps: MCP SDK is a peer dep with sub-path export ./from-mcp. Scanner stays in main barrel since @std/path is lightweight (ADR-003)
• Call protocol: call ≡ subscribe — same event types, same PendingRequestMap, different consumption
• No Effect, No Zod: Plain async/await, TypeBox for all schemas

Phase 1: Project Skeleton + Direct Copies

• Create package.json (following pubsub pattern — tsup, vitest, dual ESM/CJS)
• Create tsconfig.json (ES2022, nodenext, strict)
• Create tsup.config.ts (dual format, entries: index + from-mcp)
• Create vitest.config.ts
• Create .gitignore
• Copy types.ts → src/types.ts (renamed schema consts: AccessControlSchema, ErrorDefinitionSchema, OperationContextSchema, OperationDefinitionSchema — avoid TSchema annotation + name collision with type aliases)
• Copy from_schema.ts → src/from_schema.ts (zero changes)
• Adapt registry.ts → src/registry.ts (swap ../logger/mod.ts → @logtape/logtape)
• Adapt validation.ts → src/validation.ts (swap @std/assert → custom throw in assertIsSchema)
• Adapt env.ts → src/env.ts (swap logger)
• Create src/index.ts barrel

Phase 2: Files with Significant Changes

• Create src/error.ts — CallError, mapError, infrastructure error codes
• Create src/call.ts — PendingRequestMap class, call(), respond(), emitError(), abort(), buildCallHandler()
• Create src/subscribe.ts — AsyncIterable subscription support
• Add CallEventSchema types to src/types.ts and src/call.ts
• Adapt scanner.ts → src/scanner.ts — inject ScannerFS, no Deno.* globals
• Adapt from_openapi.ts → src/from_openapi.ts — remove Deno.env.get(), inject OpenAPIFS, explicit auth config
• Merge wrapper.ts + loader.ts → src/from_mcp.ts — dynamic imports, logger, MCPClientLoader

Phase 3: Architecture Docs

• docs/architecture/README.md
• docs/architecture/api-surface.md
• docs/architecture/call-protocol.md
• docs/architecture/adapters.md
• docs/architecture/build-distribution.md
• docs/architecture/decisions/001-logger-direct-import.md
• docs/architecture/decisions/002-fs-injection.md
• docs/architecture/decisions/003-peer-dep-adapters.md
• docs/architecture/decisions/004-schema-const-naming.md (added during implementation — discovered TSchema annotation issue)

Phase 4: Tests + Verify Build

• Tests for registry, validation, from_schema (68 tests passing)
• Tests for call protocol (PendingRequestMap, call, abort, timeout)
• Tests for error (CallError, mapError, infrastructure codes)
• Tests for env (buildEnv direct vs call protocol mode)
• Tests for from_openapi (spec parsing, operation types, auth, $ref)
• npm run build && npm run lint && npm test all pass

Target Structure

@alkdev/operations/
  src/
    index.ts              — Public API surface (all exports)
    types.ts              — IOperationDefinition, OperationType, CallEventMap, Identity, AccessControl
    registry.ts           — OperationRegistry (register, execute, subscribe)
    validation.ts          — Input/output schema validation
    call.ts               — PendingRequestMap, call(), subscribe(), CallHandler
    subscribe.ts          — AsyncIterable subscription support
    error.ts              — CallError, mapError, infrastructure codes
    env.ts                — buildEnv (direct + call protocol modes)
    scanner.ts            — Auto-discover operations (injected fs)
    from_schema.ts        — JSON Schema → TypeBox converter
    from_openapi.ts       — OpenAPI spec → IOperationDefinition[]
    from_mcp.ts           — MCP server → IOperationDefinition[]
  test/
    registry.test.ts
    validation.test.ts
    call.test.ts
    subscribe.test.ts
    error.test.ts
    env.test.ts
    from_schema.test.ts
    from_openapi.test.ts
    from_mcp.test.ts
    scanner.test.ts
  docs/
    architecture.md
    architecture/
      README.md
      api-surface.md
      call-protocol.md
      adapters.md
      build-distribution.md
      decisions/
        001-logger-direct-import.md
        002-fs-injection.md
        003-peer-dep-adapters.md
    research/
      migration.md          (this file)
  package.json
  tsconfig.json
  tsup.config.ts
  vitest.config.ts
  .gitignore
  AGENTS.md

References

• Source: @alkdev/alkhub_ts/packages/core/operations/ + packages/core/mcp/
• Pattern reference: @alkdev/pubsub (package.json, tsup, vitest, peer-dep isolation, architecture docs)
• Pattern reference: @alkdev/taskgraph_ts (AGENTS.md format, build pipeline)
• Architecture specs: alkhub_ts/docs/architecture/operations.md, call-graph.md, mcp-server.md