prodkit 0.1.3__tar.gz → 0.2.1__tar.gz

{prodkit-0.1.3 → prodkit-0.2.1}/.gitignore

@@ -24,4 +24,5 @@ dist/
 Thumbs.db
 LI.MD
 PUB.MD
-EX.MD
+EX.MD
+ss.md

prodkit-0.2.1/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-07-23
+
+### Changed
+- README polish: PyPI/Python badges, table of contents, `prodkit[cli]` install
+  note, rate-limiting shown in the config examples, and a `doctor()` hook in the
+  plugin-authoring example. Docs-only release (no code changes).
+
+## [0.2.0] - 2026-07-22
+
+### Added
+- **`prodkit` CLI** (install with `pip install prodkit[cli]`):
+  - `prodkit doctor` — production-readiness audit with a weighted 0–100 score;
+    `--strict --min-score N` turns it into a CI gate (non-zero exit below the
+    threshold).
+  - `prodkit inspect` — resolved config, active plugins, and middleware order.
+  - `prodkit plugins` — active plugins and the hooks each implements.
+  - `prodkit init [--example]` — scaffold a `prodkit.toml` (and starter app).
+- **`Plugin.doctor(ctx)` hook** returning `Audit` findings; implemented by every
+  built-in plugin. `Audit` (name, status `ok`/`warn`/`fail`, detail,
+  recommendation, weight) is exported from the top-level package.
+- Kernel doctor engine (`prodkit.core.doctor`) aggregating plugin audits with
+  config-level checks (environment, debug, disabled rate-limiting, low-entropy
+  secrets in the environment) into a score.
+- **Rate-limiting plugin** (`rate-limit`, off by default): in-memory
+  fixed-window per-IP limiting (`rate_limit={"default": "100/minute"}`),
+  returning `429 application/problem+json` with a `Retry-After` header. Logs a
+  per-process-backend warning (shared Redis backend arrives in v0.3).
+
+### Changed
+- Error responses now include an `instance` member (the request path). All
+  framework errors — including the rate limiter's 429 — share one
+  `problem_response` builder for a consistent RFC 9457 shape.
+
+## [0.1.3] - 2026-07-20
+
+### Changed
+- README updated (badge cleanup); republished so the PyPI project page shows
+  the current README.
+
+## [0.1.1] - 2026-07-20
+
+### Fixed
+- README links that were relative (LICENSE, docs/ARCHITECTURE.md,
+  CONTRIBUTING.md, SECURITY.md) now use absolute GitHub URLs so they work on
+  the PyPI project page.
+
+### Changed
+- Package author set to Pushkar Pant with contact email; author section added
+  to the README.
+
+## [0.1.0] - 2026-07-16
+
+### Added
+- Kernel: layered configuration (args > env > `prodkit.toml` > profile > defaults),
+  plugin manager with dependency topological sort, service registry, event bus,
+  lifespan composition, fail-fast config validation.
+- Plugin contract with async startup/shutdown hooks and prioritized middleware
+  registration.
+- Environment profiles: `development`, `staging`, `production`.
+- Built-in plugins: `request-id`, `logging` (structured JSON/console), `errors`
+  (RFC 9457 problem+json), `health` (`/health`, `/ready`, `/live`), `security`
+  (security headers, trusted hosts, HTTPS redirect), `cors`, `compression` (gzip).
+- `Production(app)` one-line entrypoint.

{prodkit-0.1.3 → prodkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prodkit
-Version: 0.1.3
+Version: 0.2.1
 Summary: The production framework for FastAPI. One line. Production ready.
 Project-URL: Homepage, https://github.com/Pushkarpant/PRODKIT
 Project-URL: Documentation, https://github.com/Pushkarpant/PRODKIT#readme
@@ -30,14 +30,19 @@ Requires-Dist: pydantic>=2.5
 Requires-Dist: tomli>=2.0; python_version < '3.11'
 Provides-Extra: brotli
 Requires-Dist: brotli-asgi>=1.4; extra == 'brotli'
+Provides-Extra: cli
+Requires-Dist: rich>=13; extra == 'cli'
+Requires-Dist: typer>=0.12; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: import-linter>=2.0; extra == 'dev'
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: rich>=13; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: tomli>=2.0; extra == 'dev'
+Requires-Dist: typer>=0.12; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # ProdKit
@@ -56,14 +61,24 @@ Production(app)
 
 That's it. Your app now has security headers, structured JSON logging with
 request-ID correlation, RFC 9457 error responses, Kubernetes-ready health
-endpoints, and gzip compression — configured to current best practice,
-hardened for production, and pleasant in development.
+endpoints, gzip compression, and opt-in rate limiting — configured to current
+best practice, hardened for production, and pleasant in development. Then run
+[`prodkit doctor`](#cli--prodkit-doctor) to score how production-ready it is.
 
+[![PyPI](https://img.shields.io/pypi/v/prodkit.svg)](https://pypi.org/project/prodkit/)
+[![Python](https://img.shields.io/pypi/pyversions/prodkit.svg)](https://pypi.org/project/prodkit/)
 [![CI](https://github.com/Pushkarpant/PRODKIT/actions/workflows/ci.yml/badge.svg)](https://github.com/Pushkarpant/PRODKIT/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Pushkarpant/PRODKIT/blob/main/LICENSE)
 
 ---
 
+**Contents:** [Why](#why) · [Install](#installation) · [Quick Start](#quick-start) ·
+[What You Get](#what-you-get) · [Configuration](#configuration) ·
+[Plugins](#writing-a-plugin) · [CLI / doctor](#cli--prodkit-doctor) ·
+[Status & Roadmap](#project-status)
+
+---
+
 ## Why
 
 Every production FastAPI service re-implements the same ~500 lines of glue:
@@ -79,11 +94,13 @@ evolve, `pip install -U prodkit` updates every app you own.
 [**`pip install prodkit`**](https://pypi.org/project/prodkit/)
 
 ```bash
-pip install prodkit
+pip install prodkit           # the library
+pip install "prodkit[cli]"    # + the `prodkit doctor` CLI (typer + rich)
 ```
 
 Requires Python 3.10+ and FastAPI 0.110+. The base install depends only on
-FastAPI and Pydantic — nothing else.
+FastAPI and Pydantic — nothing else. Optional extras: `cli` (CLI),
+`brotli` (Brotli compression).
 
 ## Quick Start
 
@@ -111,7 +128,9 @@ x-content-type-options: nosniff
 x-frame-options: DENY
 strict-transport-security: max-age=63072000; includeSubDomains
 referrer-policy: strict-origin-when-cross-origin
-...
+permissions-policy: camera=(), microphone=(), geolocation=()
+x-xss-protection: 0
+content-type: application/json
 ```
 
 For local development, flip the profile — pretty console logs, debug error
@@ -132,7 +151,9 @@ Production(app, environment="development")
 | ❤️ **Health endpoints** | `/health`, `/live` (liveness) and `/ready` (readiness — aggregates checks from every plugin, 503 until all pass). Kubernetes-native. |
 | 🌐 **CORS** | Explicit origins only; the wildcard-with-credentials footgun is refused at boot. |
 | 📦 **Compression** | Gzip for responses over 500 bytes. |
-| 🔌 **Plugin system** | Every feature above is a plugin. Write your own with 6 optional hooks. |
+| 🚦 **Rate limiting** | Opt-in per-IP limiting (`100/minute`), `429 problem+json` with `Retry-After`. In-memory backend (Redis in v0.3). |
+| 🩺 **`prodkit doctor`** | CLI production-readiness audit with a 0–100 score. `--strict` gates CI. |
+| 🔌 **Plugin system** | Every feature above is a plugin. Write your own with optional hooks incl. `doctor()`. |
 
 ## Configuration
 
@@ -151,6 +172,7 @@ Production(
     cors={"origins": ["https://app.example.com"]},   # dict = configure & enable
     compression=False,                                # bool = toggle
     security={"trusted_hosts": ["api.example.com"]},
+    rate_limit={"default": "100/minute"},             # opt-in per-IP limiting
 )
 ```
 
@@ -174,6 +196,10 @@ level = "INFO"
 [cors]
 enabled = true
 origins = ["https://app.example.com"]
+
+[rate_limit]
+enabled = true
+default = "100/minute"
 ```
 
 ### Fail-fast, refuse-unsafe
@@ -195,7 +221,7 @@ not warned about:
 ## Writing a Plugin
 
 ```python
-from prodkit import Check, Plugin, Production
+from prodkit import Audit, Check, Plugin, Production
 
 class DatabasePlugin(Plugin):
     name = "database"
@@ -207,13 +233,18 @@ class DatabasePlugin(Plugin):
     async def shutdown(self, ctx):
         await self.pool.close()
 
-    def checks(self, ctx):
+    def checks(self, ctx):                     # runtime readiness → /ready
         return [Check(name="database", passed=self.pool.is_alive())]
 
+    def doctor(self, ctx):                     # static audit → prodkit doctor
+        return [Audit(name="Database pool",
+                      status="ok", detail="connection pool configured")]
+
 Production(app, plugins=[DatabasePlugin()])
 ```
 
-Your check now shows up in `/ready` automatically. Plugins can declare
+Your `checks()` result now shows up in `/ready` automatically, and your
+`doctor()` findings roll into the `prodkit doctor` score. Plugins can declare
 `requires = ("other-plugin",)` and the kernel activates them in dependency
 order — cycles and missing dependencies fail at boot.
 
@@ -221,6 +252,44 @@ Middleware registered by plugins carries an explicit integer priority, so
 the middleware onion is always correctly ordered no matter what order
 plugins load in (request-id outermost, compression innermost).
 
+## CLI — `prodkit doctor`
+
+Install the CLI extra and audit any `Production`-configured app:
+
+```bash
+pip install "prodkit[cli]"
+prodkit doctor --app main:app
+```
+
+```text
+              Production readiness
+  ┌───┬───────────────────────┬─────────────────────┬─────────────────────────┐
+  │ ✔ │ Security headers      │ nosniff, X-Frame ... │                         │
+  │ ✔ │ Structured logging    │ json @ INFO          │                         │
+  │ ✔ │ Error normalization   │ 500s opaque          │                         │
+  │ ⚠ │ Content-Security-Po.. │ not set              │ set a CSP to mitigate.. │
+  │ ⚠ │ Rate limiting         │ disabled             │ enable for public APIs  │
+  └───┴───────────────────────┴─────────────────────┴─────────────────────────┘
+  Production score: 88/100    2 warning(s)
+```
+
+Make it a CI quality gate — fail the build below a threshold:
+
+```bash
+prodkit doctor --app main:app --strict --min-score 90
+```
+
+Other commands:
+
+```bash
+prodkit inspect --app main:app   # resolved config, plugins, middleware order
+prodkit plugins --app main:app   # active plugins and the hooks each implements
+prodkit init --example           # scaffold prodkit.toml (+ starter main.py)
+```
+
+Every plugin contributes findings via its `doctor(ctx)` hook, so your own
+plugins score too.
+
 ## Plays Nice With Your App
 
 - **Same app object.** Routes, dependencies, and existing middleware keep
@@ -232,12 +301,13 @@ plugins load in (request-id outermost, compression innermost).
 
 ## Project Status
 
-**v0.1.0 — alpha.** Core kernel and seven built-in plugins, 60 tests, 98%
-coverage, strict mypy, CI across Python 3.10–3.13.
+**v0.2.1 — alpha.** Core kernel, eight built-in plugins (incl. rate-limiting),
+the `prodkit doctor` CLI with a production-readiness score, strict mypy, CI
+across Python 3.10–3.13.
 
-Roadmap: `prodkit doctor` CLI with a production-readiness score (v0.2),
-Prometheus metrics + Redis backends (v0.3), Dockerfile/nginx/CI generators
-(v0.4), public plugin SDK (v0.5), auth helpers (v0.6), stable API (v1.0).
+Roadmap: ✅ `prodkit doctor` CLI + rate limiting (v0.2), Prometheus metrics +
+Redis backends (v0.3), Dockerfile/nginx/CI generators (v0.4), public plugin SDK
+(v0.5), auth helpers (v0.6), stable API (v1.0).
 Full details in [docs/ARCHITECTURE.md](https://github.com/Pushkarpant/PRODKIT/blob/main/docs/ARCHITECTURE.md).
 
 ## Contributing

{prodkit-0.1.3 → prodkit-0.2.1}/README.md

@@ -14,14 +14,24 @@ Production(app)
 
 That's it. Your app now has security headers, structured JSON logging with
 request-ID correlation, RFC 9457 error responses, Kubernetes-ready health
-endpoints, and gzip compression — configured to current best practice,
-hardened for production, and pleasant in development.
+endpoints, gzip compression, and opt-in rate limiting — configured to current
+best practice, hardened for production, and pleasant in development. Then run
+[`prodkit doctor`](#cli--prodkit-doctor) to score how production-ready it is.
 
+[![PyPI](https://img.shields.io/pypi/v/prodkit.svg)](https://pypi.org/project/prodkit/)
+[![Python](https://img.shields.io/pypi/pyversions/prodkit.svg)](https://pypi.org/project/prodkit/)
 [![CI](https://github.com/Pushkarpant/PRODKIT/actions/workflows/ci.yml/badge.svg)](https://github.com/Pushkarpant/PRODKIT/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Pushkarpant/PRODKIT/blob/main/LICENSE)
 
 ---
 
+**Contents:** [Why](#why) · [Install](#installation) · [Quick Start](#quick-start) ·
+[What You Get](#what-you-get) · [Configuration](#configuration) ·
+[Plugins](#writing-a-plugin) · [CLI / doctor](#cli--prodkit-doctor) ·
+[Status & Roadmap](#project-status)
+
+---
+
 ## Why
 
 Every production FastAPI service re-implements the same ~500 lines of glue:
@@ -37,11 +47,13 @@ evolve, `pip install -U prodkit` updates every app you own.
 [**`pip install prodkit`**](https://pypi.org/project/prodkit/)
 
 ```bash
-pip install prodkit
+pip install prodkit           # the library
+pip install "prodkit[cli]"    # + the `prodkit doctor` CLI (typer + rich)
 ```
 
 Requires Python 3.10+ and FastAPI 0.110+. The base install depends only on
-FastAPI and Pydantic — nothing else.
+FastAPI and Pydantic — nothing else. Optional extras: `cli` (CLI),
+`brotli` (Brotli compression).
 
 ## Quick Start
 
@@ -69,7 +81,9 @@ x-content-type-options: nosniff
 x-frame-options: DENY
 strict-transport-security: max-age=63072000; includeSubDomains
 referrer-policy: strict-origin-when-cross-origin
-...
+permissions-policy: camera=(), microphone=(), geolocation=()
+x-xss-protection: 0
+content-type: application/json
 ```
 
 For local development, flip the profile — pretty console logs, debug error
@@ -90,7 +104,9 @@ Production(app, environment="development")
 | ❤️ **Health endpoints** | `/health`, `/live` (liveness) and `/ready` (readiness — aggregates checks from every plugin, 503 until all pass). Kubernetes-native. |
 | 🌐 **CORS** | Explicit origins only; the wildcard-with-credentials footgun is refused at boot. |
 | 📦 **Compression** | Gzip for responses over 500 bytes. |
-| 🔌 **Plugin system** | Every feature above is a plugin. Write your own with 6 optional hooks. |
+| 🚦 **Rate limiting** | Opt-in per-IP limiting (`100/minute`), `429 problem+json` with `Retry-After`. In-memory backend (Redis in v0.3). |
+| 🩺 **`prodkit doctor`** | CLI production-readiness audit with a 0–100 score. `--strict` gates CI. |
+| 🔌 **Plugin system** | Every feature above is a plugin. Write your own with optional hooks incl. `doctor()`. |
 
 ## Configuration
 
@@ -109,6 +125,7 @@ Production(
     cors={"origins": ["https://app.example.com"]},   # dict = configure & enable
     compression=False,                                # bool = toggle
     security={"trusted_hosts": ["api.example.com"]},
+    rate_limit={"default": "100/minute"},             # opt-in per-IP limiting
 )
 ```
 
@@ -132,6 +149,10 @@ level = "INFO"
 [cors]
 enabled = true
 origins = ["https://app.example.com"]
+
+[rate_limit]
+enabled = true
+default = "100/minute"
 ```
 
 ### Fail-fast, refuse-unsafe
@@ -153,7 +174,7 @@ not warned about:
 ## Writing a Plugin
 
 ```python
-from prodkit import Check, Plugin, Production
+from prodkit import Audit, Check, Plugin, Production
 
 class DatabasePlugin(Plugin):
     name = "database"
@@ -165,13 +186,18 @@ class DatabasePlugin(Plugin):
     async def shutdown(self, ctx):
         await self.pool.close()
 
-    def checks(self, ctx):
+    def checks(self, ctx):                     # runtime readiness → /ready
         return [Check(name="database", passed=self.pool.is_alive())]
 
+    def doctor(self, ctx):                     # static audit → prodkit doctor
+        return [Audit(name="Database pool",
+                      status="ok", detail="connection pool configured")]
+
 Production(app, plugins=[DatabasePlugin()])
 ```
 
-Your check now shows up in `/ready` automatically. Plugins can declare
+Your `checks()` result now shows up in `/ready` automatically, and your
+`doctor()` findings roll into the `prodkit doctor` score. Plugins can declare
 `requires = ("other-plugin",)` and the kernel activates them in dependency
 order — cycles and missing dependencies fail at boot.
 
@@ -179,6 +205,44 @@ Middleware registered by plugins carries an explicit integer priority, so
 the middleware onion is always correctly ordered no matter what order
 plugins load in (request-id outermost, compression innermost).
 
+## CLI — `prodkit doctor`
+
+Install the CLI extra and audit any `Production`-configured app:
+
+```bash
+pip install "prodkit[cli]"
+prodkit doctor --app main:app
+```
+
+```text
+              Production readiness
+  ┌───┬───────────────────────┬─────────────────────┬─────────────────────────┐
+  │ ✔ │ Security headers      │ nosniff, X-Frame ... │                         │
+  │ ✔ │ Structured logging    │ json @ INFO          │                         │
+  │ ✔ │ Error normalization   │ 500s opaque          │                         │
+  │ ⚠ │ Content-Security-Po.. │ not set              │ set a CSP to mitigate.. │
+  │ ⚠ │ Rate limiting         │ disabled             │ enable for public APIs  │
+  └───┴───────────────────────┴─────────────────────┴─────────────────────────┘
+  Production score: 88/100    2 warning(s)
+```
+
+Make it a CI quality gate — fail the build below a threshold:
+
+```bash
+prodkit doctor --app main:app --strict --min-score 90
+```
+
+Other commands:
+
+```bash
+prodkit inspect --app main:app   # resolved config, plugins, middleware order
+prodkit plugins --app main:app   # active plugins and the hooks each implements
+prodkit init --example           # scaffold prodkit.toml (+ starter main.py)
+```
+
+Every plugin contributes findings via its `doctor(ctx)` hook, so your own
+plugins score too.
+
 ## Plays Nice With Your App
 
 - **Same app object.** Routes, dependencies, and existing middleware keep
@@ -190,12 +254,13 @@ plugins load in (request-id outermost, compression innermost).
 
 ## Project Status
 
-**v0.1.0 — alpha.** Core kernel and seven built-in plugins, 60 tests, 98%
-coverage, strict mypy, CI across Python 3.10–3.13.
+**v0.2.1 — alpha.** Core kernel, eight built-in plugins (incl. rate-limiting),
+the `prodkit doctor` CLI with a production-readiness score, strict mypy, CI
+across Python 3.10–3.13.
 
-Roadmap: `prodkit doctor` CLI with a production-readiness score (v0.2),
-Prometheus metrics + Redis backends (v0.3), Dockerfile/nginx/CI generators
-(v0.4), public plugin SDK (v0.5), auth helpers (v0.6), stable API (v1.0).
+Roadmap: ✅ `prodkit doctor` CLI + rate limiting (v0.2), Prometheus metrics +
+Redis backends (v0.3), Dockerfile/nginx/CI generators (v0.4), public plugin SDK
+(v0.5), auth helpers (v0.6), stable API (v1.0).
 Full details in [docs/ARCHITECTURE.md](https://github.com/Pushkarpant/PRODKIT/blob/main/docs/ARCHITECTURE.md).
 
 ## Contributing

{prodkit-0.1.3 → prodkit-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "prodkit"
-version = "0.1.3"
+version = "0.2.1"
 description = "The production framework for FastAPI. One line. Production ready."
 readme = "README.md"
 license = "MIT"
@@ -43,6 +43,7 @@ dependencies = [
 
 [project.optional-dependencies]
 brotli = ["brotli-asgi>=1.4"]
+cli = ["typer>=0.12", "rich>=13"]
 dev = [
     "pytest>=8.0",
     "pytest-cov>=5.0",
@@ -51,8 +52,13 @@ dev = [
     "mypy>=1.11",
     "import-linter>=2.0",
     "tomli>=2.0",  # so mypy (python_version=3.10) can type-check the fallback import
+    "typer>=0.12",  # CLI is type-checked and tested in CI
+    "rich>=13",
 ]
 
+[project.scripts]
+prodkit = "prodkit.cli:run"
+
 [project.urls]
 Homepage = "https://github.com/Pushkarpant/PRODKIT"
 Documentation = "https://github.com/Pushkarpant/PRODKIT#readme"
@@ -88,12 +94,23 @@ select = [
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["S101", "S106"]  # asserts and test credentials are fine in tests
 
+[tool.ruff.lint.flake8-bugbear]
+# typer's API is built on function-call defaults (Option/Argument); this is the
+# documented pattern, not the B008 footgun.
+extend-immutable-calls = ["typer.Option", "typer.Argument"]
+
 [tool.mypy]
 python_version = "3.10"
 strict = true
 packages = ["prodkit"]
 mypy_path = "src"
 
+[[tool.mypy.overrides]]
+# typer's decorator-driven option defaults don't play well with strict mode.
+module = "prodkit.cli.app"
+disallow_untyped_decorators = false
+disallow_any_decorated = false
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "--cov=prodkit --cov-report=term-missing --cov-fail-under=90"

{prodkit-0.1.3 → prodkit-0.2.1}/src/prodkit/__init__.py

@@ -7,7 +7,7 @@ app = FastAPI()
 Production(app)
 """
 
-from prodkit.contracts.plugin import Check, Plugin
+from prodkit.contracts.plugin import Audit, Check, Plugin
 from prodkit.core.config import (
     CompressionConfig,
     CORSConfig,
@@ -15,6 +15,7 @@ from prodkit.core.config import (
     HealthConfig,
     LoggingConfig,
     ProdKitConfig,
+    RateLimitConfig,
     RequestIDConfig,
     SecurityConfig,
 )
@@ -33,9 +34,10 @@ from prodkit.plugins import builtin_plugins
 # root — the kernel itself never imports from prodkit.plugins.
 set_builtin_factory(builtin_plugins)
 
-__version__ = "0.1.3"
+__version__ = "0.2.1"
 
 __all__ = [
+    "Audit",
     "CORSConfig",
     "Check",
     "CompressionConfig",
@@ -50,6 +52,7 @@ __all__ = [
     "ProdKitConfigError",
     "ProdKitError",
     "Production",
+    "RateLimitConfig",
     "RequestIDConfig",
     "SecurityConfig",
     "ServiceNotFoundError",

prodkit-0.2.1/src/prodkit/cli/__init__.py

@@ -0,0 +1,28 @@
+"""ProdKit command-line interface.
+
+The heavy CLI (typer + rich) lives in :mod:`prodkit.cli.app`; this module keeps
+only a thin ``run()`` entry point so that a base install without the ``cli``
+extra fails with an actionable message instead of an import traceback.
+"""
+
+from __future__ import annotations
+
+import sys
+
+_CLI_DEPS = {"typer", "rich", "click"}
+
+
+def run() -> None:
+    """Console-script entry point (``prodkit``)."""
+    try:
+        from prodkit.cli.app import app
+    except ModuleNotFoundError as exc:  # pragma: no cover - exercised via packaging
+        if exc.name in _CLI_DEPS:
+            print(
+                "The prodkit CLI requires extra dependencies.\n"
+                "  Install them with:  pip install 'prodkit[cli]'",
+                file=sys.stderr,
+            )
+            raise SystemExit(1) from None
+        raise
+    app()