prodkit 0.1.3__tar.gz → 0.2.0__tar.gz

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

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

prodkit-0.2.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# 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.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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prodkit
-Version: 0.1.3
+Version: 0.2.0
 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
@@ -132,7 +137,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
 
@@ -221,6 +228,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 +277,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.0 — 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.0}/README.md

@@ -90,7 +90,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
 
@@ -179,6 +181,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 +230,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.0 — 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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "prodkit"
-version = "0.1.3"
+version = "0.2.0"
 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.0}/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.0"
 
 __all__ = [
+    "Audit",
     "CORSConfig",
     "Check",
     "CompressionConfig",
@@ -50,6 +52,7 @@ __all__ = [
     "ProdKitConfigError",
     "ProdKitError",
     "Production",
+    "RateLimitConfig",
     "RequestIDConfig",
     "SecurityConfig",
     "ServiceNotFoundError",

prodkit-0.2.0/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()

prodkit-0.2.0/src/prodkit/cli/app.py

@@ -0,0 +1,260 @@
+"""The typer + rich CLI application: doctor, inspect, plugins, init."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from prodkit import __version__
+from prodkit.cli.loader import AppLoadError, load_production
+from prodkit.contracts.plugin import Plugin
+from prodkit.core.doctor import DoctorReport, run_doctor
+
+app = typer.Typer(
+    name="prodkit",
+    help="Audit and inspect the production-readiness of a FastAPI app.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+_APP_OPTION = typer.Option(
+    None,
+    "--app",
+    "-a",
+    metavar="MODULE:ATTR",
+    help="Import path to your FastAPI app (default: autodetect main:app, app:app, ...).",
+)
+
+
+def _supports_unicode() -> bool:
+    """Whether the output stream can encode the status glyphs.
+
+    Windows terminals often default to cp1252, which can't encode ✔/⚠/✖; fall
+    back to ASCII markers there instead of crashing on a UnicodeEncodeError.
+    """
+    encoding = console.encoding or "utf-8"
+    try:
+        "✔⚠✖".encode(encoding)
+    except (UnicodeEncodeError, LookupError):
+        return False
+    return True
+
+
+_STATUS_ICON = (
+    {"ok": "[green]✔[/]", "warn": "[yellow]⚠[/]", "fail": "[red]✖[/]"}
+    if _supports_unicode()
+    else {"ok": "[green]OK[/]", "warn": "[yellow]![/]", "fail": "[red]X[/]"}
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"prodkit {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """ProdKit CLI."""
+
+
+def _load(app_spec: str | None):  # type: ignore[no-untyped-def]
+    try:
+        return load_production(app_spec)
+    except AppLoadError as exc:
+        err_console.print(f"[red]error:[/] {exc}")
+        raise typer.Exit(2) from None
+
+
+# --------------------------------------------------------------------------
+# doctor
+# --------------------------------------------------------------------------
+def _render_doctor(report: DoctorReport) -> None:
+    table = Table(title="Production readiness", show_lines=False, expand=False)
+    table.add_column("", justify="center", no_wrap=True)
+    table.add_column("Check", style="bold")
+    table.add_column("Detail")
+    table.add_column("Recommendation", style="dim")
+    for audit in report.audits:
+        table.add_row(
+            _STATUS_ICON[audit.status], audit.name, audit.detail, audit.recommendation or ""
+        )
+    console.print(table)
+
+    score = report.score
+    color = "green" if score >= 90 else "yellow" if score >= 70 else "red"
+    summary = f"[{color}]Production score: {score}/100[/]"
+    if report.failures:
+        summary += f"   [red]{len(report.failures)} failing[/]"
+    if report.warnings:
+        summary += f"   [yellow]{len(report.warnings)} warning(s)[/]"
+    console.print(Panel(summary, expand=False))
+
+
+@app.command()
+def doctor(
+    app_spec: str | None = _APP_OPTION,
+    strict: bool = typer.Option(
+        False, "--strict", help="Exit non-zero when the score is below --min-score (CI gate)."
+    ),
+    min_score: int = typer.Option(90, "--min-score", help="Passing threshold for --strict."),
+) -> None:
+    """Audit a FastAPI app and print a production-readiness score."""
+    report = run_doctor(_load(app_spec))
+    _render_doctor(report)
+    if strict and report.score < min_score:
+        err_console.print(
+            f"[red]doctor: score {report.score} is below the required {min_score}[/]"
+        )
+        raise typer.Exit(1)
+
+
+# --------------------------------------------------------------------------
+# inspect
+# --------------------------------------------------------------------------
+def _overridden_hooks(plugin: Plugin) -> list[str]:
+    hooks = (
+        "configure",
+        "register_middleware",
+        "register_routes",
+        "startup",
+        "shutdown",
+        "checks",
+        "doctor",
+    )
+    return [h for h in hooks if getattr(type(plugin), h) is not getattr(Plugin, h)]
+
+
+@app.command()
+def inspect(app_spec: str | None = _APP_OPTION) -> None:
+    """Show the resolved config, active plugins, and middleware order."""
+    prod = _load(app_spec)
+
+    console.print(Panel(f"[bold]environment:[/] {prod.config.environment}", expand=False))
+
+    console.print("[bold]Resolved configuration[/]")
+    console.print_json(json.dumps(prod.config.model_dump(mode="json")))
+
+    plugins_table = Table(title="Active plugins", expand=False)
+    plugins_table.add_column("Plugin", style="bold")
+    plugins_table.add_column("Requires")
+    plugins_table.add_column("Hooks", style="dim")
+    for plugin in prod.plugins:
+        plugins_table.add_row(
+            plugin.name,
+            ", ".join(plugin.requires) or "-",
+            ", ".join(_overridden_hooks(plugin)) or "-",
+        )
+    console.print(plugins_table)
+
+    mw_table = Table(title="Middleware order (outermost first)", expand=False)
+    mw_table.add_column("Priority", justify="right")
+    mw_table.add_column("Middleware", style="bold")
+    mw_table.add_column("From plugin", style="dim")
+    for spec in sorted(prod.context.middleware_specs(), key=lambda s: s.priority):
+        mw_table.add_row(str(spec.priority), spec.cls.__name__, spec.plugin or "-")
+    console.print(mw_table)
+
+
+# --------------------------------------------------------------------------
+# plugins
+# --------------------------------------------------------------------------
+@app.command()
+def plugins(app_spec: str | None = _APP_OPTION) -> None:
+    """List the active plugins and the hooks each one implements."""
+    prod = _load(app_spec)
+    table = Table(title="Active plugins", expand=False)
+    table.add_column("Plugin", style="bold")
+    table.add_column("Requires")
+    table.add_column("Hooks", style="dim")
+    for plugin in prod.plugins:
+        table.add_row(
+            plugin.name,
+            ", ".join(plugin.requires) or "-",
+            ", ".join(_overridden_hooks(plugin)) or "-",
+        )
+    console.print(table)
+    console.print(f"[green]{len(prod.plugins)}[/] plugin(s) active.")
+
+
+# --------------------------------------------------------------------------
+# init
+# --------------------------------------------------------------------------
+_TOML_TEMPLATE = """\
+# prodkit.toml — ProdKit configuration
+# Resolution order (highest wins): Python args > env vars > this file > profile defaults
+[prodkit]
+environment = "production"
+
+[logging]
+level = "INFO"
+format = "json"
+
+[security]
+hsts = true
+# trusted_hosts = ["api.example.com"]
+
+[cors]
+enabled = false
+# origins = ["https://app.example.com"]
+
+[rate_limit]
+enabled = false
+default = "100/minute"
+
+[compression]
+minimum_size = 500
+"""
+
+_EXAMPLE_TEMPLATE = """\
+from fastapi import FastAPI
+
+from prodkit import Production
+
+app = FastAPI()
+Production(app)
+
+
+@app.get("/")
+def root():
+    return {"message": "production ready"}
+"""
+
+
+@app.command()
+def init(
+    path: Path = typer.Option(Path("."), "--path", help="Directory to write files into."),
+    example: bool = typer.Option(False, "--example", help="Also scaffold a minimal main.py."),
+    force: bool = typer.Option(False, "--force", help="Overwrite existing files."),
+) -> None:
+    """Scaffold a prodkit.toml (and optionally a starter app)."""
+    path.mkdir(parents=True, exist_ok=True)
+    toml_path = path / "prodkit.toml"
+    if toml_path.exists() and not force:
+        err_console.print(f"[red]error:[/] {toml_path} already exists (use --force to overwrite)")
+        raise typer.Exit(2)
+    toml_path.write_text(_TOML_TEMPLATE, encoding="utf-8")
+    console.print(f"[green]created[/] {toml_path}")
+
+    if example:
+        main_path = path / "main.py"
+        if main_path.exists() and not force:
+            err_console.print(f"[yellow]skipped[/] {main_path} already exists")
+        else:
+            main_path.write_text(_EXAMPLE_TEMPLATE, encoding="utf-8")
+            console.print(f"[green]created[/] {main_path}")