TypeScript migration: investigate phased conversion path

[lidge-jun]

Source

Current migration investigation from 2026-04-28.

Problem

The app has grown into a mixed JavaScript/TypeScript codebase. UI work now depends on TypeScript types in several places, while backend and tests still include broad JavaScript surfaces. Before converting more files opportunistically, the project needs a deliberate migration plan.

Investigation goals

• Inventory current JS/TS boundaries across backend, frontend, tests, and CLI.
• Decide whether migration should start with UI-only, shared types, tests, backend modules, or CLI modules.
• Identify files that are too large or too coupled and should be split before conversion.
• Define tsconfig/check strategy that does not break current Node ESM behavior.
• Decide how to handle test files: keep node:test JS contracts, convert selectively, or introduce a TS test runner.
• Document risks around build time, CI matrix, generated artifacts, and current WIP branches.

Acceptance criteria for planning

• Produce a phased migration PRD before broad implementation.
• No large mechanical conversion without approval.
• Preserve ES Module imports/exports.
• Keep CI green at every phase.
• Avoid mixing TypeScript migration with unrelated feature work.

Out of scope for this issue

• Immediate full-repo conversion.
• Framework replacement.
• Bundler rewrite unless proven necessary.