@cherishxn/agent-scaffold 0.0.0-stage → 1.0.0

package/templates/react-fastapi-antd/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-antd/README.md

@@ -0,0 +1,55 @@
+## 运行
+
+需要 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；英文名用于目录和工程标识。基础示例只包含个人记录功能，不因简介自动新增业务。
+
+## 验证
+
+安装依赖后，由已安装的 CLI 执行：
+
+```bash
+scaffold doctor --dir . --json
+scaffold verify --dir . --profile baseline --json
+scaffold report --dir . --json
+```
+
+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。按需运行 api:generate 更新 TypeScript 客户端类型，不在 verify 中修改源码。
+
+## 认证边界
+
+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：antd。需要 Python 3.12 + uv、Bun（前端）。
+后端镜像：docker build backend；前端构建产物位于 web/dist，生产需要同源反向代理 /api 到后端。

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

@@ -0,0 +1,14 @@
+# 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'.

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

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

package/templates/react-fastapi-antd/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-antd/backend/alembic.ini

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

package/templates/react-fastapi-antd/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-antd/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-antd/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-antd/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-antd/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-antd/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-antd/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-antd/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-antd/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