refactor: extract metro/ folder — Phase 5

[thymikee]

Summary

Phase 5 (layering) slice from plans/perfect-shape.md §5.5 — extract the metro cluster from src/ root into a src/metro/ folder. Pure path codemod, no behavior change.

§5.5 target: metro/ ← metro* · client-metro*.

Move set (→ src/metro/)

file	importers	why it moves
metro.ts	4	the metro public surface (rslib metro entry)
metro-types.ts	2	metro-domain types, used only by metro/client-metro
client-metro.ts	10	the metro client driver
client-metro-companion.ts	6	metro companion lifecycle (ensure/stopMetroCompanion)

These four form a cohesive metro domain: metro.ts → client-metro* + metro-types; client-metro.ts → client-metro-companion + metro-types. Moving them together keeps intra-folder imports as ./ (unchanged); only their edges to root infra (contracts, kernel/errors, utils/*, client-companion-tunnel-contract) and their external importers were rewritten.

Deliberately kept OUT (stay at src/ root)

The companion-tunnel cluster — client-companion-tunnel-contract.ts, client-companion-tunnel.ts, client-companion-tunnel-worker.ts, companion-tunnel.ts, client-react-devtools-companion.ts — is a separate domain (the future companion/ slice, not part of metro*/client-metro*). Keeping it at root avoids a reverse/sibling churn and, critically, keeps the worker process entrypoint co-located with its spawner (see below). General-purpose infra (utils, contracts, kernel) also stays out.

Worker-path verification (the critical risk for this slice)

metro.ts is itself an rslib entrypoint (metro: 'src/metro.ts'), and the companion tunnel runs as a detached child process whose entry is src/companion-tunnel.ts (rslib entry internal/companion-tunnel). That worker is not a new Worker(new URL('./worker.ts')) thread — client-companion-tunnel.ts resolves the entry by name relative to its own built location in dist/ and spawns it via runCmdDetached.

• The spawner (client-companion-tunnel.ts) and the worker entry source (companion-tunnel.ts) both stay at root → entry-name resolution is unchanged.
• The worker bundle chain reaches the moved metro.ts (companion-tunnel.ts → client-companion-tunnel-worker.ts → metro.ts); that import was rewritten and re-bundled.
• Verified by npm run build (exit 0), which emits both dist/src/metro.js and dist/src/internal/companion-tunnel.js. The metro output path is keyed by the entry name, so package.json ./metro (→ dist/src/metro.js) is unaffected.

Codemod

A resolve-based node codemod: for every .ts in src/test, each relative import/vi.mock/vi.importActual specifier is resolved to an absolute path against the file's original dir, mapped through the old→new move table, and rewritten relative to the file's new dir (compares resolved paths — no naive string replace). Three non-.ts references were updated to the new paths: the rslib metro entry, the .fallowrc.json entry list, and the fallow-baselines/health.json baseline key. tsconfig uses glob includes (no change).

Verification (all green)

• tsc -p tsconfig.json --noEmit → exit 0
• oxfmt --check src test → exit 0; oxlint src --deny-warnings → exit 0
• npm run build → exit 0 (metro entry + companion-tunnel worker bundle both emitted)
• fallow audit --base origin/main → CLEAN (no issues, 21 changed files)
• vitest run (full) → 314 files / 2892 tests passed; affected metro/client tests: 7 files / 58 tests passed
• Layering Guard (git grep for commands/ imports in daemon/platforms/kernel) → EMPTY
• No stale references to the old paths anywhere (src/test/json); git tracks all 4 files as renames

Pure path codemod — no runtime behavior change.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.4 MB	1.4 MB	0 B
JS gzip	455.5 kB	455.5 kB	+4 B
npm tarball	561.0 kB	561.2 kB	+185 B
npm unpacked	2.0 MB	2.0 MB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	25.4 ms	25.9 ms	+0.4 ms
CLI --help	50.1 ms	46.9 ms	-3.2 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/1153.js	+17.5 kB	+6.0 kB
dist/src/cli.js	0 B	+1 B
dist/src/9919.js	0 B	+1 B

[thymikee]

Reviewed against plans/perfect-shape.md §5.5 and ADR 0008/0003 boundaries.

This looks ready for maintainer review. I checked the PR as a pure metro-domain move: metro.ts, metro-types.ts, client-metro.ts, and client-metro-companion.ts moved under src/metro/; external imports were mechanically updated; rslib.config.ts still preserves the public ./metro package entry output as dist/src/metro.js; the companion tunnel worker stays rooted and only its import of the metro protocol moved.

Additional checks I ran locally while reviewing:

• no stale source references to src/client-metro*, src/metro-types, or src/metro.ts
• no stale relative imports from the old root metro files
• git diff --check origin/main...origin/pr/947 clean

CI is green across 21 checks. I did not find an actionable blocker.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-06-30 06:22 UTC