@cherishxn/agent-scaffold 0.0.0-stage → 1.0.0

package/templates/react-nest-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-nest-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-nest-shadcn/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-nest；UI：shadcn。需要 pnpm + Node.js 24。
+后端镜像：docker build backend；前端构建产物位于 web/dist，生产需要同源反向代理 /api 到后端。

package/templates/react-nest-shadcn/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-nest-shadcn/backend/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:24-alpine
+RUN corepack enable && corepack prepare pnpm@10.28.2 --activate
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY prisma ./prisma
+RUN pnpm install --frozen-lockfile && pnpm exec prisma generate
+COPY tsconfig*.json ./
+COPY src ./src
+RUN pnpm run build
+ENV HOST=0.0.0.0
+EXPOSE 8000
+CMD ["node", "dist/main.js"]

package/templates/react-nest-shadcn/backend/eslint.config.mjs

@@ -0,0 +1,3 @@
+import js from '@eslint/js';
+import ts from 'typescript-eslint';
+export default ts.config(js.configs.recommended,...ts.configs.recommended,{languageOptions:{parserOptions:{tsconfigRootDir:import.meta.dirname}},ignores:['dist/**','node_modules/**']});

package/templates/react-nest-shadcn/backend/jest.config.cjs

@@ -0,0 +1 @@
+module.exports={testEnvironment:'node',extensionsToTreatAsEsm:['.ts'],transform:{'^.+\\.tsx?$':['ts-jest',{useESM:true,tsconfig:{module:'ES2022',moduleResolution:'node'}}]},testMatch:['**/test/**/*.test.ts'],reporters:['default',['jest-junit',{outputDirectory:process.env.SCAFFOLD_REPORT_DIR||'../reports',outputName:'native.xml'}]]};

package/templates/react-nest-shadcn/backend/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "__NAME_EN__-api",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src test scripts",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "@nestjs/common": "12.2.0",
+    "@nestjs/core": "12.2.0",
+    "@nestjs/platform-express": "12.2.0",
+    "@nestjs/jwt": "12.0.3",
+    "@nestjs/swagger": "12.0.2",
+    "@prisma/client": "6.19.3",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "prisma": "6.19.3",
+    "tsx": "4.23.15",
+    "@types/node": "24.19.2",
+    "@types/express": "5.0.6",
+    "@nestjs/testing": "12.2.0",
+    "jest": "29.7.0",
+    "ts-jest": "29.4.15",
+    "@types/jest": "29.5.14",
+    "supertest": "7.3.1",
+    "@types/supertest": "7.2.1",
+    "jest-junit": "16.0.0",
+    "eslint": "9.39.5",
+    "@eslint/js": "9.39.5",
+    "typescript-eslint": "8.71.2"
+  }
+}