Metadata-Version: 2.5
Name: create-caspian-app
Version: 0.0.11
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.

Caspian is in **alpha**. 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@latest my-app
```

Use `@latest` to check for the newest published installer. Without it, uvx can reuse
a cached older version. Verify with `uvx create-caspian-app@latest --version`;
use `@0.0.7` instead to run that exact release.

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, the installer runs `settings/build.py setup` before the CSS
build. Setup installs Tailwind's pinned official standalone executable and verifies
its checksum. The shared user cache is reused by every project, so the same
version/platform is downloaded once. Existing verified project-local downloads
can seed that cache. PulsePoint and Tailwind Merge are bundled scaffold files.

Then:

```bash
cd my-app
uv run dev
```

`uv run dev` is a shortcut for `uv run python main.py`; both start the development server.
The other everyday tools have short commands too; arguments pass through unchanged:

| Command               | Same as                                   | Does                                    |
| --------------------- | ----------------------------------------- | --------------------------------------- |
| `uv run dev`          | `uv run python main.py`                   | Start the development server            |
| `uv run restart`      | `uv run python settings/restart.py`       | Apply edits: graceful restart of the dev server (`--stop` to stop) |
| `uv run test`         | `uv run python settings/test.py`          | Quality gate: ty, Ruff, templates, pytest |
| `uv run format`       | `uv run python settings/format.py`        | Format markup and Python (`--check` to report only) |
| `uv run fix`          | `uv run python settings/fix.py`           | Format, apply lint fixes, run the gate  |
| `uv run build`        | `uv run python settings/build.py`         | Build CSS and validate sources (`css`, `pages`, `--check`) |
| `uv run browser-log`  | `uv run python settings/browser_log.py`   | Browser errors from the dev session     |
| `uv run generate`     | `uv run python settings/generate.py`      | Add a component, route, layout, or `route.py` endpoint to the app |

### Skip the questions

Pass flags and `-y`. Only the flags you pass are turned on:

```bash
uvx create-caspian-app@latest my-app --tailwindcss --mcp --prisma --websocket -y
uvx create-caspian-app@latest my-app --prisma --websocket -y
```

| Flag             | Feature                                                        |
| ---------------- | -------------------------------------------------------------- |
| `--tailwindcss`  | Tailwind CSS v4 (pinned standalone compiler in a shared user cache) |
| `--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@latest casp update project          # latest
uvx --from create-caspian-app@latest 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 asks about any features that aren't enabled yet and re-pins
the managed dependencies.

**It replaces only the template files nobody changed.** `caspian.config.json` keeps a
`scaffold` ledger: the SHA-256 of every template file as the installer wrote it. Edit
any file freely, by hand or with an AI agent; on the next update:

| File on disk | Update |
| --- | --- |
| Unchanged since the installer wrote it | Replaced with the new template version |
| Edited | Kept, and listed as yours |
| Deleted | Stays deleted |
| New in this template | Written |
| No longer in the template (or its feature was turned off) | Removed when unchanged, kept when edited; `prisma/` is never removed |

Take the template version of a file you edited with `--force` (repeatable):

```bash
uvx --from create-caspian-app@latest casp update project -y --force src/app/index.py
```

Some files follow fixed rules instead: `.env` and `uv.lock` are never written,
`public/css/styles.css` is rebuilt by the update's CSS build,
`src/app/globals.css` only gains or loses the Tailwind directives, `pyproject.toml` only
has the managed requirements re-pinned and missing `uv run` aliases added, and
`AGENTS.md` only has its `<!-- caspian:start -->` block replaced, so your notes around it
stay.

A project created before the ledger existed gets one on its first update: the installer
re-runs the version recorded in its config into a temporary folder to learn exactly which
files are unchanged.

## 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`.
