[release] Standardize package entrypoint contracts across all public packages

[kang-heewon]

배경

Croco는 98개 패키지를 가진 TypeScript 모노레포인데, public package의 배포 엔트리포인트 계약이 패키지마다 다릅니다. 현재 조사 기준으로 53개 패키지가 root main/types를 ./src/index.ts로 가리키면서 files는 dist만 포함합니다.

예시:

• packages/framework-context/package.json:4-20 — files: ["dist"]인데 root main/types는 ./src/index.ts, publishConfig는 dist를 가리킴
• packages/impersonation-core/package.json:8-23 — root main/module/types/exports가 dist 기반이지만 types가 배열 형태
• package.json:18 — release는 pnpm build && changeset publish 흐름
• 관련 기존 이슈: [storage packages] Published manifests point package roots at src while only dist is shipped #578 은 storage package 한정 manifest 문제. 이 이슈는 전 public package 정책과 CI gate를 다룸

왜 중요한가

world-class 프레임워크는 npm 소비자가 ESM/CJS/TypeScript 환경에서 동일하게 패키지를 해석할 수 있어야 합니다. entrypoint drift는 release 직후 런타임 import 실패, 타입 해상도 실패, bundler별 동작 차이로 이어집니다.

외부 기준:

• SemVer: https://semver.org/
• Fastify LTS/version policy: https://fastify.dev/docs/latest/Reference/LTS/

제안 범위

• public package manifest 표준 결정
  • root main, module, types, exports, type, files
  • publishConfig 사용 여부와 root field 중복 정책
  • CJS/ESM/type declaration 확장자 정책
• scripts/normalize-packages.mjs를 write 모드와 check 모드로 분리
• CI에서 manifest drift를 hard fail
• 기존 package별 예외가 필요하면 allowlist와 사유 문서화

완료 기준

• 모든 public package가 합의된 manifest shape를 따른다
• pnpm check 또는 별도 CI step이 manifest drift를 실패로 처리한다
• scripts/normalize-packages.mjs가 check-only 모드를 지원한다
• [storage packages] Published manifests point package roots at src while only dist is shipped #578 같은 package-family 단위 문제를 전역 gate가 재발 방지한다
• CJS/ESM/TypeScript 소비 예제가 최소 1개씩 검증된다