croco-dev · kang-heewon · Jun 21, 2026 · Jun 21, 2026
diff --git a/.changeset/static-architecture-policy.md b/.changeset/static-architecture-policy.md
@@ -0,0 +1,7 @@
+---
+"@croco/architecture-policy": minor
+"@croco/cli": patch
+"create-croco-app": patch
+---
+
+Add a static architecture policy engine and CLI gate for package/layer boundaries, public entrypoint imports, and generated SaaS app policy manifests.
diff --git a/README.md b/README.md
@@ -369,7 +369,7 @@ Croco가 **완전한 SaaS 프레임워크**가 되기 위해 계획 중인 기
 
 > 이 섹션은 `pnpm docs:catalog:write`로 생성됩니다. 패키지 이름과 경로는 `packages/*/package.json`에서 읽고, 그룹/성숙도는 `docs/package-catalog.json`에서 관리합니다.
 
-현재 카탈로그는 **108개 public package**를 추적합니다. Private package 2개는 publish 카탈로그에서 제외됩니다. 문서 커버리지 상세는 [docs/package-docs-report.md](docs/package-docs-report.md)를 확인하세요.
+현재 카탈로그는 **109개 public package**를 추적합니다. Private package 2개는 publish 카탈로그에서 제외됩니다. 문서 커버리지 상세는 [docs/package-docs-report.md](docs/package-docs-report.md)를 확인하세요.
 
 ### Package Groups
 
@@ -382,7 +382,7 @@ Croco가 **완전한 SaaS 프레임워크**가 되기 위해 계획 중인 기
 | Protocol     | API protocol definitions and code generation                                               |         7 |
 | Transport    | Runtime adapters that execute protocol routes                                              |         3 |
 | Presentation | Frontend, SSR, and presentation-layer adapters                                             |         7 |
-| Tooling      | CLIs, scaffolds, presets, migration tools, and build-time helpers                          |         8 |
+| Tooling      | CLIs, scaffolds, presets, migration tools, and build-time helpers                          |         9 |
 
 ### Maturity Guide
 
@@ -391,7 +391,7 @@ Adapter 경계와 공식 우선순위, compatibility certification checklist는
 | 상태                | 의미                                | 패키지 수 |
 | ------------------- | ----------------------------------- | --------: |
 | 🟢 production-ready | 안정화, 적극 사용 권장              |        23 |
-| 🟡 beta             | 기능 완성, 실사용 검증 중           |        51 |
+| 🟡 beta             | 기능 완성, 실사용 검증 중           |        52 |
 | 🔴 alpha/WIP        | 개발 중, 사용 시 주의 필요          |        34 |
 | ⚠️ deprecated       | 대체 패키지 존재, 마이그레이션 권장 |         0 |
 
@@ -539,6 +539,7 @@ Runtime columns: Node는 장기 실행 서버/CLI, Lambda는 서버리스 함수
 | `@croco/billing-polar`        | Provider     | `packages/billing-polar`        | README, tests      |
 | `@croco/llm-openai`           | Provider     | `packages/llm-openai`           | README, API, tests |
 | `@croco/storage-r2`           | Provider     | `packages/storage-r2`           | README, tests      |
+| `@croco/architecture-policy`  | Tooling      | `packages/architecture-policy`  | README, tests      |
 | `@croco/cli`                  | Tooling      | `packages/cli`                  | README, tests      |
 | `create-croco-app`            | Tooling      | `packages/create-croco-app`     | README, API, tests |
 | `@croco/esbuild-plugin`       | Tooling      | `packages/esbuild-plugin`       | README, tests      |

diff --git a/croco.arch.json b/croco.arch.json
@@ -0,0 +1,176 @@
+{
+  "schemaVersion": "croco.architecture-policy/v1",
+  "policyName": "croco-framework",
+  "packageRoots": ["packages"],
+  "include": [
+    "packages/*/src/**/*.ts",
+    "packages/*/src/**/*.tsx",
+    "packages/*/src/**/*.mts",
+    "packages/*/src/**/*.cts"
+  ],
+  "ignore": [
+    "packages/*/src/**/__tests__/**",
+    "packages/*/src/**/tests/**",
+    "packages/*/src/**/*.spec.ts",
+    "packages/*/src/**/*.test.ts"
+  ],
+  "packageGroups": {
+    "framework": {
+      "description": "Build-time and runtime framework primitives without provider or transport implementations.",
+      "packages": [
+        "@croco/*-core",
+        "@croco/architecture-policy",
+        "@croco/cache-core",
+        "@croco/dataloader-core",
+        "@croco/diagnostics-core",
+        "@croco/events-core",
+        "@croco/events-inmemory",
+        "@croco/framework-*",
+        "@croco/gid-core",
+        "@croco/health-core",
+        "@croco/idempotency-core",
+        "@croco/pagination-core",
+        "@croco/problems-core",
+        "@croco/repository-core",
+        "@croco/retry-core",
+        "@croco/tenant-core",
+        "@croco/tx-core"
+      ]
+    },
+    "protocols": {
+      "description": "Protocol contracts and generated protocol artifacts.",
+      "packages": [
+        "@croco/admin-generated",
+        "@croco/openapi-spec",
+        "@croco/protocols-*",
+        "@croco/rpc-codegen"
+      ]
+    },
+    "transports": {
+      "description": "Runtime adapters that execute protocol routes.",
+      "packages": ["@croco/transports-*"]
+    },
+    "integrations": {
+      "description": "Concrete datastore, SaaS provider, and external service adapters.",
+      "packages": [
+        "@croco/*-drizzle",
+        "@croco/*-posthog",
+        "@croco/*-qstash",
+        "@croco/*-upstash",
+        "@croco/auth-better-auth",
+        "@croco/auth-clerk",
+        "@croco/billing-polar",
+        "@croco/events-tx",
+        "@croco/llm-openai",
+        "@croco/metrics-billing",
+        "@croco/notifications-resend",
+        "@croco/search-meilisearch",
+        "@croco/storage-cloudflare",
+        "@croco/storage-cloudinary",
+        "@croco/storage-r2",
+        "@croco/telemetry-sdk-node",
+        "@croco/tx-drizzle"
+      ]
+    },
+    "presentation": {
+      "description": "Frontend, SSR, and presentation adapters.",
+      "packages": [
+        "@croco/admin-react",
+        "@croco/frontend-*",
+        "@croco/meta-vite",
+        "@croco/presentation-preset"
+      ]
+    },
+    "app": {
+      "description": "Repository-owned CLIs, scaffolds, docs, and release tooling.",
+      "packages": [
+        "@croco/cli",
+        "@croco/docs",
+        "@croco/esbuild-plugin",
+        "@croco/migration-runner",
+        "@croco/oxlint-rules",
+        "@croco/preset-*",
+        "@croco/testing",
+        "create-croco-app"
+      ]
+    }
+  },
+  "rules": {
+    "forbiddenImports": [
+      {
+        "id": "framework-provider-package-boundary",
+        "description": "Framework and core packages must not depend on concrete provider/runtime implementation packages.",
+        "from": {
+          "groups": ["framework"]
+        },
+        "to": {
+          "packages": [
+            "@croco/*-drizzle",
+            "@croco/*-posthog",
+            "@croco/*-qstash",
+            "@croco/*-upstash",
+            "@croco/auth-better-auth",
+            "@croco/auth-clerk",
+            "@croco/billing-polar",
+            "@croco/events-tx",
+            "@croco/llm-openai",
+            "@croco/metrics-billing",
+            "@croco/notifications-resend",
+            "@croco/search-meilisearch",
+            "@croco/storage-cloudflare",
+            "@croco/storage-cloudinary",
+            "@croco/storage-r2",
+            "@croco/telemetry-sdk-node",
+            "@croco/transports-*",
+            "@croco/tx-drizzle"
+          ]
+        },
+        "message": "Framework/core packages cannot import provider or runtime implementation packages.",
+        "recovery": "Move provider/runtime implementation code behind an adapter package and keep the framework/core package on an explicit contract."
+      },
+      {
+        "id": "framework-provider-sdk-boundary",
+        "description": "Framework and core packages must not depend on concrete provider/runtime SDKs.",
+        "from": {
+          "groups": ["framework"]
+        },
+        "to": {
+          "specifiers": [
+            "@clerk/*",
+            "@hono/node-server",
+            "@polar-sh/*",
+            "@upstash/*",
+            "cloudinary",
+            "cloudinary/*",
+            "drizzle-orm",
+            "drizzle-orm/*",
+            "hono",
+            "hono/*",
+            "ioredis",
+            "ioredis/*"
+          ]
+        },
+        "message": "Framework/core packages cannot import provider or runtime implementation SDKs.",
+        "recovery": "Move provider/runtime implementation code behind an adapter package and keep the framework/core package on an explicit contract."
+      }
+    ],
+    "publicEntrypoints": {
+      "id": "croco-public-entrypoints",
+      "description": "Production source imports between Croco packages must use declared package exports instead of src/dist internals.",
+      "includePackages": ["@croco/*"],
+      "ignoreImports": [
+        {
+          "paths": [
+            "packages/*/src/**/__tests__/**",
+            "packages/*/src/**/tests/**",
+            "packages/*/src/**/*.spec.ts",
+            "packages/*/src/**/*.test.ts"
+          ],
+          "specifiers": ["@croco/*/src/**"]
+        }
+      ],
+      "message": "Croco packages must import declared public entrypoints instead of private package internals.",
+      "recovery": "Export the needed surface from the target package or move the test-only alias behind an explicit test/config ignore."
+    }
+  }
+}
diff --git a/docs/architecture-policy.md b/docs/architecture-policy.md
@@ -0,0 +1,36 @@
+# Architecture Policy Check
+
+`pnpm architecture-policy:check` validates `croco.arch.json` with the
+`@croco/architecture-policy` engine. The gate runs through `pnpm check`.
+
+The policy manifest is a build-time contract for package and layer boundaries:
+
+- package groups such as `framework`, `protocols`, `transports`, `integrations`,
+  `presentation`, and `app`;
+- forbidden imports from framework/core packages into provider or runtime implementations;
+- allowed group edges for generated app packages;
+- public entrypoint imports so package consumers do not reach into `src` or `dist` internals;
+- deterministic diagnostics with file, line, column, diagnostic code, import specifier, and
+  recovery guidance.
+
+This gate is intentionally not a replacement for oxlint, oxfmt, Biome, TypeScript, or
+`static-misuse:check`.
+
+| Gate                        | Owns                                                                                                  |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `architecture-policy:check` | Croco package groups, layer edges, package manifest dependencies, public entrypoint import boundaries |
+| `static-misuse:check`       | Narrow line-oriented misuse patterns that are easier to express as source text checks                 |
+| `oxlint` / `oxfmt` / Biome  | Syntax, style, unused symbols, and lint rules that do not need Croco package context                  |
+| `typecheck`                 | TypeScript type contracts and emitted declaration compatibility                                       |
+| `public-api:check`          | Export snapshot drift for publishable package entrypoints                                             |
+
+Generated SaaS apps receive their own `croco.arch.json` and an
+`architecture-policy:check` script:
+
+```bash
+croco architecture-policy check --manifest croco.arch.json
+```
+
+The generated policy uses the same engine as this repository. Its manifest keeps app entrypoints,
+provider packages, generated provider RPC contracts, Croco framework/protocol packages, selected
+integrations, and external SDKs in explicit groups before demo smoke tests run.
diff --git a/docs/package-catalog.json b/docs/package-catalog.json
@@ -135,6 +135,7 @@
     "Tooling": {
       "description": "CLIs, scaffolds, presets, migration tools, and build-time helpers",
       "packages": [
+        "architecture-policy",
         "cli",
         "create-croco-app",
         "esbuild-plugin",
@@ -181,6 +182,7 @@
         "access-core",
         "admin-core",
         "admin-ops",
+        "architecture-policy",
         "billing-polar",
         "cache-core",
         "cli",

diff --git a/docs/package-docs-baseline.json b/docs/package-docs-baseline.json
@@ -7,6 +7,7 @@
     "admin-core",
     "admin-react",
     "analytics-posthog",
+    "architecture-policy",
     "audit-drizzle",
     "auth-better-auth",
     "auth-clerk",

diff --git a/docs/package-docs-report.md b/docs/package-docs-report.md
@@ -6,10 +6,10 @@
 
 | Metric                         | Count |
 | ------------------------------ | ----: |
-| Public packages                |   108 |
+| Public packages                |   109 |
 | Private packages skipped       |     2 |
 | Missing package README         |     0 |
-| Missing generated API docs     |    58 |
+| Missing generated API docs     |    59 |
 | Missing package test directory |     0 |
 | Extension matrix packages      |    41 |
 
@@ -26,6 +26,7 @@ None.
 - `@croco/admin-core` (`packages/admin-core`) — legacy baseline
 - `@croco/admin-react` (`packages/admin-react`) — legacy baseline
 - `@croco/analytics-posthog` (`packages/analytics-posthog`) — legacy baseline
+- `@croco/architecture-policy` (`packages/architecture-policy`) — legacy baseline
 - `@croco/audit-drizzle` (`packages/audit-drizzle`) — legacy baseline
 - `@croco/auth-better-auth` (`packages/auth-better-auth`) — legacy baseline
 - `@croco/auth-clerk` (`packages/auth-clerk`) — legacy baseline
@@ -85,7 +86,7 @@ None.
 | Maturity            | Missing API docs |
 | ------------------- | ---------------: |
 | 🟢 production-ready |                0 |
-| 🟡 beta             |               28 |
+| 🟡 beta             |               29 |
 | 🔴 alpha/WIP        |               30 |
 | ⚠️ deprecated       |                0 |
 
@@ -104,12 +105,12 @@ None.
 | Protocol     |        7 |
 | Transport    |        3 |
 | Presentation |        7 |
-| Tooling      |        8 |
+| Tooling      |        9 |
 
 | Maturity            | Packages |
 | ------------------- | -------: |
 | 🟢 production-ready |       23 |
-| 🟡 beta             |       51 |
+| 🟡 beta             |       52 |
 | 🔴 alpha/WIP        |       34 |
 | ⚠️ deprecated       |        0 |