mcporter/docs/refactor.md

Next-Step Refactor Checklist

This doc tracks remaining reuse/refactor work now that the original plan is done. Each section lists the goal, why it matters, and the concrete steps/tests needed.

1. Shared Tool Schema Cache (Completed)

• Problem: generate-cli and emit-ts both fetch & serialize tool schemas independently (and mcporter list re-parses them too).
• What we did:
  1. Added src/cli/tool-cache.ts with loadToolMetadata() caching tool metadata per runtime/server/options.
  2. Switched mcporter list (single-server path) and emit-ts to consume the helper, so both reuse ToolMetadata.
  3. Added tests/tool-cache.test.ts + updated emit-ts tests to ensure the helper is covered.
• Next: Consider integrating the cache into generate-cli if we ever reuse runtime instances there.

2. Unified Flag Parsing for Generator-style Commands (Completed)

• Problem: generate-cli, regenerate-cli, and emit-ts each reimplemented --runtime, --timeout, and --include-optional handling.
• What we did:
  1. Added extractGeneratorFlags() in src/cli/generate/flag-parser.ts to normalize shared flags while mutating args in place.
  2. Updated all three commands to call the helper before parsing command-specific options.
  3. Added tests/generator-flag-parser.test.ts to cover runtime/timeout and optional flags.

3. Test Fixture Reuse (Completed)

• Problem: Emit-ts/tool-cache/unit tests each defined their own tool/definition fixtures, leading to divergence.
• What we did:
  1. Added tests/fixtures/tool-fixtures.ts (shared definition + tools).
  2. Updated tests/emit-ts.test.ts and tests/tool-cache.test.ts to import the shared fixtures (and reuse them via buildToolMetadata).
  3. Ensured the fixture covers required+optional parameters so both suites hit the same edge cases.

4. CallResult Helper Extraction (Completed)

• Problem: call-command.ts and the emit-ts client template both wrapped results with createCallResult, but there was no shared helper.
• What we did:
  1. Added wrapCallResult() to result-utils.ts and exported it from the package entry.
  2. Updated call-command.ts and the emit-ts template to reuse the helper so they stay in sync.
  3. Adjusted emit-ts tests to assert the helper is referenced.

5. CLI Docs Consolidation (Completed)

• Problem: CLI usage guidance was scattered across README, docs/spec.md, and various feature docs.
• What we did:
  1. Added docs/cli-reference.md summarizing list, call, generate-cli, and emit-ts flags/modes in one place.
  2. Pointed emit-ts users to that doc so we can converge other references over time (no README/spec churn yet to avoid clobbering parallel work).
• Next: Once the other doc changes land, update README/spec to link to the reference and drop redundant sections.

---

Tracking the above here keeps future agents aligned. Update this checklist as items ship (mark sections “Completed” when done, or delete the doc once empty).