Refactor: split large single-file `index.ts` barrels in leaf packages (platform/download/sidecar/sidecar-proto/host) — export-surface-stable

[leonaburime-ucla]

Proposal / question

The leaf packages under packages/* each keep their entire implementation in a single large src/index.ts:

package	src/index.ts LOC
platform	~1111
download	~1051
sidecar-proto	~933
sidecar	~800
host	~674 (2-file)

These are cohesive, well-tested, and low-churn — not god-files — but the single-file shape makes them harder to navigate and review than they need to be. I'd like to split each into a few concern-focused sibling modules with index.ts kept as a pure barrel that re-exports the exact same public surface (byte-identical function bodies; only import-path rewrites). No behavior change, no dependency change, export surface identical before/after.

This is deliberately a lightweight file-split, not the full apps/daemon/src/design-systems capability-barrel machinery — packages/* aren't in the check-barrel-imports guard registry (that guard is daemon-scoped), so this wouldn't touch guard infrastructure.

Why

Maintainability/reviewability of the shared substrate. platform's process/proxy/fs/stamp helpers, for example, are five unrelated concerns in one 1.1k-line file.

What users see

Nothing — internal refactor, public API and runtime behavior unchanged.

Plan

Land platform as a pilot PR first so the shape can be reviewed on one package, then replicate for download / sidecar / sidecar-proto / host if the pilot is accepted.

Before I invest in all five — is this kind of maintainability refactor welcome for these packages, or do you prefer the single-file shape for the leaf substrate? Happy to close if it's unwanted churn.

[open-design-bot]

🎉 📡 You just leveled up to Giotto

📡 ✨ Sending steady signals.

🙌 Your contributions are sending a clear signal across the network: you care about making Open Design better. Keep transmitting.

💛 Thanks for helping Open Design move forward. Keep building in the open. 🚀

---

📊 Rank #131 among 100+ contributors

🔗 Share on X (English) · 分享到 X（中文）

[lefarcen]

Hi @leonaburime-ucla! The direction makes sense — splitting those leaf-package src/index.ts files into concern-focused sibling modules while keeping index.ts as a pure barrel is welcome from our side.

Starting with packages/platform as a pilot is the right scope. The main bar we'd want in the PR is: no public export changes, no behavior or dependency changes, and a diff that stays easy to review package-by-package rather than all five at once. No need to pull this into the daemon barrel-guard machinery for this pass.

I checked the current tree and those packages really are still concentrated in single entry files (platform 1111 LOC, download 1051, sidecar-proto 933, sidecar 800, host 674), so the maintainability motivation is concrete here. If the platform pilot stays that tight and the before/after surface is easy to verify, we'd be happy to review it. ✨

[lefarcen]

Pilot is now up in #5166. It keeps @open-design/platform's public surface unchanged and only splits the current src/index.ts into concern-focused sibling modules, so this issue can stay focused on whether that pattern is welcome for the leaf packages before the rest are replicated.

Keeping #5165 open until the pilot lands (or maintainers decide against the pattern).

[leonaburime-ucla]

Got it, working on the rest now.

[lefarcen]

Following up from the pilot in #5166, #5167 applies the same export-surface-stable barrel split to @open-design/download.

The scope there is still behavior-preserving only: the current 1051-line src/index.ts is being split into concern-focused sibling modules while keeping the package's public API unchanged. Keeping this issue open until the pattern lands (or maintainers decide against it).

[lefarcen]

PR #5170 is up for the @open-design/host slice of the same barrel-split track from #5165.

This one keeps the package surface unchanged while breaking the 674-line host bridge entrypoint into protocol / detection / normalize / actions sibling modules, so #5165 can keep tracking whether the pattern stays behavior-preserving package by package.

[lefarcen]

PR #5168 takes the packages/sidecar slice of this barrel-split series: it turns packages/sidecar/src/index.ts into a pure re-export barrel and moves the existing runtime-path/bootstrap/port/JSON-IPC helpers into sibling modules without changing the public surface.

Keeping #5165 open while the package-by-package refactor set lands.

[lefarcen]

Following the same export-surface-stable barrel-split track from #5165, PR #5169 is now up for @open-design/sidecar-proto.

This slice keeps the package API/runtime contract unchanged while breaking the current 933-line src/index.ts into concern-focused sibling modules (validation, identity, errors, stamp, desktop-update, desktop-control, status, messages, contract), so this issue can keep tracking whether the pattern stays behavior-preserving package by package. The issue stays open until the series lands or maintainers decide against the pattern.