Init App Stack

Bootstrap a full-stack project with:

• Frontend: Vite 8+ + React + TanStack Router + TanStack Query + TanStack Form + TanStack Table + TanStack Virtual + Zustand + @bmsuisse/ui (BMS's shared shadcn/ui-based component library, public npm package) + @bmsuisse/datagrid (shared <DataGrid>/<TreeDataGrid>) + TailwindCSS v4, managed with bun — the shadcn CLI stays wired up as a fallback for anything @bmsuisse/ui doesn't cover
• Backend: FastAPI + Granian + pgdevkit (psycopg, no ORM), managed with uv, targeting Python 3.14
• DB: Postgres 17 via docker-compose.yml for dev; pgdevkit's pgdb testdb for tests; schema lives as .sql files under database/
• Types: @hey-api/openapi-ts generates a typed SDK, TanStack Query options, and Zod runtime validators from FastAPI's OpenAPI schema — the generated output is committed, not gitignored
• Task runner: just — the scaffold writes a root justfile (install, db-up, db-down, backend, frontend, dev, agent-preview, agent-preview-status, agent-preview-stop, generate-api, test). just dev runs backend + frontend together (Ctrl+C stops both); it does not start Postgres — run just db-up first. It uses set shell := ["bash", "-uc"] for &/wait, so Git Bash must be on PATH on Windows. Run just with no args to list recipes; always drive the project through just <recipe> instead of raw uv run / bun run / docker compose commands.
• Ports: randomly assigned high ports (seeded by project name, so deterministic per project — printed on scaffold completion)
• Agent preview: just agent-preview (scripts/agent_preview.py) is the parallel-safe alternative to just dev — for multiple worktrees/agents running on the same machine at once. It provisions its own pgdevkit-scoped Postgres database (project + git branch), builds the frontend once, and serves it from the backend (via a StaticFiles mount in backend/main.py) on a port the OS picks itself, so it never collides with or kills another worktree's dev server or database. The port is overridable with --port <n> or BACKEND_PORT. just agent-preview-status/-stop check/stop the instance for the current workspace.

Step 1: Run the scaffold script

This creates the full project structure deterministically — do not scaffold manually.

uv run python scripts/create.py <project-name>