Metadata-Version: 2.5
Name: create-caspian-app
Version: 0.0.4
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 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`, `setup`, `--check`) |
| `uv run browser-log`  | `uv run python settings/browser_log.py`   | Browser errors from the dev session     |

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