create-caspian-app 0.0.1__py3-none-any.whl

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/__main__.py

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

create_caspian_app/casp.py

@@ -0,0 +1,74 @@
+"""casp: project maintenance commands (``casp update project [version]``)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from . import ui
+from .cli import FLAG_NAMES
+from .installer import InstallError, find_uv
+
+USAGE = """Usage:
+  casp update project            update to the latest create-caspian-app
+  casp update project 1.2.3      update to a specific version
+  casp update project -y         update without prompts
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="casp", usage=USAGE)
+    parser.add_argument("command", nargs="*")
+    parser.add_argument("--tag", "--version", dest="version")
+    parser.add_argument("-y", "--yes", action="store_true")
+    args = parser.parse_args(argv)
+
+    words = args.command
+    if words[:2] != ["update", "project"] or len(words) > 3:
+        print(USAGE)
+        return 0 if not words else 1
+
+    version = args.version or (words[2] if len(words) == 3 else "latest")
+    version = version.lstrip("@v") if version != "latest" else version
+
+    config_path = Path.cwd() / "caspian.config.json"
+    if not config_path.is_file():
+        ui.error("caspian.config.json was not found in the current directory.")
+        return 1
+    config = json.loads(config_path.read_text(encoding="utf-8"))
+
+    if not args.yes and not ui_confirm(version):
+        ui.error("Operation cancelled by the user.")
+        return 1
+
+    try:
+        uv = find_uv()
+    except InstallError as exc:
+        ui.error(str(exc))
+        return 1
+
+    command = uv + ["tool", "run", f"create-caspian-app@{version}", config["projectName"]]
+    command += [flag for feature, flag in FLAG_NAMES.items() if config.get(feature)]
+    if args.yes:
+        command.append("-y")
+
+    ui.info(f"\nUpdating with create-caspian-app@{version}\n")
+    return subprocess.run(command, check=False).returncode
+
+
+def ui_confirm(version: str) -> bool:
+    try:
+        return ui.ask_bool(
+            f"This updates the project with {ui.blue(f'create-caspian-app@{version}')} "
+            "and overwrites the default template files. Proceed?",
+            default=False,
+        )
+    except ui.Cancelled:
+        return False
+
+
+if __name__ == "__main__":
+    sys.exit(main())

create_caspian_app/cli.py

@@ -0,0 +1,192 @@
+"""create-caspian-app: scaffold or update a Caspian Python application."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__, ui
+from .features import FEATURES, LABELS, Answers
+from .installer import InstallError, build_css, find_uv, sync, update_dependencies
+from .scaffold import UpdateContext, remove_disabled, sync_stylesheet, write_project
+
+FLAG_NAMES = {
+    "tailwindcss": "--tailwindcss",
+    "mcp": "--mcp",
+    "prisma": "--prisma",
+    "websocket": "--websocket",
+}
+
+
+def parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="create-caspian-app",
+        description="Create a new Caspian app, or update the one in the current folder.",
+        epilog=(
+            "Examples:\n"
+            "  uvx create-caspian-app my-app\n"
+            "  uvx create-caspian-app my-app --tailwindcss --mcp -y\n"
+            "  uvx create-caspian-app my-app --prisma --websocket -y"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("project_name", nargs="?", help="folder to create (or update)")
+    for feature, flag in FLAG_NAMES.items():
+        parser.add_argument(
+            flag, dest=feature, action="store_true", help=f"enable {LABELS[feature]}"
+        )
+    parser.add_argument(
+        "-y", "--yes", action="store_true", help="no prompts: only the flags you pass are enabled"
+    )
+    parser.add_argument(
+        "--skip-install",
+        action="store_true",
+        help="only write files; skip uv sync and the CSS build",
+    )
+    parser.add_argument("--version", action="version", version=f"create-caspian-app {__version__}")
+    return parser.parse_args(argv)
+
+
+def ask_features(answers: Answers, preset: set[str], interactive: bool) -> None:
+    for feature in FEATURES:
+        if feature in preset:
+            continue
+        if interactive:
+            setattr(
+                answers, feature, ui.ask_bool(f"Would you like to use {ui.blue(LABELS[feature])}?")
+            )
+
+
+def find_existing_project(name: str | None) -> Path | None:
+    cwd = Path.cwd()
+    if name and (cwd / "caspian.config.json").is_file():
+        return cwd
+    if name and (cwd / name / "caspian.config.json").is_file():
+        return cwd / name
+    return None
+
+
+def create(args: argparse.Namespace) -> Path:
+    interactive = not args.yes
+    preset = {f for f in FEATURES if getattr(args, f)}
+    answers = Answers(**{f: getattr(args, f) for f in FEATURES})
+
+    name = args.project_name
+    if not name:
+        name = ui.ask_text("What is your project named?", "my-app") if interactive else "my-app"
+    name = name.strip().replace(" ", "-")
+
+    root = (Path.cwd() / name).resolve()
+    answers.project_name = root.name
+    if root.exists() and any(root.iterdir()):
+        raise SystemExit(
+            ui.red(f"The folder {root} already exists and is not empty. Pick another name.")
+        )
+
+    ask_features(answers, preset, interactive)
+
+    print()
+    ui.info(f"Creating a new Caspian app in {ui.green(str(root))}")
+    ui.note("Features: " + (", ".join(answers.enabled()) or "none"))
+    root.mkdir(parents=True, exist_ok=True)
+    write_project(root, answers)
+    ui.success("Project files written.")
+
+    if not args.skip_install:
+        uv = find_uv()
+        sync(root, uv)
+        build_css(root, answers, uv)
+    return root
+
+
+def update(args: argparse.Namespace, root: Path) -> Path:
+    interactive = not args.yes
+    config = json.loads((root / "caspian.config.json").read_text(encoding="utf-8"))
+
+    answers = Answers(project_name=config.get("projectName") or root.name)
+    for feature in FEATURES:
+        setattr(answers, feature, bool(config.get(feature)) or getattr(args, feature))
+    preset = {f for f in FEATURES if getattr(answers, f)}
+
+    ui.info(f"Updating the Caspian app in {ui.green(str(root))}")
+    ask_features(answers, preset, interactive)
+
+    if interactive:
+        ui.warn(
+            "\nThis refreshes the Caspian template files (main.py, settings/, src/, docs).\n"
+            "Your .env, pyproject.toml, uv.lock, src/app/globals.css, and tests/ are kept.\n"
+            'List any other file you customized in caspian.config.json "excludeFiles" too.'
+        )
+        if not ui.ask_bool("Continue?", default=False):
+            raise ui.Cancelled
+
+    context = UpdateContext(
+        exclude_files=list(config.get("excludeFiles") or []),
+        component_scan_dirs=list(config.get("componentScanDirs") or ["src"]),
+    )
+    write_project(root, answers, context)
+    for rel in remove_disabled(root, answers, context):
+        ui.note(f"Removed {rel} (feature disabled)")
+    sync_stylesheet(root, answers.tailwindcss)
+    ui.success("Project files updated.")
+
+    if not args.skip_install:
+        uv = find_uv()
+        update_dependencies(root, answers, uv)
+        sync(root, uv)
+        build_css(root, answers, uv)
+    return root
+
+
+def next_steps(root: Path, answers_config: dict, installed: bool, updated: bool) -> None:
+    cd = Path.cwd()
+    try:
+        shown = root.relative_to(cd)
+    except ValueError:
+        shown = root
+    print()
+    verb = "updated" if updated else "ready"
+    ui.success(f"Success! Your Caspian app is {verb} in {root.as_posix()}")
+    print("\nNext steps:\n")
+    if str(shown) != ".":
+        print(f"  cd {shown}")
+    if not installed:
+        print("  uv sync --group dev")
+        if answers_config.get("tailwindcss"):
+            print("  uv run python settings/build.py setup")
+        print("  uv run python settings/build.py css")
+    print("  uv run python main.py")
+    if answers_config.get("prisma"):
+        print("\n  Database: set DATABASE_URL in .env, then\n  uv run caspian-db migrate deploy")
+    print(
+        "\n  Tests: uv run python settings/test.py"
+        "\n  Read README.md and AGENTS.md for the full workflow.\n"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    # Keep our messages ordered with the output of the uv child processes.
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(line_buffering=True)
+    print(ui.bold(f"create-caspian-app {__version__}"))
+    try:
+        existing = find_existing_project(args.project_name)
+        root = update(args, existing) if existing else create(args)
+    except ui.Cancelled:
+        ui.error("Operation cancelled by the user.")
+        return 1
+    except InstallError as exc:
+        ui.error(f"\n{exc}")
+        ui.warn("The project files were written; fix the problem above and rerun the command.")
+        return 1
+
+    config = json.loads((root / "caspian.config.json").read_text(encoding="utf-8"))
+    next_steps(root, config, installed=not args.skip_install, updated=existing is not None)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

create_caspian_app/envfile.py

@@ -0,0 +1,185 @@
+"""Generate the .env for a new Caspian app, with fresh secrets.
+
+The file lists only what a project must or commonly sets: credentials,
+per-project values, security switches, and deployment origins. Every other
+variable keeps the default of the code that reads it and is documented in
+docs/caspian/environment.md, so it is left out here.
+"""
+
+from __future__ import annotations
+
+import base64
+import secrets
+
+from .features import Answers
+
+RULE = "# " + "=" * 77
+
+
+def _section(title: str, body: str) -> str:
+    lines = [line if line.startswith("#") else f"# {line}" for line in title.split("\n")]
+    return f"{RULE}\n" + "\n".join(lines) + f"\n{RULE}\n\n{body.strip()}"
+
+
+def build_env(answers: Answers) -> str:
+    auth_secret = base64.b64encode(secrets.token_bytes(33)).decode()
+    cookie_name = secrets.token_hex(8)
+    mcp_token = secrets.token_hex(32)
+
+    sections: list[str] = []
+
+    if answers.prisma:
+        sections.append(
+            _section(
+                "DATABASE\n# Read by prisma/schema.prisma and src/lib/prisma/db.py.",
+                """
+# Connection string. A credential, which is why .env is git-ignored. The provider
+# in prisma/schema.prisma must match the URL scheme (postgresql://, mysql://, or
+# file: for SQLite). Format reference: https://pris.ly/d/connection-strings
+DATABASE_URL="postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public"
+""",
+            )
+        )
+
+    sections.append(
+        _section(
+            "APPLICATION RUNTIME\n"
+            "# Read by casp/runtime_security.py is_production_environment() and casp/app_time.py.",
+            """
+# Resolved FAIL-CLOSED: only dev, development, local, staging, test or testing
+# enable the development relaxations. Unset or misspelled counts as production,
+# which turns on Secure cookies, HSTS, generic errors, a mandatory AUTH_SECRET,
+# and the production checks of the MCP and WebSocket sections below.
+APP_ENV="development"
+
+# IANA timezone deciding which calendar day an instant belongs to. Timestamps
+# stay stored in UTC; session expiry and cache TTLs are unaffected. Empty = UTC.
+APP_TIMEZONE="UTC"
+""",
+        )
+    )
+    sections.append(
+        _section(
+            "PUBLIC URL AND ORIGINS\n# Read by casp/rpc.py origin checks and the main.py CORS layer.",
+            """
+# Canonical public origin. Leave empty when the browser URL and the app URL
+# match; set it behind a reverse proxy, load balancer or TLS terminator.
+APP_BASE_URL=""
+
+# Extra browser origins allowed to call RPC. Comma-separated, no spaces.
+CORS_ALLOWED_ORIGINS=""
+
+# Trust Forwarded/X-Forwarded-* headers for the RPC origin check and the rate
+# limiter address. Enable ONLY when a proxy strips client-supplied copies.
+TRUST_FORWARDED_HEADERS="false"
+""",
+        )
+    )
+    sections.append(
+        _section(
+            "AUTHENTICATION AND SESSIONS\n# Read by casp/auth.py and main.py SessionMiddleware. "
+            "Route privacy and RBAC\n# live in src/lib/auth/auth_config.py, not here.",
+            f"""
+# Session signing secret, unique per app and environment. Production refuses to
+# start when it is missing or a placeholder ("change-me"/"changeme").
+AUTH_SECRET="{auth_secret}"
+
+# Unique per project: apps sharing a parent domain and cookie name overwrite
+# each other's sessions.
+AUTH_COOKIE_NAME="{cookie_name}"
+
+# Session lifetime in hours. Default 7.
+SESSION_LIFETIME_HOURS="7"
+""",
+        )
+    )
+    sections.append(
+        _section(
+            "OAUTH PROVIDERS\n# AuthMiddleware already serves /api/auth/signin/{google,github} and\n"
+            "# /api/auth/callback/{google,github}. A provider with no client id is skipped\n"
+            "# silently (the button appears dead). Empty means disabled.",
+            """
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+# Must match the Google Cloud Console redirect URI exactly; required for Google.
+GOOGLE_REDIRECT_URI=
+
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+# Must match a URI registered on the GitHub App. Empty derives it from
+# APP_BASE_URL as "<APP_BASE_URL>/api/auth/callback/github".
+GITHUB_REDIRECT_URI=
+""",
+        )
+    )
+    sections.append(
+        _section(
+            "REQUEST SECURITY\n# Read by main.py BodySizeLimitMiddleware and casp/runtime_security.py.",
+            """
+# Max whole request body in MB (file + fields + encoding). Default 16.
+MAX_CONTENT_LENGTH_MB="16"
+
+# Replaces the built-in Content-Security-Policy wholesale; empty keeps the
+# default. A replacement MUST keep 'unsafe-eval' and 'unsafe-inline' in
+# script-src (PulsePoint compiles templates with new Function()). An override
+# also replaces the development-only loopback connect-src entries.
+CONTENT_SECURITY_POLICY=
+""",
+        )
+    )
+
+    if answers.websocket:
+        sections.append(
+            _section(
+                "WEBSOCKETS\n# Read by src/lib/websocket/sockets.py (named-socket endpoint).",
+                """
+# Browser origins allowed to open a socket. Falls back to CORS_ALLOWED_ORIGINS,
+# then APP_BASE_URL. REQUIRED IN PRODUCTION: the same-origin fallback trusts the
+# client Host header and is development-only. Comma-separated, no spaces.
+WEBSOCKET_ALLOWED_ORIGINS=
+""",
+            )
+        )
+
+    # Always written, even when MCP is off, so enabling mcp in
+    # caspian.config.json later finds a token already in place.
+    sections.append(
+        _section(
+            "MCP ENDPOINT\n# Read by main.py MCPAuthMiddleware. /mcp is mounted outside the routing tree,\n"
+            "# so AuthMiddleware does not protect it. Required in production. Inert until\n"
+            "# caspian.config.json has mcp: true.",
+            f"""
+MCP_AUTH_TOKEN="{mcp_token}"
+""",
+        )
+    )
+    sections.append(
+        _section(
+            "DATA CACHE AND JOBS\n# Read by casp/cache.py and casp/jobs.py.",
+            """
+# Data cache store: memory, file, or redis (redis needs `uv add redis`).
+CACHE_STORE="memory"
+# Redis connection for CACHE_STORE=redis, e.g. redis://localhost:6379/0.
+CACHE_REDIS_URL=
+
+# Job queue: memory (lost on restart) or sqlite (survives restarts).
+JOBS_DRIVER="memory"
+""",
+        )
+    )
+    sections.append(
+        _section(
+            "SERVER PROCESS\n# Read by main.py __main__.",
+            """
+# Uvicorn worker processes. Keep 1 unless the app is built for multi-process
+# coordination; workers duplicate memory, pools and in-process state.
+UVICORN_WORKERS="1"
+
+# Every other setting (rate limits, websocket limits, logging, maintenance,
+# job tuning, localization, Prisma pool, CORS preflight) has a built-in default.
+# See docs/caspian/environment.md before adding one here.
+""",
+        )
+    )
+
+    return "\n\n".join(sections) + "\n"

create_caspian_app/features.py

@@ -0,0 +1,87 @@
+"""The optional features a Caspian app can be generated with, and what each one owns."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+FEATURES = ("tailwindcss", "mcp", "prisma", "websocket")
+
+LABELS = {
+    "tailwindcss": "Tailwind CSS",
+    "mcp": "MCP (Model Context Protocol)",
+    "prisma": "Prisma ORM (Caspian DB)",
+    "websocket": "WebSocket",
+}
+
+
+@dataclass
+class Answers:
+    project_name: str = "my-app"
+    tailwindcss: bool = False
+    mcp: bool = False
+    prisma: bool = False
+    websocket: bool = False
+
+    def enabled(self) -> list[str]:
+        return [name for name in FEATURES if getattr(self, name)]
+
+
+# Python requirement names owned by each feature. The pinned specifiers come
+# from the template's pyproject.toml, so a template sync is the only place
+# versions change.
+FEATURE_DEPENDENCIES = {
+    "mcp": ("fastmcp",),
+    "websocket": ("websockets",),
+    "prisma": ("psycopg2-binary", "asyncpg", "aiosqlite", "aiomysql", "cryptography"),
+}
+FEATURE_DEV_DEPENDENCIES = {
+    "prisma": ("caspian-db",),
+}
+
+# Template paths (POSIX, relative to the project root) that exist only for a
+# feature. A trailing slash marks a directory.
+FEATURE_PATHS = {
+    "mcp": ("src/lib/mcp/", "settings/serve_mcp.py"),
+    "websocket": ("src/lib/websocket/",),
+    "prisma": (
+        "prisma/",
+        "src/lib/prisma/",
+    ),
+    "tailwindcss": ("public/js/tailwind-merge.mjs", "public/js/bundle-mjs.mjs.map"),
+}
+
+# The package main.py imports lazily for each feature.
+FEATURE_MODULES = {
+    "mcp": "src.lib.mcp",
+    "websocket": "src.lib.websocket",
+    "prisma": "src.lib.prisma",
+}
+
+
+def owned_by(path: str, prefixes: tuple[str, ...]) -> bool:
+    return any(path == p or (p.endswith("/") and path.startswith(p)) for p in prefixes)
+
+
+def excluded_paths(answers: Answers) -> tuple[str, ...]:
+    """Every template path that must not exist for these answers."""
+    paths: list[str] = []
+    for feature, owned in FEATURE_PATHS.items():
+        if not getattr(answers, feature):
+            paths.extend(owned)
+    return tuple(paths)
+
+
+def disabled_modules(answers: Answers) -> list[str]:
+    return [module for feature, module in FEATURE_MODULES.items() if not getattr(answers, feature)]
+
+
+def disabled_dependencies(answers: Answers) -> tuple[set[str], set[str]]:
+    deps: set[str] = set()
+    dev: set[str] = set()
+    for feature, names in FEATURE_DEPENDENCIES.items():
+        if not getattr(answers, feature):
+            deps.update(names)
+    for feature, names in FEATURE_DEV_DEPENDENCIES.items():
+        if not getattr(answers, feature):
+            dev.update(names)
+    return deps, dev

create_caspian_app/installer.py

@@ -0,0 +1,106 @@
+"""Run uv to create the environment and finish the build of a scaffolded app."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import ui
+from .features import Answers, disabled_dependencies
+from .scaffold import requirement_name, template_pyproject
+
+
+class InstallError(RuntimeError):
+    pass
+
+
+def _works(command: list[str]) -> bool:
+    try:
+        return (
+            subprocess.run(command + ["--version"], capture_output=True, check=False).returncode
+            == 0
+        )
+    except OSError:
+        return False
+
+
+def find_uv(allow_install: bool = True) -> list[str]:
+    """Return the argv prefix that runs uv, installing it with pip as a last resort."""
+    candidates = []
+    if exe := shutil.which("uv"):
+        candidates.append([exe])
+    candidates.append([sys.executable, "-m", "uv"])
+    for candidate in candidates:
+        if _works(candidate):
+            return candidate
+    if allow_install:
+        ui.info("uv was not found. Installing it with pip (python -m pip install uv)...")
+        result = subprocess.run(
+            [sys.executable, "-m", "pip", "install", "--upgrade", "uv"], check=False
+        )
+        if result.returncode == 0 and _works([sys.executable, "-m", "uv"]):
+            return [sys.executable, "-m", "uv"]
+    raise InstallError(
+        "uv is required but could not be found or installed.\n"
+        "Install it from https://docs.astral.sh/uv/getting-started/installation/ and run again."
+    )
+
+
+def run(argv: list[str], cwd: Path) -> None:
+    ui.note("$ " + " ".join(_display(a) for a in argv))
+    # A VIRTUAL_ENV from the shell that launched us would point uv at the wrong venv.
+    env = {k: v for k, v in os.environ.items() if k != "VIRTUAL_ENV"}
+    result = subprocess.run(argv, cwd=cwd, env=env, check=False)
+    if result.returncode != 0:
+        raise InstallError(f"Command failed with exit code {result.returncode}: {argv[-1]}")
+
+
+def _display(arg: str) -> str:
+    return "uv" if arg.lower().endswith(("uv", "uv.exe")) and os.sep in arg else arg
+
+
+def sync(root: Path, uv: list[str]) -> None:
+    ui.step("Installing Python dependencies (uv sync --group dev)")
+    run(uv + ["sync", "--group", "dev"], root)
+
+
+def update_dependencies(root: Path, answers: Answers, uv: list[str]) -> None:
+    """Re-pin managed requirements to the template and drop disabled-feature ones."""
+    import tomllib
+
+    current = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    template = template_pyproject()
+    removed, removed_dev = disabled_dependencies(answers)
+
+    have = {requirement_name(s) for s in current.get("project", {}).get("dependencies", [])}
+    have_dev = {
+        requirement_name(s)
+        for s in current.get("dependency-groups", {}).get("dev", [])
+        if isinstance(s, str)
+    }
+
+    drop = sorted(have & removed)
+    drop_dev = sorted(have_dev & removed_dev)
+    add = [s for s in template["project"]["dependencies"] if requirement_name(s) not in removed]
+    add_dev = [
+        s for s in template["dependency-groups"]["dev"] if requirement_name(s) not in removed_dev
+    ]
+
+    ui.step("Updating Python dependencies")
+    if drop:
+        run(uv + ["remove", "--no-sync", *drop], root)
+    if drop_dev:
+        run(uv + ["remove", "--no-sync", "--group", "dev", *drop_dev], root)
+    run(uv + ["add", "--no-sync", *add], root)
+    run(uv + ["add", "--no-sync", "--group", "dev", *add_dev], root)
+
+
+def build_css(root: Path, answers: Answers, uv: list[str]) -> None:
+    if answers.tailwindcss:
+        ui.step("Downloading the pinned Tailwind CSS compiler (checksum verified)")
+        run(uv + ["run", "python", "settings/build.py", "setup"], root)
+    ui.step("Building CSS (src/app/globals.css -> public/css/styles.css)")
+    run(uv + ["run", "python", "settings/build.py", "css"], root)