@cherishxn/agent-scaffold 0.0.0-stage → 1.1.0

package/templates/react-fastapi-shadcn/DESIGN.md

@@ -0,0 +1,208 @@
+---
+version: "alpha"
+name: "Scientific Workspace"
+description: "从 CleerScience 提炼的通用深色科技视觉，适配可读、安静的工具型界面。"
+colors:
+  primary: "#8fc3ff"
+  primary-hover: "#b5d8ff"
+  primary-active: "#69a9f3"
+  primary-text: "#02040a"
+  background: "#02040a"
+  text: "#f4f8ff"
+  surface: "#0b111d"
+  focus: "#8fc3ff"
+  border: "#283547"
+  brand: "#f4f8ff"
+  eyebrow: "#9baecb"
+  muted: "#a1afc3"
+  intro: "#b5c3d7"
+  panel-border: "#283547"
+  divider: "#202c3e"
+  record-text: "#f4f8ff"
+  record-meta: "#a1afc3"
+  record-hover: "#142237"
+  pagination-border: "#283547"
+  empty: "#a1afc3"
+  empty-heading: "#e2eeff"
+  success-background: "#102b25"
+  success-border: "#387c69"
+  success-text: "#a2e6cc"
+  error-background: "#311b24"
+  error-border: "#8f4c61"
+  error-text: "#ffbdcd"
+  footer-border: "#283547"
+  footer-text: "#a1afc3"
+  badge-border: "#435773"
+  badge-text: "#b5c3d7"
+  control-focus: "#8fc3ff"
+  control-border: "#657891"
+  control-background: "#080e18"
+  secondary-border: "#657891"
+  secondary-text: "#e2eeff"
+  secondary-hover: "#19283d"
+  danger-border: "#ad6578"
+  danger-background: "#311b24"
+  danger-text: "#ffbdcd"
+  danger-hover: "#472636"
+typography:
+  body:
+    fontFamily: "Inter,ui-sans-serif,-apple-system,BlinkMacSystemFont,\"Segoe UI\",\"PingFang SC\",\"Hiragino Sans GB\",\"Microsoft YaHei\",sans-serif"
+    fontSize: "16px"
+    lineHeight: 1.65
+  h1:
+    fontSize: "36px"
+    lineHeight: 1.2
+    letterSpacing: "-0.03em"
+    fontWeight: 560
+  login-heading:
+    fontSize: "48px"
+    lineHeight: 1.15
+    fontWeight: 560
+    letterSpacing: "-0.03em"
+  h2:
+    fontSize: "20px"
+    lineHeight: 1.4
+    fontWeight: 580
+    letterSpacing: "-0.02em"
+  h3:
+    fontSize: "18px"
+    fontWeight: 600
+    lineHeight: 1.5
+  label:
+    fontSize: "14px"
+    fontWeight: 600
+  eyebrow:
+    fontSize: "11px"
+    fontWeight: 700
+    letterSpacing: "0.22em"
+    lineHeight: 1.5
+  button:
+    fontSize: "14px"
+    fontWeight: 600
+    lineHeight: "20px"
+  caption:
+    fontSize: "12px"
+  intro:
+    fontSize: "18px"
+    lineHeight: 1.8
+  mobile-heading:
+    fontSize: "32px"
+    lineHeight: 1.2
+  mobile-page-heading:
+    fontSize: "28px"
+    lineHeight: 1.25
+rounded:
+  md: "0px"
+  panel: "0px"
+  full: "0px"
+spacing:
+  s0: "0px"
+  s1: "1px"
+  s2: "2px"
+  s3: "3px"
+  s4: "4px"
+  s6: "6px"
+  s8: "8px"
+  s10: "10px"
+  s12: "12px"
+  s14: "14px"
+  s15: "15px"
+  s16: "16px"
+  s18: "18px"
+  s20: "20px"
+  s22: "22px"
+  s24: "24px"
+  s26: "26px"
+  s28: "28px"
+  s30: "30px"
+  s32: "32px"
+  s34: "34px"
+  s38: "38px"
+  s44: "44px"
+  s48: "48px"
+  s60: "60px"
+  s80: "80px"
+  s88: "88px"
+  shell-max: "1240px"
+  login-max: "1020px"
+  intro-max: "460px"
+  login-card-max: "430px"
+  list-min: "260px"
+  footer-reserve: "155px"
+  mobile-breakpoint: "760px"
+  control-min: "44px"
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-text}"
+    rounded: "{rounded.md}"
+    height: "{spacing.control-min}"
+  panel:
+    backgroundColor: "{colors.surface}"
+    padding: "{spacing.s26}"
+    rounded: "{rounded.panel}"
+  input:
+    rounded: "{rounded.md}"
+---
+
+## Overview
+
+**Scientific Workspace**：从 [CleerScience 官网](https://cleerscience.com/) 提炼的通用深色科技视觉。以近黑蓝底、冷白文字、冰蓝重点、直角薄边框和清晰排版传达秩序；各组件库使用同一份视觉、控件和结构规格。它服务于登录、列表与编辑任务，不把科学品牌、产品名或营销文案带入生成项目。
+
+来源于 2026-10-20 对官网桌面 1440px 和手机 375px 的实际页面及计算样式观察。官网原值包括背景 #02040a、正文 #f4f8ff、冰蓝 #8fc3ff、0px 面板圆角；本模板沿用这些核心值。正文与控件对比度、实体表面、较小标题和 44px 以上操作尺寸是工具型界面的适配决定，并非官网原样复刻。背景视频、品牌标识、全屏叙事和科学插图不属于本模板。
+
+**唯一编辑源**：`design/tokens.json`、`design/widgets.json`、`design/structure.json`、`design/guide.md` 及中立布局/控件样式。执行 `npm run design:sync` 生成本文件、design-tokens.css、design-layout.css、design-widgets.css、design-runtime.json，再执行 `npm run design:check`。不要直接修改派生产物；build/typecheck/lint 会拒绝漂移。YAML 是与组件库无关的有效 token；阴影等非标准字段在正文给出，避免伪装成官方 schema 字段。
+
+## Colors
+
+背景使用 `colors.background`，面板使用 `colors.surface`，输入区使用 `colors.control-background`。正文使用 `colors.text`，辅助说明使用 `colors.muted`，标题不降低透明度。不要把官网用于装饰的低透明度文字直接用于表单标签或必要说明。
+
+`primary` 仅用于主要操作、当前选中项和可见焦点；按钮文字使用 `primary-text`，确保亮色按钮上的深色字可读。`primary-hover` / `primary-active` 表达交互状态。普通表面保持中性冷色，避免整页泛蓝或大面积发光。错误和成功使用各自的 background/border/text 组合，同时保留明确文字或状态角色。
+
+必要文字对比度至少 4.5:1，焦点与操作控件边界至少 3:1；装饰分隔线可以更弱。对比度必须按实际背景检查，不能只比较两个透明 token。新项目若改变主色，需重新验证文字、hover、active 和焦点，不仅替换一个十六进制值。
+
+## Typography
+
+一套无衬线字体贯穿全站：Inter 可用时优先，否则落到系统字体与 PingFang SC / Microsoft YaHei；不主动下载字体。中文正文 16px、行高 1.65，标签 14px，辅助信息 12px；避免将官网 11px 导航字直接当作表单正文。
+
+页面标题 36px、登录标题 48px，手机分别 28px/32px；h2 为 20px，h3 为 18px。标题使用 560–600 字重与轻微负字距，中文不采用官网展示标题的 -0.075em 压缩。`eyebrow` 用 11px、700 字重、0.22em 字距作短标签，不承载唯一操作说明。标题平衡换行，说明文字自然换行，长记录标题允许断行，账号单行省略。
+
+具体字号、字重与行高以 typography 为准。所有套件严格使用同一按钮字号 14px 与行高 20px；不要混用第二套展示字体。
+
+## Layout
+
+沿用工作空间的信息结构：顶栏、页面标题、记录列表与编辑区。桌面 shell-max 为 1240px，水平边距 32px；记录区两栏，登录页说明与表单两栏。面板间距 24px，桌面面板内边距 26px。避免为了科技感给每一行再套卡片。
+
+在 `spacing.mobile-breakpoint`（当前 760px）收为单列，水平边距 18px、面板内边距 20px。375px 不允许横向溢出；操作区允许自然增长，不用全屏固定高度压缩内容。布局 CSS 与媒体查询由同一 token 源生成。
+
+官网的超大留白、全屏分区与宽幅媒体可用于品牌落地页，但不是登录和 CRUD 页面默认规则。新增导航、统计卡或营销分区需要业务需求，不能由设计规范自行扩张功能。
+
+## Elevation & Depth
+
+面板首先依靠深浅表面和 1px 冷色边框分层；阴影为 `0 16px 48px rgba(0,0,0,0.18)`，来自 design/tokens.json 的 effects.panelShadow。控件边框比装饰分隔线更清晰。选中记录增加冰蓝侧线与背景变化，不只靠文字颜色。
+
+官网玻璃面板的 blur(14px) 和影像叠层可作为品牌页面参考；本工具使用实体表面保证阅读和性能，不全局加 backdrop-filter。禁止给每个按钮、输入框加辉光或重阴影。
+
+## Shapes
+
+`rounded.md` 为 0px、`rounded.panel` 为 0px、`rounded.full` 为 0px：按钮、输入、面板和标签保持精确直角。`full` 是沿用的 token 名，在当前主题不代表胶囊。修改形状时同步组件 token；所有尺寸的圆角由套件显式绑定，避免库派生出另一种圆角。
+
+边框厚度通常为 1px。图标沿用所选组件库的简洁线性风格，保持光学尺寸一致；不复制官网 Logo 或专有插图。
+
+## Components
+
+主按钮：冰蓝填充、深色文字；secondary：深色表面与清晰描边；danger：暗红表面与浅红文字。按钮与单行输入高度 44px，保持键盘焦点。default/hover/active/focus/disabled/loading 与输入错误态由 design/widgets.json 定义，套件逐项翻译，不接受原生默认值偏差。颜色派生结果以共享 token 为准；图标使用同一份 SVG 几何，套件不得替换成近似图标。
+
+输入：深色底、冷白输入文字、可读 placeholder，标签始终可见。加载时禁用重复提交；错误后保留输入；空态说明下一步；记录正文以纯文本显示。删除需确认，退出清除当前编辑内容。控件自身焦点、输入和禁用状态由原生控件/套件管理；登录身份、校验、记录状态与请求隔离只在框架无关的 workspace-model 中实现。页面区块顺序和嵌套来自 design/structure.json，框架视图负责绑定。上述行为由业务实现与 Playwright 测试负责，设计文件不替代执行逻辑。
+
+动效只用于短暂状态反馈；遵循 150–250ms 的颜色/边框变化，不新增背景循环、滚动接管或入场延迟。`prefers-reduced-motion: reduce` 下取消非必要动画与过渡。品牌页面如果采用背景媒体，需静态后备、降低亮度、保障文字对比度，并单独验收性能。
+
+## Do's and Don'ts
+
+- UI 开发前读本文件；设计修改先改源，再 sync/check，最后看浏览器真实结果。
+- 复用冷色中性层级、单一字体、直角薄边框与有限强调色；保持所选 UI 库的一致性。
+- 验证默认、hover、active、focus、disabled、loading、empty、error，以及键盘与 375px 布局。
+- 不将来源网站的行业、品牌内容、低对比装饰字或全屏动效当成通用业务要求。
+- 不给每个面板加玻璃、光晕或渐变；库默认值与规格不符时修改套件，不反向修改规范。
+- 全量执行控件/页面比较：位置容差 ≤0.6 CSS px；颜色、圆角、图标几何零容差；必须覆盖 widgets.json 和 structure.json 的全部声明项。
+- 不直接编辑生成文件，不把文档格式通过当成浏览器验收通过，不根据项目简介随机改变视觉。

package/templates/react-fastapi-shadcn/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qinchaomeishenmeshi
+
+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.

package/templates/react-fastapi-shadcn/README.md

@@ -0,0 +1,64 @@
+## 运行
+
+需要 Node.js 24、Docker 和该模板的运行时（见 project.json 与下方说明）。
+
+```bash
+npm run setup
+npm run dev
+```
+
+`setup` 安装依赖，然后显式启动本地 PostgreSQL、迁移并创建 A/B 开发账号。首次生成随机密码，登录信息在 Git 忽略的 `.scaffold-local-credentials`；不是生产默认密码。已有 `.env` 时保留配置，请仅使用本地开发实例。
+
+默认数据库端口为 54329、API 为 8000、Web 为 5173（Next 为 3000）。首次 setup 可用 `POSTGRES_PORT`、`PORT`、`WEB_PORT` 环境变量指定空闲端口；后续沿用 `.env`。
+
+页面名称与简介来自根 project.json；英文名用于目录和工程标识。基础示例只包含个人记录功能，不因简介自动新增业务。
+
+## 验证
+
+安装前可只检查工具；doctor 不会安装依赖或启动服务：
+
+```bash
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ doctor --dir . --tools-only --json
+```
+
+安装依赖后，先做快速检查，再按需要验证完整业务：
+
+```bash
+npm run check
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ doctor --dir . --json
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ verify --dir . --profile baseline --json
+npx @cherishxn/agent-scaffold@__CLI_VERSION__ report --dir . --json
+```
+
+`check` 顺序执行类型、Lint、构建，任一步失败即停止；它不创建数据库、不执行迁移或业务测试。
+
+verify 创建自己的临时 PostgreSQL 并注入连接，不使用开发 DATABASE_URL；完成后释放本次容器。单独运行项目命令时需要显式提供本地环境：
+
+```bash
+node scripts/project.mjs typecheck
+node scripts/project.mjs lint
+node scripts/project.mjs build
+node scripts/project.mjs test:native
+node scripts/project.mjs test:api
+node scripts/project.mjs test:e2e
+node scripts/project.mjs api:generate
+```
+
+接口：docs/openapi.json；结构：docs/PROJECT.md；规则：AGENTS.md。修改契约后运行 npm run api:generate 更新 TypeScript 类型。npm run api:check 在临时目录重新生成并只读比较，check/verify 自动执行；test:api 同时按 OpenAPI 检查真实响应状态、必填字段和类型。验证不会自动修改源码。
+
+## 认证边界
+
+JWT 模板只在浏览器内存保存 Token，页面刷新需重新登录；退出清除内存，不声称服务器撤销旧 JWT。Session 模板使用 HttpOnly Cookie 和同源写入校验，退出后 Session 失效。所有记录访问由服务端按当前用户过滤。
+
+## 容器构建
+
+按模板提供的 Dockerfile 构建，配置自己的数据库和秘密；构建与本地验证不代表生产部署或业务验收通过。不要把 `.env`、凭据文件或运行报告加入镜像/版本库。
+
+## 视觉设计
+
+UI 开发前读根目录 DESIGN.md 和内置 design-contract Skill。`design/tokens.json`、`widgets.json`、`structure.json` 与公共 CSS 是组件库无关的设计源；`web/src/ui.tsx` 是所选组件库适配器；`workspace-model.ts` 管理业务。修改源后执行 `npm run design:sync`，再运行只读漂移检查 `npm run design:check` 和浏览器契约检查 `npm run design:verify`。后者临时创建测试入口，验证全部声明的组件状态及页面（桌面/移动端），输出 `reports/design-check/result.json`，结束后清理入口。需要已安装依赖及 Playwright Chromium。build/typecheck/lint 同样检查漂移。当前项目的 PASS 仅证明已选适配器；新增库须保持共享规范和业务不变，添加适配器、依赖及框架绑定，并在脚手架完整矩阵中复验。
+
+## 本模板
+
+技术栈：react-fastapi；UI：shadcn。需要 Python 3.12 + uv、Bun（前端）。
+后端镜像：docker build backend；前端构建产物位于 web/dist，生产需要同源反向代理 /api 到后端。

package/templates/react-fastapi-shadcn/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,18 @@
+# Template sources and licenses
+
+Templates are maintained derivatives, not unmodified upstream distributions. Exact bundled files are hashed in templates/catalog.json; npm/uv/pnpm/Bun locks pin dependency resolution. Initialization is offline and never invokes upstream generators.
+
+| Source | Fixed reference | Use / modifications | License |
+| --- | --- | --- | --- |
+| fastapi/full-stack-fastapi-template | b1125d8839482cb7bbae603ddc6d0081bf87532e | SQLModel/Alembic/JWT/pwdlib foundation; reduced accounts, replaced sample feature with owner-scoped records, retained Bun frontend | MIT, licenses/fastapi.txt |
+| nestjs/typescript-starter | a122dea65cd0610ee205d7765ed46f9d73629141 | Nest module/bootstrap foundation; added Prisma, JWT/Guard, Jest/Supertest; no deployment tooling | MIT, licenses/nest.txt |
+| Spring Initializr | starter.zip fetched 2026-10-19; Maven Wrapper and Java layout | Generator returned unresolved 4.1.1.RELEASE; parent adjusted to stable Maven Central 3.5.16, Session/JPA/Flyway/CRUD added | Apache-2.0 wrapper, licenses/spring.txt |
+| create-next-app | npm 16.4.2 | Official App Router/TypeScript baseline; Better Auth + Prisma + records; no remote fonts | MIT, licenses/next.txt |
+| shadcn/ui | Button/Input pattern, pinned source reference in licenses/sources.json | Adapted local CVA/Slot controls with Tailwind; retained copy ownership | MIT, licenses/shadcn.txt |
+| Ant Design | npm 6.6.6 | Installed dependency; no copied source | MIT (package license) |
+
+Package dependencies carry their own licenses. Generated apps include these notices; template authors must carry applicable notices when changing upstream-derived files. Names and marks remain their respective owners'.
+
+## Design and workflow reference
+
+VinkyDev/vibestart at commit `5768fc561340422bf7736499fe69b1aae263790a` (MIT) informed the preview, task-oriented Agent guidance, quick checks and template-layer collision rules. These changes are independently implemented for Agent Scaffold; no VibeStart source, bundled skills, branding or UI assets are redistributed. The source review and selected adaptations are recorded in docs/reference/VIBESTART-REVIEW.md.

package/templates/react-fastapi-shadcn/backend/.python-version

@@ -0,0 +1 @@
+3.12

package/templates/react-fastapi-shadcn/backend/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:0.13.1 /uv /usr/local/bin/uv
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev
+COPY app ./app
+COPY migrations ./migrations
+COPY alembic.ini ./
+EXPOSE 8000
+CMD ["uv", "run", "--frozen", "--no-dev", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

package/templates/react-fastapi-shadcn/backend/alembic.ini

@@ -0,0 +1,3 @@
+[alembic]
+script_location = migrations
+prepend_sys_path = .

package/templates/react-fastapi-shadcn/backend/app/core/security.py

@@ -0,0 +1,25 @@
+# Adapted from the pinned FastAPI full-stack template; see THIRD_PARTY_NOTICES.md.
+from datetime import UTC, datetime, timedelta
+import os
+import jwt
+from pwdlib import PasswordHash
+from pwdlib.hashers.argon2 import Argon2Hasher
+from pwdlib.hashers.bcrypt import BcryptHasher
+
+password_hash = PasswordHash((Argon2Hasher(), BcryptHasher()))
+ALGORITHM = "HS256"
+SECRET_KEY = os.environ["AUTH_SECRET"]
+if len(SECRET_KEY) < 32:
+    raise RuntimeError("AUTH_SECRET must contain at least 32 characters")
+
+
+def create_access_token(subject: str, expires_delta: timedelta = timedelta(minutes=15)) -> str:
+    return jwt.encode({"exp": datetime.now(UTC) + expires_delta, "sub": subject, "aud": "personal-records"}, SECRET_KEY, algorithm=ALGORITHM)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    return password_hash.verify(plain_password, hashed_password)
+
+
+def get_password_hash(password: str) -> str:
+    return password_hash.hash(password)

package/templates/react-fastapi-shadcn/backend/app/db.py

@@ -0,0 +1,11 @@
+import os
+from collections.abc import Generator
+from sqlmodel import Session, create_engine
+
+url = os.environ["DATABASE_URL"].replace("postgresql://", "postgresql+psycopg://", 1)
+engine = create_engine(url, pool_pre_ping=True, echo=False)
+
+
+def get_session() -> Generator[Session, None, None]:
+    with Session(engine) as session:
+        yield session

package/templates/react-fastapi-shadcn/backend/app/main.py

@@ -0,0 +1,146 @@
+from datetime import UTC, datetime
+from typing import Annotated, Any
+from uuid import UUID
+import jwt
+from fastapi import Depends, FastAPI, HTTPException, Query, Request, Response
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from pydantic import BaseModel, ConfigDict, field_validator
+from sqlalchemy import func
+from sqlmodel import Session, col, select
+from app.core.security import ALGORITHM, SECRET_KEY, create_access_token, verify_password
+from app.db import get_session
+from app.models import PersonalRecord, User
+
+app = FastAPI(title="Personal Records", docs_url="/api/docs", openapi_url="/api/openapi.json")
+Db = Annotated[Session, Depends(get_session)]
+bearer = HTTPBearer(auto_error=False)
+
+
+@app.exception_handler(HTTPException)
+async def http_error(_request: Request, exc: HTTPException) -> JSONResponse:
+    messages = {401: "请重新登录。", 404: "记录不存在。", 422: "输入不合法。"}
+    return JSONResponse(status_code=exc.status_code, content={"error": {"code": str(exc.status_code), "message": messages.get(exc.status_code, "请求失败。")}})
+
+
+@app.exception_handler(RequestValidationError)
+async def validation_error(_request: Request, _exc: RequestValidationError) -> JSONResponse:
+    return JSONResponse(status_code=422, content={"error": {"code": "INVALID_INPUT", "message": "输入不合法，请检查字段和长度。"}})
+
+
+class Login(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    email: str
+    password: str
+
+
+class RecordInput(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    title: str
+    content: str
+
+    @field_validator("title")
+    @classmethod
+    def valid_title(cls, value: str) -> str:
+        value = value.strip()
+        if not 1 <= len(value) <= 120:
+            raise ValueError("Invalid title length")
+        return value
+
+    @field_validator("content")
+    @classmethod
+    def valid_content(cls, value: str) -> str:
+        if len(value) > 10000:
+            raise ValueError("Invalid content length")
+        return value
+
+
+def current_user(db: Db, auth: Annotated[HTTPAuthorizationCredentials | None, Depends(bearer)]) -> User:
+    try:
+        if auth is None:
+            raise ValueError("missing")
+        claims = jwt.decode(auth.credentials, SECRET_KEY, algorithms=[ALGORITHM], audience="personal-records", options={"require": ["exp", "sub", "aud"]})
+        user = db.get(User, UUID(claims["sub"]))
+        if user is None:
+            raise ValueError("missing")
+        return user
+    except (jwt.InvalidTokenError, ValueError, KeyError):
+        raise HTTPException(401) from None
+
+
+Identity = Annotated[User, Depends(current_user)]
+
+
+def public_record(row: PersonalRecord) -> dict[str, Any]:
+    return {"id": str(row.id), "title": row.title, "content": row.content, "created_at": row.created_at.isoformat(), "updated_at": row.updated_at.isoformat()}
+
+
+def owned(db: Session, record_id: UUID, user: User) -> PersonalRecord:
+    row = db.exec(select(PersonalRecord).where(PersonalRecord.id == record_id, PersonalRecord.owner_id == user.id)).first()
+    if row is None:
+        raise HTTPException(404)
+    return row
+
+
+@app.get("/api/health")
+def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@app.post("/api/auth/login")
+def login(body: Login, db: Db) -> dict[str, Any]:
+    user = db.exec(select(User).where(User.email == body.email.strip().lower())).first()
+    if user is None or not verify_password(body.password, user.hashed_password):
+        raise HTTPException(401)
+    return {"user": {"id": str(user.id), "email": user.email}, "token": create_access_token(str(user.id)), "mode": "jwt"}
+
+
+@app.get("/api/auth/me")
+def me(user: Identity) -> dict[str, Any]:
+    return {"user": {"id": str(user.id), "email": user.email}}
+
+
+@app.post("/api/auth/logout", status_code=204)
+def logout(_user: Identity) -> Response:
+    return Response(status_code=204)
+
+
+@app.get("/api/records")
+def records(user: Identity, db: Db, page: Annotated[int, Query(ge=1, le=1000000)] = 1, pageSize: Annotated[int, Query(ge=1, le=100)] = 10) -> dict[str, Any]:
+    total = db.exec(select(func.count()).select_from(PersonalRecord).where(PersonalRecord.owner_id == user.id)).one()
+    rows = db.exec(select(PersonalRecord).where(PersonalRecord.owner_id == user.id).order_by(col(PersonalRecord.created_at).desc(), col(PersonalRecord.id).desc()).offset((page - 1) * pageSize).limit(pageSize)).all()
+    return {"items": [public_record(row) for row in rows], "total": total, "page": page, "pageSize": pageSize}
+
+
+@app.post("/api/records", status_code=201)
+def create(body: RecordInput, user: Identity, db: Db) -> dict[str, Any]:
+    row = PersonalRecord(owner_id=user.id, **body.model_dump())
+    db.add(row)
+    db.commit()
+    db.refresh(row)
+    return public_record(row)
+
+
+@app.get("/api/records/{record_id}")
+def detail(record_id: UUID, user: Identity, db: Db) -> dict[str, Any]:
+    return public_record(owned(db, record_id, user))
+
+
+@app.put("/api/records/{record_id}")
+def update(record_id: UUID, body: RecordInput, user: Identity, db: Db) -> dict[str, Any]:
+    row = owned(db, record_id, user)
+    row.title, row.content = body.title, body.content
+    row.updated_at = datetime.now(UTC)
+    db.add(row)
+    db.commit()
+    db.refresh(row)
+    return public_record(row)
+
+
+@app.delete("/api/records/{record_id}", status_code=204)
+def delete(record_id: UUID, user: Identity, db: Db) -> Response:
+    row = owned(db, record_id, user)
+    db.delete(row)
+    db.commit()
+    return Response(status_code=204)

package/templates/react-fastapi-shadcn/backend/app/models.py

@@ -0,0 +1,21 @@
+from datetime import UTC, datetime
+from uuid import UUID, uuid4
+from sqlmodel import SQLModel, Field
+from sqlalchemy import Column, DateTime, Text
+
+
+class User(SQLModel, table=True):
+    __tablename__ = "app_user"
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    email: str = Field(unique=True, index=True)
+    hashed_password: str
+
+
+class PersonalRecord(SQLModel, table=True):
+    __tablename__ = "personal_record"
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    owner_id: UUID = Field(foreign_key="app_user.id", index=True)
+    title: str
+    content: str = Field(sa_column=Column(Text, nullable=False))
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC), sa_column=Column(DateTime(timezone=True), nullable=False))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC), sa_column=Column(DateTime(timezone=True), nullable=False))

package/templates/react-fastapi-shadcn/backend/app/seed.py

@@ -0,0 +1,21 @@
+import os
+from sqlmodel import Session, select
+from app.core.security import get_password_hash
+from app.db import engine
+from app.models import User
+
+
+def main() -> None:
+    password = os.environ["SEED_PASSWORD"]
+    if len(password) < 12:
+        raise RuntimeError("Development/test seed password must be at least 12 characters")
+    with Session(engine) as db:
+        for key in ("SEED_A_EMAIL", "SEED_B_EMAIL"):
+            email = os.environ[key].strip().lower()
+            if not db.exec(select(User).where(User.email == email)).first():
+                db.add(User(email=email, hashed_password=get_password_hash(password)))
+        db.commit()
+
+
+if __name__ == "__main__":
+    main()

package/templates/react-fastapi-shadcn/backend/migrations/env.py

@@ -0,0 +1,9 @@
+from alembic import context
+from sqlmodel import SQLModel
+from app.db import engine
+from app import models  # noqa: F401
+
+with engine.connect() as connection:
+    context.configure(connection=connection, target_metadata=SQLModel.metadata)
+    with context.begin_transaction():
+        context.run_migrations()

package/templates/react-fastapi-shadcn/backend/migrations/versions/0001_initial.py

@@ -0,0 +1,18 @@
+from alembic import op
+import sqlalchemy as sa
+revision = "0001"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.create_table("app_user", sa.Column("id", sa.Uuid(), primary_key=True), sa.Column("email", sa.String(), nullable=False), sa.Column("hashed_password", sa.String(), nullable=False))
+    op.create_index("ix_app_user_email", "app_user", ["email"], unique=True)
+    op.create_table("personal_record", sa.Column("id", sa.Uuid(), primary_key=True), sa.Column("owner_id", sa.Uuid(), sa.ForeignKey("app_user.id"), nullable=False), sa.Column("title", sa.String(), nullable=False), sa.Column("content", sa.Text(), nullable=False), sa.Column("created_at", sa.DateTime(timezone=True), nullable=False), sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False))
+    op.create_index("ix_personal_record_owner_id", "personal_record", ["owner_id"])
+
+
+def downgrade():
+    op.drop_table("personal_record")
+    op.drop_table("app_user")

package/templates/react-fastapi-shadcn/backend/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "backend"
+version = "1.0.0"
+requires-python = ">=3.12,<3.13"
+dependencies = ["fastapi[standard]==0.141.1", "sqlmodel==0.0.46", "alembic==1.19.1", "psycopg[binary]==3.3.6", "pyjwt==2.15.0", "pwdlib[argon2,bcrypt]==0.3.1", "pydantic==2.13.5", "httpx==0.28.1"]
+[dependency-groups]
+dev = ["pytest>=8,<10", "mypy>=1.18,<2", "ruff>=0.16,<1"]
+[tool.mypy]
+python_version = "3.12"
+strict = true
+[tool.ruff]
+target-version = "py312"
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/templates/react-fastapi-shadcn/backend/tests/test_api.py

@@ -0,0 +1,27 @@
+import os
+from datetime import timedelta
+from fastapi.testclient import TestClient
+from app.main import app
+from app.core.security import create_access_token
+
+
+def test_identity_persistence_and_ownership():
+    with TestClient(app) as c:
+        assert c.get("/api/records").status_code == 401
+        login = c.post("/api/auth/login", json={"email": os.environ["SEED_A_EMAIL"], "password": os.environ["SEED_PASSWORD"]}).json()
+        a = {"Authorization": "Bearer " + login["token"]}
+        expired = create_access_token(login["user"]["id"], timedelta(seconds=-10))
+        assert c.get("/api/records", headers={"Authorization": "Bearer " + expired}).status_code == 401
+        btoken = c.post("/api/auth/login", json={"email": os.environ["SEED_B_EMAIL"], "password": os.environ["SEED_PASSWORD"]}).json()["token"]
+        b = {"Authorization": "Bearer " + btoken}
+        assert c.post("/api/records", headers=a, json={"title": "x", "content": "", "owner_id": login["user"]["id"]}).status_code == 422
+        row = c.post("/api/records", headers=a, json={"title": "  native test  ", "content": "persisted"}).json()
+        path = "/api/records/" + row["id"]
+        assert c.get(path, headers=a).json()["content"] == "persisted"
+        assert c.get(path, headers=b).status_code == 404
+        assert c.put(path, headers=b, json={"title": "x", "content": ""}).status_code == 404
+        assert c.delete(path, headers=b).status_code == 404
+        assert c.put(path, headers=a, json={"title": "", "content": ""}).status_code == 422
+        assert c.get(path, headers=a).json()["title"] == "native test"
+        assert c.delete(path, headers=a).status_code == 204
+        assert c.get(path, headers=a).status_code == 404