fix: harden presentation runtime smoke contract

[kang-heewon]

Fixes #828.

Summary

Presentation runtime readiness is now documented as an explicit support matrix instead of being inferred from package tests. The package catalog and generated docs call out the stable ISR v1 exact-key TTL contract, Worker ISR durability requirements, and the promotion gates that keep presentation packages from being marked production-ready without named runtime evidence.

Generated meta-vite profiles now include a zero-credential presentation:smoke command that dispatches an SSR page, API route, server action, and ISR route through current local Croco presentation package tarballs. The generated smoke matrix also builds and packs the local presentation packages before app install, so generated-app checks exercise the current publishable artifacts rather than stale registry ranges.

Cloudflare and Lambda adapter coverage now proves the runtime handoff points needed by the matrix: Cloudflare asset fallback, service-binding routing, env/execution-context propagation, streaming response preservation, and Lambda API handlers receiving the original event/context.

Verification

• pnpm --filter @croco/meta-vite exec vitest run src/tests/lambda-adapter.spec.ts src/tests/cloudflare-adapter.spec.ts src/tests/isr-middleware.spec.ts src/tests/redis-adapter.spec.ts src/tests/server-action.spec.ts --maxWorkers=1
• pnpm --filter @croco/frontend-cloudflare exec vitest run src/tests/CloudflareSsrHandler.spec.ts --maxWorkers=1
• pnpm --filter create-croco-app exec vitest run src/tests/e2e-generation.spec.ts --maxWorkers=1
• pnpm docs:catalog:check
• pnpm create-croco-app:smoke
• pnpm check
• pnpm changeset-required:check -- --base origin/trunk --head HEAD
• Pre-push hook: full pnpm test and pnpm typecheck

Self-review gates

• Correctness/regression: PASS. Generated meta-vite apps now run page/API/action/ISR smoke against local package tarballs, and focused adapter tests cover the runtime handoff claims documented in the matrix.
• API/security/compatibility/release: PASS. No public API or maturity promotion is introduced; Worker durable ISR is documented as requiring an external Worker-safe IsrCacheStore; generated templates add only a dev-only tsx smoke dependency and a create-croco-app patch changeset.
• Maintainability/minimality: PASS. Changes are scoped to smoke coverage, adapter tests, docs/catalog generation, and generated template smoke files.

Risk

The generated smoke command is intentionally synthetic and zero-credential. It proves route dispatch and cache semantics, not a deployed Cloudflare or Lambda environment.

Summary by CodeRabbit

릴리스 노트

• 새로운 기능

  • Presentation smoke 검증 기능 추가 (페이지, API, server-action, ISR 라우트 대상)
  • ISR v1 exact-key TTL 지원 공식화

• 문서

  • Presentation Runtime Support 문서 추가
  • ISR v1 계약 조건 및 Production Runtime Matrix 명시
  • 확장 행렬 및 패키지 카탈로그 업데이트

• 테스트

  • E2E 생성 테스트 강화 및 람다 어댑터 테스트 추가

[coderabbitai]

Warning

Review limit reached

@kang-heewon, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 40 minutes and 28 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: be944ee1-8463-4013-8984-fbe80e7fab36

📥 Commits

Reviewing files that changed from the base of the PR and between c131c49 and af8e1bb.

📒 Files selected for processing (2)

• packages/docs/src/content/docs/en/reference/extension-matrix.md
• scripts/package-docs-check.mts

📝 Walkthrough

Walkthrough

meta-vite 생성 템플릿(web, ssr-worker) 두 곳에 SSR/ISR/API/서버액션 라우트를 통합 검증하는 presentationSmoke.ts 스크립트와 tsx 의존성이 추가됩니다. 생성 스모크 파이프라인, E2E 테스트, Cloudflare/Lambda 어댑터 테스트가 보강되고, ISR v1 계약·런타임 매트릭스가 문서와 패키지 카탈로그에 반영됩니다.

Changes

Presentation Smoke 통합 및 문서화

Layer / File(s)	Summary
presentationSmoke.ts 구현 (web 및 ssr-worker 템플릿) packages/create-croco-app/templates/addons/web-meta-vite/src/smoke/presentationSmoke.ts, packages/create-croco-app/templates/addons/web-meta-vite-fullstack/ssr-worker/src/smoke/presentationSmoke.ts	두 템플릿 각각에 SmokeResponseCache(TTL 기반 IsrCacheStore 구현), assert/expectText 헬퍼, main()에서 SSR(/)/ISR(/cached)/API(/api/ping)/서버액션(subscribe)을 등록하고 캐시 히트까지 검증하는 스크립트가 추가됩니다.
템플릿 package.json.hbs에 스크립트 및 의존성 추가 packages/create-croco-app/templates/addons/web-meta-vite/package.json.hbs, packages/create-croco-app/templates/addons/web-meta-vite-fullstack/ssr-worker/package.json.hbs	두 템플릿 모두에 presentation:smoke 스크립트(tsx src/smoke/presentationSmoke.ts)와 tsx ^4.20.3 devDependency가 추가됩니다.
E2E 생성 테스트 및 생성 스모크 파이프라인 연결 packages/create-croco-app/src/tests/e2e-generation.spec.ts, scripts/create-croco-app-generated-smoke.mts, .changeset/meta-vite-presentation-smoke.md	E2E 테스트에 presentation:smoke 스크립트·tsx 버전·파일 생성·베어 import 검증이 추가됩니다. 생성 스모크 스크립트에 presentation:smoke 실행 단계, 추가 패키지 필터(@croco/frontend-cloudflare 등), file: 오버라이드 확장이 포함됩니다.
Cloudflare SSR 핸들러 및 Lambda 어댑터 테스트 보강 packages/frontend-cloudflare/src/tests/CloudflareSsrHandler.spec.ts, packages/meta-vite/src/tests/lambda-adapter.spec.ts	createExecutionContext/createStream 헬퍼 도입, ASSETS 바인딩 200/404 분기, 플랫폼 컨텍스트 전달, 스트리밍 청크 보존, Lambda 이벤트/컨텍스트 수신 검증 테스트가 추가됩니다.
ISR v1 계약 및 런타임 매트릭스 문서화 packages/meta-vite/README.md, packages/docs/src/content/docs/en/reference/presentation-runtime-support.md	meta-vite/README.md에 Production Runtime Matrix 표와 ISR v1 Contract 규칙이 추가됩니다. 신규 presentation-runtime-support.md에 런타임 기능 매트릭스, ISR v1 계약, Beta gate 체크리스트, 카탈로그 승격 규칙이 정의됩니다.
패키지 카탈로그·extension matrix·README 갱신 docs/package-catalog.json, packages/docs/src/content/docs/en/reference/extension-matrix.md, README.md, scripts/package-docs-check.mts	package-catalog.json의 4개 패키지 항목에 features/requiredEnv가 확장되고, extension-matrix.md와 README.md에 Presentation Runtime Support 참조가 추가되며, package-docs-check.mts의 안내 문구도 확장됩니다.

Sequence Diagram(s)

sequenceDiagram
  participant CI as CI / generate-smoke 스크립트
  participant Template as create-croco-app 템플릿
  participant SmokeScript as presentationSmoke.ts
  participant RouteRegistry
  participant RenderServer
  participant IsrMiddleware as createIsrMiddleware
  participant SmokeResponseCache

  CI->>Template: 앱 생성 (meta-vite-web / fullstack-workers)
  CI->>SmokeScript: pnpm presentation:smoke 실행
  SmokeScript->>RouteRegistry: / (SSR), /cached (ISR, revalidate=60), /api/ping, subscribe 등록
  SmokeScript->>RenderServer: new RenderServer(compiled)
  SmokeScript->>SmokeResponseCache: new SmokeResponseCache()
  SmokeScript->>IsrMiddleware: createIsrMiddleware(renderServer, cache)
  SmokeScript->>SmokeScript: fetch("/") → expectText 검증
  SmokeScript->>SmokeScript: fetch("/api/ping") → JSON 검증
  SmokeScript->>SmokeScript: POST subscribe → 결과 검증
  SmokeScript->>IsrMiddleware: fetch("/cached") 1회
  IsrMiddleware->>SmokeResponseCache: 캐시 미스 → 렌더 후 저장
  SmokeScript->>IsrMiddleware: fetch("/cached") 2회
  IsrMiddleware->>SmokeResponseCache: 캐시 히트 (renderCount === 1 검증)
  SmokeScript->>CI: 성공 로그 출력 / 실패 시 exitCode=1

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• croco-dev/framework#760: docs/package-catalog.json 및 extension matrix 메타데이터를 Presentation 런타임 기능 설명(meta-vite, presentation-preset 등)으로 확장하는 작업으로, 이번 PR의 카탈로그/매트릭스 갱신과 직접적으로 연관됩니다.
• croco-dev/framework#819: packages/create-croco-app/src/tests/e2e-generation.spec.ts 및 scripts/create-croco-app-generated-smoke.mts에서 saas 프리셋 스모크 경로를 추가한 PR로, 이번 PR이 동일한 테스트/스모크 플러밍에 presentation:smoke를 추가하는 방식과 같은 수준에서 연관됩니다.

🚥 Pre-merge checks | ✅ 5 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR 제목은 presentation runtime smoke contract을 강화한다는 핵심 변경사항을 명확하게 요약하고 있습니다.
Linked Issues check	✅ Passed	PR은 #828의 모든 핵심 요구사항을 충족합니다: 런타임 지원 매트릭스 정의, ISR v1 exact-key TTL 계약 문서화, Cloudflare/Lambda 어댑터 smoke 테스트 추가, 생성된 앱 smoke 커버리지 확대, 패키지 프로모션 게이트 설정.
Out of Scope Changes check	✅ Passed	모든 변경사항이 #828의 목표 범위 내입니다. Smoke 테스트, 어댑터 검증, 문서화, 생성 템플릿 확대만 포함되며 새 공개 API나 부작용 있는 기능은 없습니다.
Description check	✅ Passed	PR 설명이 변경사항의 목적(presentation runtime 준비도 강화), 구현(smoke 테스트, 어댑터 검증, 문서화), 범위(dev-only 변경, 공개 API 추가 없음)를 명확히 제시합니다.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/828-presentation-production

---

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.}

[github-actions]

📊 Benchmark Results

❌ Some benchmarks failed

Gate failures

• Lambda cold-start simulation: p75 217.2μs exceeds baseline 70.2μs by more than 20%
• Lambda cold-start with headers: p75 147.2μs exceeds baseline 66.7μs by more than 20%
• Lambda cold-start with binary body: p75 129.7μs exceeds baseline 63.2μs by more than 20%
• Lambda cold-start with query params: p75 114.0μs exceeds baseline 63.9μs by more than 20%
• Lambda cold-start with authorizer context: p75 118.7μs exceeds baseline 59.8μs by more than 20%
• Lambda cold-start realistic scenario: p75 115.4μs exceeds baseline 60.2μs by more than 20%
• EventBusConfig.start (10 handlers): p75 1.3μs exceeds baseline 0.9μs by more than 20%
• EventPublisher.publishNow single event: p75 1.6μs exceeds baseline 1.1μs by more than 20%
• DefaultHandlerResolver.resolve × 10: p75 0.1μs exceeds baseline 0.0μs by more than 20%
• Container.get singleton (cold): p75 1.0μs exceeds baseline 0.6μs by more than 20%
• Container.get singleton (warm): p75 0.4μs exceeds baseline 0.3μs by more than 20%
• lambdaPreset config creation: p75 1.5μs exceeds baseline 1.0μs by more than 20%

Benchmark	p75	Threshold	Baseline	vs Baseline	Status	Notes
CrocoApp constructor	3.2μs	30.0ms	3.4μs	-5.3%	✅	-
CrocoApp lambdaHandler (10 controllers)	39.3μs	50.0ms	33.3μs	+18.0%	✅	-
Lambda cold-start simulation	217.2μs	80.0ms	70.2μs	+209.5%	❌	-
Lambda cold-start with headers	147.2μs	80.0ms	66.7μs	+120.6%	❌	-
Lambda cold-start with binary body	129.7μs	80.0ms	63.2μs	+105.3%	❌	-
Lambda cold-start with query params	114.0μs	80.0ms	63.9μs	+78.5%	❌	-
Lambda cold-start with authorizer context	118.7μs	80.0ms	59.8μs	+98.5%	❌	-
Lambda cold-start realistic scenario	115.4μs	80.0ms	60.2μs	+91.8%	❌	-
EventBusConfig.start (10 handlers)	1.3μs	10.0ms	0.9μs	+48.8%	❌	-
EventPublisher.publishNow single event	1.6μs	2.0ms	1.1μs	+44.2%	❌	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.0μs	+69.0%	❌	-
Container.get singleton (cold)	1.0μs	5.0ms	0.6μs	+52.3%	❌	-
Container.register × 50 components	11.7μs	10.0ms	12.1μs	-3.9%	✅	-
Container.validate (50 components)	29.3μs	20.0ms	29.7μs	-1.4%	✅	-
Container.get singleton (warm)	0.4μs	500.0μs	0.3μs	+44.2%	❌	-
TelemetryRuntime.init (lambda preset)	1.1ms	200.0ms	69.3ms	-98.4%	✅	-
lambdaPreset config creation	1.5μs	2.0ms	1.0μs	+46.3%	❌	-

_{Updated: 2026-06-17T12:35:05.138Z · Commit: 76c8ce3}

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@scripts/package-docs-check.mts`:
- Line 977: The relative paths in the documentation links are incorrect because
they point to parent directories instead of the same reference directory. In the
string containing the Korean text with Provider Maturity Gates and Presentation
Runtime Support links, change the relative path references from
`../provider-maturity/` and `../presentation-runtime-support/` to use correct
relative paths like `./provider-maturity.md` and
`./presentation-runtime-support.md` (since both files are in the same reference
directory), or alternatively use absolute paths following the pattern shown in
line 977 with the full path starting from
packages/docs/src/content/docs/en/reference/.

🪄 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: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e8531ac5-947d-4854-99c9-4442135dbf75

📥 Commits

Reviewing files that changed from the base of the PR and between f27c1dd and c131c49.

📒 Files selected for processing (15)

• .changeset/meta-vite-presentation-smoke.md
• README.md
• docs/package-catalog.json
• packages/create-croco-app/src/tests/e2e-generation.spec.ts
• packages/create-croco-app/templates/addons/web-meta-vite-fullstack/ssr-worker/package.json.hbs
• packages/create-croco-app/templates/addons/web-meta-vite-fullstack/ssr-worker/src/smoke/presentationSmoke.ts
• packages/create-croco-app/templates/addons/web-meta-vite/package.json.hbs
• packages/create-croco-app/templates/addons/web-meta-vite/src/smoke/presentationSmoke.ts
• packages/docs/src/content/docs/en/reference/extension-matrix.md
• packages/docs/src/content/docs/en/reference/presentation-runtime-support.md
• packages/frontend-cloudflare/src/tests/CloudflareSsrHandler.spec.ts
• packages/meta-vite/README.md
• packages/meta-vite/src/tests/lambda-adapter.spec.ts
• scripts/create-croco-app-generated-smoke.mts
• scripts/package-docs-check.mts

Dismissed stale CodeRabbit requested-changes review after resolving the only thread and verifying the suggested link form failed docs-links while the restored route-relative links pass current CI on d9e3dc6.