docs: add v1.0 TypeScript/npx migration plan

[kartikloops]

Description

This MR adds a scoped migration plan for deciding whether OpenROAD MCP should move from Python/uvx to TypeScript/npx for v1.0.
Refs: #114

Summary by CodeRabbit

• Documentation
  • Added a comprehensive migration plan outlining the multi-stage transition strategy, phased timeline, testing approach (including snapshot and integration tests), risk analysis and mitigations, packaging and deployment considerations for various environments, a decision/recommendation matrix, and a prioritized implementation roadmap to ensure behavioral parity across implementations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3d3bda0d-6326-4890-b80a-c7cbc0d655d5

📥 Commits

Reviewing files that changed from the base of the PR and between 98ddc68 and af9d10c.

📒 Files selected for processing (1)

• docs/MIGRATION_PLAN.md

✅ Files skipped from review due to trivial changes (1)

• docs/MIGRATION_PLAN.md

---

📝 Walkthrough

Walkthrough

This PR adds a comprehensive migration plan documenting the transition from a Python/uvx-distributed MCP server to TypeScript/npm-npx distribution. The plan covers current-state assessment, strategic options, week-by-week execution timeline with PTY feasibility gate, immutable schema contracts, packaging strategy, testing approach, risk analysis, and developer reference materials.

Changes

Python to TypeScript MCP Server Migration Plan

Layer / File(s)	Summary
Problem statement and current-state baseline docs/MIGRATION_PLAN.md (lines 1–74)	Introduces the distribution onboarding motivation and establishes the baseline: codebase complexity by module, the 10 tools requiring identical behavior, and PTY subsystem risk (Python POSIX modules vs. node-pty).
Migration strategy and approach options docs/MIGRATION_PLAN.md (lines 75–206)	Compares thin Node wrapper, full TypeScript rewrite, and stage-gated delivery strategies; details layer-by-layer rewrite mapping and identifies PTY semantics as the primary behavioral-difference risk.
Stage-gated execution timeline and milestones docs/MIGRATION_PLAN.md (lines 209–405)	Week-by-week breakdown: Week 1 PTY spike with go/no-go criteria, Week 2 business logic/tools/server, Week 3 testing/CI/packaging/docs; includes schema replacement (Pydantic→Zod), image tooling (PIL→sharp), and npm publishing workflow.
Immutable schema contracts and tool annotations docs/MIGRATION_PLAN.md (lines 409–486)	Documents the JSON contract that must remain identical: tool input schemas, output field structures with nullability semantics, and tool annotation matrix (read-only/destructive/idempotent).
Packaging strategy and npm distribution docs/MIGRATION_PLAN.md (lines 491–557)	Inventories npm dependencies, native compilation concerns (node-pty, sharp), npm publish workflow, example mcp.json configuration, and registry/server metadata updates for npx distribution.
Testing strategy and quality assurance tooling docs/MIGRATION_PLAN.md (lines 562–655)	Specifies golden-file snapshot tests, PTY integration tests, Vitest configuration for file descriptors, and tool replacements (ruff→ESLint, mypy→strict TypeScript).
Risk assessment and decision matrix docs/MIGRATION_PLAN.md (lines 658–703)	Enumerates risks (PTY behavioral differences, native failures, schema divergence, timeline uncertainty, opportunity cost) with mitigations, presents decision matrix, and recommends proceeding with Week 1 PTY gate as the critical decision point.
Reference materials and implementation guides docs/MIGRATION_PLAN.md (lines 709–751)	Appendix with asyncio-to-Node.js concept mapping and file-by-file rewrite priority order for implementation.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

In burrowed code I nibble lines,
A migration map of careful signs,
PTY gates and schema thread,
I hop where Python once was led,
TypeScript carrots on the spread. 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: add v1.0 TypeScript/npx migration plan' accurately describes the main change: adding comprehensive migration documentation for a Python-to-TypeScript switch.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a detailed migration plan documenting a potential move from the current Python/uvx distribution to a TypeScript/Node.js implementation distributed via npx, with emphasis on PTY behavior parity and stage-gated execution.

Changes:

• Introduces a comprehensive, stage-gated TypeScript migration plan (scope, risks, timeline, tooling).
• Documents schema/tool contract requirements and testing strategy (golden files + PTY integration).
• Outlines packaging/CI/Docker implications for a Node.js + native-module stack (node-pty, sharp).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/MIGRATION_PLAN.md`:
- Around line 418-429: The migration doc has several fenced code blocks
containing function signatures (e.g., interactive_openroad_query,
interactive_openroad_exec, create_interactive_session,
list_interactive_sessions, terminate_interactive_session,
inspect_interactive_session, get_session_history, get_session_metrics,
list_report_images, read_report_image) that lack a language identifier—edit each
fenced block and add a language tag (suggest "typescript" or "ts") immediately
after the opening ``` so linters accept them; also locate the inline code span
that currently has an extra space inside its backticks (the inline symbol near
the session/metrics section) and remove the extra space so the inline code span
contains the identifier exactly with no surrounding spaces.
- Line 286: Update the sentence claiming JSON "stays identical" to a caveated
statement: note that Zod's z.object().parse() behavior varies with .optional(),
.nullish(), .nullable(), and .default() (keys may be omitted, null preserved, or
defaults populated), so JSON may differ; instruct readers to add parity tests
that cover undefined vs null vs omitted fields and default values to verify
equivalence between each Pydantic model and its Zod schema.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 66b9b1ba-24f7-44a0-b60b-0f00756dc495

📥 Commits

Reviewing files that changed from the base of the PR and between f2022ce and 98ddc68.

📒 Files selected for processing (1)

• docs/MIGRATION_PLAN.md

[luarss]

Code review

Found 2 issues:

1. openroad_error_patterns.txt does not exist in the codebase — the plan instructs Day 5 to load it via fs.readFileSync and includes it in the package.json files manifest, but error patterns are hardcoded as a compiled-regex list in session.py lines 35–53. Following the plan as written will reference a missing file and produce a broken npm package.

https://github.com/luarss/openroad-mcp/blob/98ddc68e823f5350f4fe564352254d7f5ea561a7/docs/MIGRATION_PLAN.md#L242-L246

https://github.com/luarss/openroad-mcp/blob/98ddc68e823f5350f4fe564352254d7f5ea561a7/docs/MIGRATION_PLAN.md#L378-L382

2. asyncio.create_task is mapped to Promise + setImmediate, which is the wrong Node.js equivalent — setImmediate defers a single synchronous callback to the next I/O tick; it does not spawn a long-running concurrent loop. The Python code uses asyncio.create_task to launch three background loops (_read_output, _write_input, _monitor_exit) that run concurrently for the lifetime of the session. The correct Node.js idiom is a fire-and-forget async IIFE: (async () => { while (true) { ... } })(). Using setImmediate as described will cause the background reader/writer loops to not run, breaking PTY communication entirely.

https://github.com/luarss/openroad-mcp/blob/98ddc68e823f5350f4fe564352254d7f5ea561a7/docs/MIGRATION_PLAN.md#L138-L142

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[luarss]

Please sync the plan to the latest codebase.

[luarss]

You may start contributing to feat/ts-migration