create-caspian-app 0.0.1__tar.gz

create_caspian_app-0.0.1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

create_caspian_app-0.0.1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.0.1 — Alpha
+
+Initial release of the Caspian Python app generator.
+
+- Create apps with the `create-caspian-app` command and a bundled starter template.
+- Choose backend-only apps, Tailwind CSS, MCP, Prisma, and WebSocket support.
+- Generate environment files with fresh secrets for each project.
+- Update existing apps with `casp update project`, preserving managed user files
+  and configured exclusions.
+- Include starter app tests and development guides.

create_caspian_app-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Maintaining create-caspian-app
+
+Use Python 3.14 for package development and release checks.
+
+
+The app template comes from the Caspian starter repository
+(`create-caspian-app-python`) and is bundled inside the wheel, so creating an app
+works offline and each release always installs the same files.
+
+```bash
+uv run python scripts/sync_template.py          # copy git-tracked files from ../create-caspian-app-python
+uv run python scripts/sync_template.py --check  # fail if the bundled template is stale
+uv run pytest                                   # installer tests
+uv run ruff check src/create_caspian_app tests scripts
+uv build                                        # dist/*.whl + dist/*.tar.gz
+uvx twine check --strict dist/create_caspian_app-0.0.1-py3-none-any.whl dist/create_caspian_app-0.0.1.tar.gz
+```
+
+### Publish 0.0.1
+
+The version comes from `src/create_caspian_app/__init__.py`; the package metadata
+marks its development status as Alpha. The exact version is `0.0.1`, so package
+installers treat it as a normal release. A version such as `0.0.1a1` would instead
+be an alpha prerelease under Python's versioning rules.
+
+After the checks above pass, upload the two verified artifacts:
+
+```bash
+uv publish dist/create_caspian_app-0.0.1-py3-none-any.whl dist/create_caspian_app-0.0.1.tar.gz
+```
+
+Provide a PyPI API token through `UV_PUBLISH_TOKEN` in your shell or CI secret
+store. Never commit the token. PyPI does not allow replacing an uploaded release
+file; use a new version for subsequent changes.
+
+To rehearse on TestPyPI, use a separate TestPyPI token and upload endpoint:
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/ dist/create_caspian_app-0.0.1-py3-none-any.whl dist/create_caspian_app-0.0.1.tar.gz
+```
+
+Only files tracked by git in the source repo get copied. `.venv/`, `caspian.config.json`,
+`.env`, and bytecode are always left out. The source repo is also the framework's
+development workspace, so the sync also leaves out its demo pages, benchmarks,
+and the framework's own test suite (`DEVELOPMENT_ONLY` in
+`scripts/sync_template.py`), and applies small checked text edits (`EDITS`). When the
+source changes so that one of those edits no longer applies, the sync stops with an error,
+so development content never ships silently.
+
+`template_overrides/` holds the files this package owns, which are added to (or replace
+files in) the template:
+
+- `tests/conftest.py`: the app test fixtures (`client`, `rpc`, `csrf_headers`, `sign_in`,
+  `config`) and the `feature(...)` / `frontend` markers.
+- `tests/test_app.py`: starter tests for the app shell.
+- `tests/README.md`: the gate, formatting, and test commands.
+- `docs/caspian/testing.md`: the testing guide AI agents follow ("what to test for each
+  change", with a recipe for each surface).
+
+Edit those files here, not in the source repo, then run the sync. Every code block in the
+Recipes section of `testing.md` was run against a generated app. If you change a recipe,
+check it the same way.

create_caspian_app-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jefferson Abraham Omier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

create_caspian_app-0.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: create-caspian-app
+Version: 0.0.1
+Summary: Create Caspian apps: a high-performance Python web framework (FastAPI + PulsePoint).
+Project-URL: Homepage, https://caspian.tsnc.tech/
+Project-URL: Repository, https://github.com/TheSteelNinjaCode/create-caspian-app
+Author-email: Jefferson Abraham Omier <thesteelninjacode@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: boilerplate,caspian,create-app,fastapi,mcp,python,scaffold,tailwindcss
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# create-caspian-app
+
+Create a new [Caspian](https://caspian.tsnc.tech/) app, a high-performance Python web
+framework built on FastAPI and the PulsePoint browser runtime.
+
+The installer and application tooling use Python.
+
+Version **0.0.1** is the initial **alpha** release. APIs and generated project
+structure may change as Caspian develops.
+
+## Create an app
+
+With [uv](https://docs.astral.sh/uv/) (recommended, nothing to install first):
+
+```bash
+uvx create-caspian-app my-app
+```
+
+Or install the command once:
+
+```bash
+uv tool install create-caspian-app     # or: pipx install create-caspian-app
+create-caspian-app my-app
+```
+
+You'll be asked which features you want:
+
+```
+? What is your project named? (my-app)
+? Would you like to use Tailwind CSS? y/N
+? Would you like to use MCP (Model Context Protocol)? y/N
+? Would you like to use Prisma ORM (Caspian DB)? y/N
+? Would you like to use WebSocket? y/N
+```
+
+The installer writes the project, generates a `.env` with fresh secrets, runs
+`uv sync --group dev`, and builds the CSS. When Tailwind is on, it also downloads the
+pinned, checksum-verified Tailwind standalone compiler. Then:
+
+```bash
+cd my-app
+uv run python main.py
+```
+
+### Skip the questions
+
+Pass flags and `-y`. Only the flags you pass are turned on:
+
+```bash
+uvx create-caspian-app my-app --tailwindcss --mcp --prisma --websocket -y
+uvx create-caspian-app my-app --prisma --websocket -y
+```
+
+| Flag             | Feature                                                        |
+| ---------------- | -------------------------------------------------------------- |
+| `--tailwindcss`  | Tailwind CSS v4 via the standalone compiler                    |
+| `--mcp`          | MCP server mounted in FastAPI (`src/lib/mcp`)                  |
+| `--prisma`       | Caspian DB: `prisma/schema.prisma` + generated Python client   |
+| `--websocket`    | Named sockets (`src/lib/websocket`)                            |
+| `--skip-install` | Write files only; skip `uv sync` and the CSS build             |
+| `-y`             | No prompts                                                     |
+
+## Update an existing app
+
+Run this from the project folder:
+
+```bash
+uvx --from create-caspian-app casp update project          # latest
+uvx --from create-caspian-app casp update project 0.0.1    # a specific version
+```
+
+Running `create-caspian-app <name>` inside a folder that has a `caspian.config.json`
+does the same. The update refreshes the Caspian template files and asks about any
+features that aren't enabled yet. It removes the files of features you turn off and
+re-pins the managed dependencies.
+
+An update never overwrites:
+
+- `.env`
+- `pyproject.toml` (only the managed requirements are re-pinned, with `uv add` / `uv remove`)
+- `uv.lock`
+- `src/app/globals.css` (only the Tailwind directives are added or removed)
+- `prisma/`
+- any path listed in `caspian.config.json` → `"excludeFiles"`
+
+Everything else that comes from the template, such as `src/app/index.py`, gets
+overwritten. Add the files you've customized to `excludeFiles` first.
+
+## Requirements
+
+- Python 3.14+ for the installer and generated apps. uv can download Python 3.14
+  if it is missing.
+- [uv](https://docs.astral.sh/uv/). If it's missing, the installer tries
+  `python -m pip install uv`.

create_caspian_app-0.0.1/README.md

@@ -0,0 +1,94 @@
+# create-caspian-app
+
+Create a new [Caspian](https://caspian.tsnc.tech/) app, a high-performance Python web
+framework built on FastAPI and the PulsePoint browser runtime.
+
+The installer and application tooling use Python.
+
+Version **0.0.1** is the initial **alpha** release. APIs and generated project
+structure may change as Caspian develops.
+
+## Create an app
+
+With [uv](https://docs.astral.sh/uv/) (recommended, nothing to install first):
+
+```bash
+uvx create-caspian-app my-app
+```
+
+Or install the command once:
+
+```bash
+uv tool install create-caspian-app     # or: pipx install create-caspian-app
+create-caspian-app my-app
+```
+
+You'll be asked which features you want:
+
+```
+? What is your project named? (my-app)
+? Would you like to use Tailwind CSS? y/N
+? Would you like to use MCP (Model Context Protocol)? y/N
+? Would you like to use Prisma ORM (Caspian DB)? y/N
+? Would you like to use WebSocket? y/N
+```
+
+The installer writes the project, generates a `.env` with fresh secrets, runs
+`uv sync --group dev`, and builds the CSS. When Tailwind is on, it also downloads the
+pinned, checksum-verified Tailwind standalone compiler. Then:
+
+```bash
+cd my-app
+uv run python main.py
+```
+
+### Skip the questions
+
+Pass flags and `-y`. Only the flags you pass are turned on:
+
+```bash
+uvx create-caspian-app my-app --tailwindcss --mcp --prisma --websocket -y
+uvx create-caspian-app my-app --prisma --websocket -y
+```
+
+| Flag             | Feature                                                        |
+| ---------------- | -------------------------------------------------------------- |
+| `--tailwindcss`  | Tailwind CSS v4 via the standalone compiler                    |
+| `--mcp`          | MCP server mounted in FastAPI (`src/lib/mcp`)                  |
+| `--prisma`       | Caspian DB: `prisma/schema.prisma` + generated Python client   |
+| `--websocket`    | Named sockets (`src/lib/websocket`)                            |
+| `--skip-install` | Write files only; skip `uv sync` and the CSS build             |
+| `-y`             | No prompts                                                     |
+
+## Update an existing app
+
+Run this from the project folder:
+
+```bash
+uvx --from create-caspian-app casp update project          # latest
+uvx --from create-caspian-app casp update project 0.0.1    # a specific version
+```
+
+Running `create-caspian-app <name>` inside a folder that has a `caspian.config.json`
+does the same. The update refreshes the Caspian template files and asks about any
+features that aren't enabled yet. It removes the files of features you turn off and
+re-pins the managed dependencies.
+
+An update never overwrites:
+
+- `.env`
+- `pyproject.toml` (only the managed requirements are re-pinned, with `uv add` / `uv remove`)
+- `uv.lock`
+- `src/app/globals.css` (only the Tailwind directives are added or removed)
+- `prisma/`
+- any path listed in `caspian.config.json` → `"excludeFiles"`
+
+Everything else that comes from the template, such as `src/app/index.py`, gets
+overwritten. Add the files you've customized to `excludeFiles` first.
+
+## Requirements
+
+- Python 3.14+ for the installer and generated apps. uv can download Python 3.14
+  if it is missing.
+- [uv](https://docs.astral.sh/uv/). If it's missing, the installer tries
+  `python -m pip install uv`.

create_caspian_app-0.0.1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "create-caspian-app"
+dynamic = ["version"]
+description = "Create Caspian apps: a high-performance Python web framework (FastAPI + PulsePoint)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+authors = [{ name = "Jefferson Abraham Omier", email = "thesteelninjacode@gmail.com" }]
+keywords = ["caspian", "python", "fastapi", "scaffold", "create-app", "boilerplate", "tailwindcss", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Code Generators",
+]
+# Deliberately empty: the installer uses only the standard library and uv.
+dependencies = []
+
+[project.urls]
+Homepage = "https://caspian.tsnc.tech/"
+Repository = "https://github.com/TheSteelNinjaCode/create-caspian-app"
+
+[project.scripts]
+create-caspian-app = "create_caspian_app.cli:main"
+casp = "create_caspian_app.casp:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[tool.hatch.version]
+path = "src/create_caspian_app/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/create_caspian_app"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "scripts/", "template_overrides/", "tests/", "README.md", "CHANGELOG.md", "CONTRIBUTING.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+extend-exclude = ["src/create_caspian_app/template"]

create_caspian_app-0.0.1/scripts/sync_template.py

@@ -0,0 +1,272 @@
+"""Copy the Caspian Python starter project into the package template.
+
+The source of truth is the Caspian app repository (by default the sibling
+folder ``../create-caspian-app-python``). Only files tracked by git in that
+repository are copied, so its own ``.gitignore`` decides what is private
+(``.env``, ``.tools/``, ``.casp/``, caches).
+
+That repository is also the framework's development workspace. Its demo pages,
+benchmarks and framework test suite are not part of a new
+app, so they are left out here, and ``template_overrides/`` supplies what a new
+app gets instead (the app test scaffold and the agent testing guide). Every
+text edit below must match the source exactly; when the source changes so an
+edit no longer applies, the sync fails instead of silently shipping
+development content.
+
+Usage:
+    uv run python scripts/sync_template.py
+    uv run python scripts/sync_template.py --source C:/path/to/caspian-app
+    uv run python scripts/sync_template.py --check   # fail if template is stale
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+TEMPLATE = ROOT / "src" / "create_caspian_app" / "template"
+OVERRIDES = ROOT / "template_overrides"
+DEFAULT_SOURCE = ROOT.parent / "create-caspian-app-python"
+
+# Tracked in the source repo but never shipped to a new app.
+EXCLUDED_PREFIXES = (
+    ".venv/",  # the installed runtime belongs to uv, not the template
+    ".git/",
+)
+EXCLUDED_FILES = {
+    "caspian.config.json",  # generated per project by the installer
+    ".env",  # generated per project (fresh secrets)
+}
+EXCLUDED_SUFFIXES = (".pyc", ".pyo")
+
+# Development-only content of the source workspace.
+DEVELOPMENT_ONLY = (
+    "docs/prepared-pages-example.md",
+    "settings/benchmark_pages.py",
+    "src/app/performance/",
+    "src/components/performance/",
+    "src/lib/performance_demo.py",
+    "src/app/form/",
+    "src/components/form/",
+    # The framework's own test suite. New apps get the scaffold from
+    # template_overrides/tests/ and the guide in docs/caspian/testing.md.
+    "tests/",
+)
+
+# Exact text edits: (old, new) pairs applied to one file.
+EDITS = {
+    "src/app/index.py": (
+        ("from src.components.performance.ExampleLinks import ExampleLinks\n", ""),
+        ("  <x-example-links />\n\n", ""),
+    ),
+    "AGENTS.md": (
+        (
+            (
+                ' Read `docs/caspian/websockets.md` "Named Sockets"; the handshake has no'
+                " dedicated tests yet (`tests/test_request_security.py` covers only the"
+                " per-connection message rate)."
+            ),
+            (
+                ' Read `docs/caspian/websockets.md` "Named Sockets"; test sockets with'
+                ' `client.websocket_connect(...)` as shown in `docs/caspian/testing.md` "Sockets".'
+            ),
+        ),
+        (
+            (
+                "  - Coverage lives in `tests/test_layout.py` (brace escaping), "
+                "`tests/test_runtime_security.py` (environment + CSP + path safety), "
+                "`tests/test_request_security.py` (page rate limit, missing-asset 404s, "
+                "per-connection socket message rate), `tests/test_python_server.py` "
+                "(development cookie scoping), `tests/test_page_policy.py` (prepared-page "
+                "policy selection), `tests/test_upload_serving.py`, `tests/test_rpc.py`, and "
+                "`tests/test_auth.py`. The `/mcp` token gate (`MCPAuthMiddleware`) and the "
+                "named-socket handshake (origin check, `require_auth`/`allowed_roles`, "
+                "size/idle limits) have no dedicated tests yet — verify them by reading "
+                "`main.py` and `src/lib/websocket/sockets.py`."
+            ),
+            (
+                "  - The runtime's own security coverage ships with Caspian. Test this app's"
+                " security-relevant behavior (route privacy, RBAC, `@rpc()` auth and roles, CSRF on"
+                " `route.py`, socket auth) with the `client`, `rpc`, `csrf_headers`, and `sign_in`"
+                " fixtures; recipes are in `docs/caspian/testing.md`."
+            ),
+        ),
+        (
+            (
+                "- Testing/type checking/linting: read `tests/README.md`, `settings/test.py`, and"
+                " `docs/caspian/testing.md`. Run `uv run python settings/test.py` (fix: `uv run"
+                " python settings/fix.py`). The four checks are native ty, Ruff, templates, and"
+                " pytest. A green gate does not prove browser health."
+            ),
+            (
+                "- Testing: **every change to app behavior ships with a test in the same edit batch.**"
+                " When you add or change a page, layout, component, `@rpc()` action, `route.py`"
+                " endpoint, socket, job, auth/RBAC rule, validation rule, or `src/lib/**` function,"
+                " read `docs/caspian/testing.md` first: it maps each kind of change to the test it"
+                " needs, with working examples built on the fixtures in `tests/conftest.py`"
+                " (`client`, `rpc`, `csrf_headers`, `sign_in`, `config`). Put tests in"
+                " `tests/test_<feature>.py`, test routes over HTTP (never import"
+                " `src/app/**` modules), and never weaken a test to pass the gate. Then run"
+                " `uv run python settings/test.py` (ty, Ruff, templates, pytest; fix: `uv run"
+                " python settings/fix.py`) and fix every failure. A green gate does not prove"
+                " browser health."
+            ),
+        ),
+    ),
+    ".github/copilot-instructions.md": (
+        (
+            (
+                "- App Python edits require uv run python settings/test.py: ty, Ruff, templates,"
+                " pytest. Fix all errors."
+            ),
+            (
+                "- App Python edits require uv run python settings/test.py: ty, Ruff, templates,"
+                " pytest. Fix all errors. Every new or changed page, component, @rpc() action,"
+                " route.py endpoint, socket, job, or auth rule ships with a test in"
+                " tests/test_<feature>.py; follow docs/caspian/testing.md."
+            ),
+        ),
+        (
+            "pytest exercises app and installed runtime contracts.",
+            (
+                "pytest runs the app's tests in tests/ (fixtures in tests/conftest.py, recipes in"
+                " docs/caspian/testing.md)."
+            ),
+        ),
+    ),
+    ".github/instructions/database-generation.instructions.md": (
+        (
+            (
+                "Testing: uv run python settings/test.py. Optional PostgreSQL verification:\n"
+                "set CASPIAN_DB_TEST_POSTGRES=1 and run uv run python -m pytest\n"
+                "tests/test_prisma_postgresql.py -q, then unset the variable. That test reads .env\n"
+                "and uses verified session-local temporary tables, never application tables."
+            ),
+            (
+                "Testing: keep queries in src/lib/** functions that routes call through their\n"
+                "module, fake them in route tests, and test the queries themselves against a\n"
+                'dedicated test database; see docs/caspian/testing.md "Database". Then run\n'
+                "uv run python settings/test.py."
+            ),
+        ),
+    ),
+}
+
+# Dotfiles are renamed inside the wheel so packaging tools never treat them as
+# their own ignore rules. The installer renames them back.
+RENAMED = {".gitignore": "_gitignore"}
+
+
+def tracked_files(source: Path) -> list[str]:
+    try:
+        output = subprocess.run(
+            ["git", "ls-files", "-z"],
+            cwd=source,
+            check=True,
+            capture_output=True,
+        ).stdout
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise SystemExit(f"{source} must be a git repository: {exc}") from exc
+    return [name for name in output.decode("utf-8").split("\0") if name]
+
+
+def shipped(name: str) -> bool:
+    if name in EXCLUDED_FILES or name.endswith(EXCLUDED_SUFFIXES):
+        return False
+    if "__pycache__/" in name:
+        return False
+    if any(name == p or (p.endswith("/") and name.startswith(p)) for p in DEVELOPMENT_ONLY):
+        return False
+    return not name.startswith(EXCLUDED_PREFIXES)
+
+
+def apply_edits(name: str, text: str) -> str:
+    for old, new in EDITS.get(name, ()):
+        if old not in text:
+            raise SystemExit(f"{name}: expected text not found (source changed?): {old!r}")
+        text = text.replace(old, new)
+    return text
+
+
+def content(name: str, path: Path) -> bytes:
+    if name not in EDITS:
+        return path.read_bytes()
+    raw = path.read_bytes().decode("utf-8")
+    crlf = "\r\n" in raw
+    text = apply_edits(name, raw.replace("\r\n", "\n"))  # edits are written with \n
+    return (text.replace("\n", "\r\n") if crlf else text).encode("utf-8")
+
+
+def destination(name: str) -> str:
+    return RENAMED.get(name, name)
+
+
+def plan(source: Path) -> dict[str, bytes]:
+    files = {}
+    for name in tracked_files(source):
+        path = source / name
+        if shipped(name) and path.is_file():
+            files[destination(name)] = content(name, path)
+    # Files owned by this package: added, or replacing the source's version.
+    for path in sorted(OVERRIDES.rglob("*")):
+        if path.is_file() and "__pycache__" not in path.parts:
+            files[destination(path.relative_to(OVERRIDES).as_posix())] = path.read_bytes()
+    return files
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--source", type=Path, default=DEFAULT_SOURCE)
+    parser.add_argument("--check", action="store_true", help="report drift, write nothing")
+    args = parser.parse_args()
+
+    source = args.source.resolve()
+    if not (source / "main.py").is_file():
+        raise SystemExit(f"Not a Caspian app (no main.py): {source}")
+
+    files = plan(source)
+    existing = (
+        {p.relative_to(TEMPLATE).as_posix() for p in TEMPLATE.rglob("*") if p.is_file()}
+        if TEMPLATE.exists()
+        else set()
+    )
+    stale = sorted(existing - files.keys())
+    changed = sorted(
+        name
+        for name, data in files.items()
+        if not (TEMPLATE / name).is_file() or (TEMPLATE / name).read_bytes() != data
+    )
+
+    if args.check:
+        for name in changed:
+            print(f"changed: {name}")
+        for name in stale:
+            print(f"removed: {name}")
+        if changed or stale:
+            print("Template is out of date. Run: uv run python scripts/sync_template.py")
+            return 1
+        print(f"Template is current ({len(files)} files from {source}).")
+        return 0
+
+    for name in stale:
+        (TEMPLATE / name).unlink()
+    for name in changed:
+        target = TEMPLATE / name
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(files[name])
+    # Drop directories emptied by removals.
+    for directory in sorted(TEMPLATE.rglob("*"), reverse=True):
+        if directory.is_dir() and not any(directory.iterdir()):
+            directory.rmdir()
+
+    print(
+        f"Synced {len(files)} files from {source} ({len(changed)} updated, {len(stale)} removed)."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

create_caspian_app-0.0.1/src/create_caspian_app/__init__.py

@@ -0,0 +1,5 @@
+"""Scaffold Caspian Python applications."""
+
+# One version for both the PyPI package and the Caspian framework: the
+# installer writes it to every project's caspian.config.json.
+__version__ = "0.0.1"

create_caspian_app-0.0.1/src/create_caspian_app/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())