fix: make the public SaaS scaffold journey executable

[kang-heewon]

Fixes #1313.

Summary

• Makes every public first-success command generate the same REST SaaS workspace through the real Commander registration and production normalization path.
• Derives documentation runtime assertions from generated scaffold artifacts and validates the zero-credential demo:smoke success state.
• Extends generated-app and packed-release smoke coverage with a distinct canonical SaaS case while preserving the production-app case.
• Publishes the corrected journey in all four public entry points and includes a patch changeset.

Verification

• pnpm test — 225/225 tasks passed.
• pnpm typecheck — 224/224 tasks passed.
• pnpm check — passed.
• Focused release and first-success specs — 36/36 passed.
• create-croco-app option specs — 47/47 passed.
• pnpm first-success:verify — passed.
• pnpm create-croco-app:smoke — all 16 cases passed.
• pnpm alpha-release:smoke — packed production-app and canonical SaaS cases passed.
• pnpm changeset-required:check — passed.

Self-review

• Correctness/regression: shared CLI parsing, hostile invalid inputs, generator-derived drift, cleanup, and full repository tests passed.
• API/security/release: no dependency or credential path was added; packed installs are tested outside the checkout; release routing and changeset coverage are present.
• Maintainability: removed the verifier-local option schema and reused existing generated-app and alpha-release smoke infrastructure.

Review and QA

• Independent code review: APPROVE, no actionable findings.
• Independent architecture review: CLEAR.
• UltraQA: PASS after one cycle.

Residual risk

• Non-public pnpm create, pnpm dlx, and direct executable launcher extraction branches are not individually mutation-tested. All current public commands use the verified npx form.

Summary by CodeRabbit

• 새 기능

  • saas-api 목표로 REST SaaS 프로젝트를 생성하고, 외부 자격 증명 없이 데모 스모크 테스트를 실행할 수 있습니다.
  • CLI가 프로젝트 범위, SaaS 프로필, 배포 옵션 등 다양한 설정을 지원합니다.

• 문서

  • 빠른 시작 및 시작하기 가이드를 새로운 REST SaaS 생성 흐름에 맞게 업데이트했습니다.
  • 생성된 API 라우트, 데모 실행, 계약 검증 절차를 문서화했습니다.

• 버그 수정 및 검증

  • CLI 생성 결과와 공개 문서의 불일치를 자동으로 감지합니다.
  • 여러 생성 시나리오와 데모 흐름에 대한 릴리스 스모크 검증을 강화했습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 21a52976-9e3c-44fd-8157-2a73c53b60ee

📥 Commits

Reviewing files that changed from the base of the PR and between 88494b8 and 9354fe8.

📒 Files selected for processing (20)

• .changeset/canonical-saas-first-success.md
• .github/workflows/release.yml
• README.md
• package.json
• packages/create-croco-app/README.md
• packages/create-croco-app/src/cli-program.ts
• packages/create-croco-app/src/cli.ts
• packages/create-croco-app/src/tests/options.spec.ts
• packages/create-croco-app/src/verification.ts
• packages/create-croco-app/tsup.config.ts
• packages/docs/src/content/docs/en/guides/getting-started.mdx
• packages/docs/src/content/docs/en/index.mdx
• scripts/alpha-release-smoke.mts
• scripts/create-croco-app-generated-smoke.mts
• scripts/first-success-generated-contract.mts
• scripts/first-success-verify.mts
• scripts/tests/alpha-release-smoke.spec.ts
• scripts/tests/first-success-verify.spec.ts
• scripts/tests/release-workflow.spec.ts
• tsconfig/contract-strict.baseline.json

---

📝 Walkthrough

Walkthrough

create-croco-app의 실제 CLI 계약을 분리하고, canonical saas-api 생성 경로를 README·가이드·스모크 테스트와 연결했습니다. first-success 검증은 실제 CLI 생성물과 런타임 문서 계약을 검사하며, 관련 릴리스 게이트도 갱신되었습니다.

Changes

Canonical SaaS first-success

Layer / File(s)	Summary
CLI 계약과 빌드 표면 package.json, packages/create-croco-app/src/*, packages/create-croco-app/tsup.config.ts, tsconfig/contract-strict.baseline.json	Commander 옵션 구성을 별도 모듈로 분리하고, 검증용 export와 빌드 엔트리를 추가했습니다.
Canonical saas-api 문서 경로 README.md, packages/create-croco-app/README.md, packages/docs/src/content/docs/en/...	문서의 생성 명령을 --goal saas-api 기반 REST SaaS 흐름으로 변경하고 pnpm demo:smoke 실행 절차를 추가했습니다.
생성 앱 스모크 케이스 scripts/alpha-release-smoke.mts, scripts/create-croco-app-generated-smoke.mts, scripts/tests/alpha-release-smoke.spec.ts	생성 앱 스모크를 다중 케이스로 확장하고 canonical saas-api 및 demo:smoke 검증을 포함했습니다.
실행 기반 first-success 검증 scripts/first-success-*.mts, scripts/tests/first-success-verify.spec.ts	문서화된 CLI를 실제로 실행해 생성물을 만들고, 생성된 SaaS 런타임·README·문서 계약을 검증하도록 변경했습니다.
릴리스 게이트 연결 .changeset/*, .github/workflows/release.yml, scripts/tests/release-workflow.spec.ts	생성 계약 검증 스크립트 변경이 릴리스 게이트 maintenance self-check를 실행하도록 연결했습니다.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant FirstSuccessVerify
  participant CreateCrocoAppProgram
  participant Generator
  participant GeneratedSaasWorkspace
  participant DocsContractValidator
  FirstSuccessVerify->>CreateCrocoAppProgram: documented command 파싱
  CreateCrocoAppProgram->>Generator: 옵션 정규화 및 생성
  Generator->>GeneratedSaasWorkspace: SaaS manifest, routes, README 생성
  FirstSuccessVerify->>DocsContractValidator: 생성물 및 문서 계약 검증
  DocsContractValidator-->>FirstSuccessVerify: 실패 메시지 반환

Loading

Possibly related PRs

• croco-dev/framework#1163: 릴리스 게이트 maintenance 패턴과 first-success 검증 경로가 연결됩니다.
• croco-dev/framework#1205: 동일한 release-gate maintenance 트리거 로직을 변경합니다.
• croco-dev/framework#1208: 특정 scripts/* 변경에 대한 릴리스 게이트 트리거를 확장합니다.

Suggested reviewers: ddarkr, croco-admin

🚥 Pre-merge checks | ✅ 4 | ❌ 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 (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목이 public SaaS scaffold 여정을 실행 가능하게 만드는 핵심 변경을 간결하게 잘 요약합니다.
Linked Issues check	✅ Passed	실제 CLI 등록과 생성물 기반 검증, package README 포함, canonical saas-api 스모크 추가 등 링크된 요구사항을 충족합니다.
Out of Scope Changes check	✅ Passed	변경된 문서, 검증 스크립트, 워크플로, 테스트는 모두 공용 scaffold 여정과 first-success 검증 범위 안에 있습니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/1313-first-success-journey

---

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

[github-actions]

📊 Benchmark Results

✅ All benchmarks passed

Benchmark	p75	Threshold	Baseline	vs Baseline	Status	Notes
CrocoApp constructor	8.1μs	30.0ms	8.2μs	-0.5%	✅	-
CrocoApp lambdaHandler (10 controllers)	308.2μs	50.0ms	258.4μs	+19.3%	✅	-
Lambda cold-start simulation	479.9μs	80.0ms	418.1μs	+14.8%	✅	-
Lambda cold-start with headers	385.7μs	80.0ms	369.7μs	+4.3%	✅	-
Lambda cold-start with binary body	362.5μs	80.0ms	339.1μs	+6.9%	✅	-
Lambda cold-start with query params	307.7μs	80.0ms	301.3μs	+2.1%	✅	-
Lambda cold-start with authorizer context	314.0μs	80.0ms	299.8μs	+4.7%	✅	-
Lambda cold-start realistic scenario	310.4μs	80.0ms	299.2μs	+3.8%	✅	-
EventBusConfig.start (10 handlers)	1.5μs	10.0ms	1.4μs	+3.5%	✅	-
EventPublisher.publishNow single event	1.7μs	2.0ms	1.7μs	+1.2%	✅	-
DefaultHandlerResolver.resolve × 10	0.1μs	5.0ms	0.1μs	-11.2%	✅	-
Container.get singleton (cold)	75.6μs	5.0ms	70.3μs	+7.6%	✅	-
Container.register × 50 components	3.3ms	10.0ms	3.2ms	+2.7%	✅	-
Container.validate (50 components)	3.8ms	20.0ms	3.4ms	+12.5%	✅	-
Container.get singleton (warm)	1.7μs	500.0μs	1.6μs	+1.2%	✅	-
TelemetryRuntime.init (lambda preset)	2.0μs	200.0ms	1.1ms	-99.8%	✅	-
lambdaPreset config creation	1.4μs	2.0ms	1.4μs	-2.0%	✅	-

_{Updated: 2026-07-11T16:09:22.241Z · Commit: 0b334dc}