@cherishxn/agent-scaffold 1.0.0 → 1.1.0

package/templates/react-fastapi-shadcn/playwright.config.ts

@@ -1,3 +1,3 @@
 import { defineConfig } from '@playwright/test';
 const port=process.env.WEB_PORT||'5173';
-export default defineConfig({testDir:'./tests',outputDir:process.env.SCAFFOLD_REPORT_DIR?process.env.SCAFFOLD_REPORT_DIR+'/playwright':'test-results',workers:1,retries:0,timeout:30000,reporter:[['line'],['junit',{outputFile:process.env.PLAYWRIGHT_JUNIT_OUTPUT_FILE||'reports/playwright.xml'}]],use:{baseURL:`http://127.0.0.1:${port}`,headless:true,trace:'off',screenshot:'off'},webServer:{command:'node scripts/project.mjs serve',url:`http://127.0.0.1:${port}/api/health`,reuseExistingServer:false,timeout:120000,stdout:'ignore',stderr:'pipe'},expect:{timeout:10000}});
+export default defineConfig({testDir:'./tests',outputDir:process.env.SCAFFOLD_REPORT_DIR?process.env.SCAFFOLD_REPORT_DIR+'/playwright':'test-results',workers:1,retries:0,timeout:30000,reporter:[['line'],['junit',{outputFile:process.env.PLAYWRIGHT_JUNIT_OUTPUT_FILE||'reports/playwright.xml'}]],use:{baseURL:`http://127.0.0.1:${port}`,headless:true,trace:'off',screenshot:'off'},webServer:{command:'node scripts/project.mjs serve',url:`http://127.0.0.1:${port}/api/health`,reuseExistingServer:false,timeout:120000,stdout:'pipe',stderr:'pipe'},expect:{timeout:10000}});

package/templates/react-fastapi-shadcn/scripts/api-check.mjs

@@ -0,0 +1,18 @@
+import {mkdtemp,readFile,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join,resolve} from 'node:path';
+import {spawnSync} from 'node:child_process';
+
+// Generate outside the workspace: validation never repairs or overwrites source.
+const directory=await mkdtemp(join(tmpdir(),'scaffold-api-check-'));
+try{
+ const target=join(directory,'api.d.ts');
+ const result=spawnSync(process.execPath,['node_modules/openapi-typescript/bin/cli.js','docs/openapi.json','-o',target],{cwd:resolve('.'),encoding:'utf8'});
+ if(result.status!==0)throw new Error('API_CONTRACT_INVALID: OpenAPI generation failed. '+result.stderr);
+ const expected=await readFile(target,'utf8'),actual=await readFile('docs/api.d.ts','utf8');
+ if(expected!==actual){
+  const a=actual.split('\n'),e=expected.split('\n');let line=0;while(line<Math.max(a.length,e.length)&&a[line]===e[line])line++;
+  throw new Error(`API_CONTRACT_DRIFT: docs/api.d.ts differs from docs/openapi.json at line ${line+1}. Run npm run api:generate after reviewing the intended contract.`);
+ }
+ console.log('API contract and generated types match.');
+}finally{await rm(directory,{recursive:true,force:true});}

package/templates/react-fastapi-shadcn/scripts/api-contract.mjs

@@ -0,0 +1,46 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+export function responseValidator(document){
+ const ajv=new Ajv({strict:false,allErrors:true});addFormats(ajv);
+ ajv.addSchema(document,'contract');
+ const operations=[];
+ function dereference(value,pointer){
+  const seen=new Set();
+  while(value?.$ref){
+   const ref=value.$ref;
+   if(!ref.startsWith('#/')||seen.has(ref))throw new Error('API_CONTRACT_INVALID: unsupported or circular response reference');
+   seen.add(ref);pointer=ref.slice(1);value=pointer.slice(1).split('/').map(s=>s.replaceAll('~1','/').replaceAll('~0','~')).reduce((at,key)=>at?.[key],document);
+   if(!value)throw new Error('API_CONTRACT_INVALID: unresolved response reference');
+  }
+  return {value,pointer};
+ }
+ const pointer=value=>value.replaceAll('~','~0').replaceAll('/','~1');
+ for(const [path,item] of Object.entries(document.paths))for(const [method,operation] of Object.entries(item)){
+  if(!['get','post','put','delete','patch','head','options'].includes(method))continue;
+  const statuses=new Map();
+  for(const [status,response] of Object.entries(operation.responses)){
+   const resolved=dereference(response,`/paths/${pointer(path)}/${method}/responses/${pointer(status)}`);
+   const content=resolved.value.content?.['application/json'];
+   if(resolved.value.content&&!content)throw new Error('API_CONTRACT_INVALID: only JSON response schemas are supported');
+   const validate=content?ajv.compile({$ref:`contract#${resolved.pointer}/content/application~1json/schema`}):null;
+   statuses.set(status,validate);
+  }
+  operations.push({path,parts:path.split('/'),method,statuses});
+ }
+ return (method,url,status,headers,body)=>{
+  const parts=new URL(url,'http://contract.invalid').pathname.split('/');
+  const operation=operations.find(o=>o.method===method.toLowerCase()&&o.parts.length===parts.length&&o.parts.every((part,i)=>part===parts[i]||/^\{[^}]+\}$/.test(part)&&parts[i]!==''));
+  const label=`API_RESPONSE_INVALID: ${method.toUpperCase()} ${operation?.path??'unlisted operation'} status ${status}`;
+  if(!operation)throw new Error(label+' is absent from docs/openapi.json');
+  const key=operation.statuses.has(String(status))?String(status):operation.statuses.has(`${Math.floor(status/100)}XX`)?`${Math.floor(status/100)}XX`:'default';
+  if(!operation.statuses.has(key))throw new Error(label+' is not declared');
+  const validate=operation.statuses.get(key);
+  if(status===204&&body.length)throw new Error(label+' must have an empty body');
+  if(validate){
+   if(!/^application\/json(?:;|$)/i.test(headers['content-type']??''))throw new Error(label+' requires application/json');
+   let data;try{data=JSON.parse(body);}catch{throw new Error(label+' is not valid JSON');}
+   if(!validate(data))throw new Error(label+' '+validate.errors.map(e=>`${e.instancePath||'/'} ${e.keyword}${e.params.missingProperty?' '+e.params.missingProperty:''}`).join('; '));
+  }
+ };
+}

package/templates/react-fastapi-shadcn/scripts/project.mjs

@@ -88,9 +88,10 @@ async function setup() {
 }
 const command=process.argv[2];
 try {
-  mkdirSync('reports',{recursive:true});
+  if(command!=='api:check')mkdirSync('reports',{recursive:true});
   if(command==='install')await install();
   else if(command==='setup'){await install();await setup();}
+  else if(command==='check'){for(const task of ['api:check','typecheck','lint','build'])await run('node',['scripts/project.mjs',task]);}
   else if(command==='dev:setup')await setup();
   else if(command==='migrate')await migrate();
   else if(command==='seed')await seed();
@@ -113,6 +114,7 @@ try {
     else if(stack==='react-nest')await run('pnpm',['run','test'],'backend');
     else await run('pnpm',['run','test'],'web');
   } else if(command==='test:api'||command==='test:e2e')await run('npx',['--no-install','playwright','test',command==='test:api'?'tests/contract.spec.ts':'tests/ui.spec.ts']);
+  else if(command==='api:check')await run('node',['scripts/api-check.mjs']);
   else if(command==='api:generate')await run('npx',['--no-install','openapi-typescript','docs/openapi.json','-o','docs/api.d.ts']);
-  else throw new Error('Use setup, install, dev:setup, dev, build, typecheck, lint, migrate, seed, test:native, test:api, test:e2e, api:generate.');
+  else throw new Error('Use setup, install, dev:setup, dev, check, build, typecheck, lint, migrate, seed, test:native, test:api, test:e2e, api:check, api:generate.');
 } catch(e) {stop();console.error(e instanceof Error?e.message:'Project command failed');process.exitCode=process.exitCode||1;}

package/templates/react-fastapi-shadcn/tests/contract-client.ts

@@ -0,0 +1,20 @@
+import {request as raw,type APIRequestContext,type APIResponse} from '@playwright/test';
+import document from '../docs/openapi.json' with {type:'json'};
+import {responseValidator} from '../scripts/api-contract.mjs';
+const validate=responseValidator(document);
+export const requests={
+ async newContext(options?:Parameters<typeof raw.newContext>[0]):Promise<APIRequestContext>{
+  const context=await raw.newContext(options);
+  return new Proxy(context,{
+   get(target,key){
+    const value=Reflect.get(target,key,target);
+    if(['get','post','put','delete','patch','head'].includes(String(key)))return async(...args:unknown[])=>{
+     const response:APIResponse=await value.apply(target,args);
+     validate(String(key),response.url(),response.status(),response.headers(),(await response.body()).toString('utf8'));
+     return response;
+    };
+    return typeof value==='function'?value.bind(target):value;
+   }
+  });
+ }
+};

package/templates/react-fastapi-shadcn/tests/contract.spec.ts

@@ -1,14 +1,16 @@
-import {test,expect,request as requests,type APIRequestContext} from '@playwright/test';
+import {requests} from './contract-client';
+import {test,expect,type APIRequestContext} from '@playwright/test';
 import project from '../project.json' with {type:'json'};
 const baseURL=`http://127.0.0.1:${process.env.WEB_PORT||5173}`;
 const origin=process.env.APP_ORIGIN||baseURL;
 async function login(email:string){const context=await requests.newContext({baseURL,extraHTTPHeaders:{Origin:origin}});const res=await context.post('/api/auth/login',{data:{email,password:process.env.SEED_PASSWORD}});expect(res.status()).toBe(200);const auth=await res.json();if(auth.token)await context.dispose();const client:APIRequestContext=auth.token?await requests.newContext({baseURL,extraHTTPHeaders:{Origin:origin,Authorization:`Bearer ${auth.token}`}}):context;return {client,auth};}
 test('HTTP identity, persistent CRUD, pagination and owner isolation',async()=>{
+ const health=await requests.newContext({baseURL});expect((await health.get('/api/health')).status()).toBe(200);await health.dispose();
  const anonymous=await requests.newContext({baseURL,extraHTTPHeaders:{Origin:origin}});
  expect((await anonymous.get('/api/records')).status()).toBe(401);
  expect((await anonymous.post('/api/records',{data:{title:'x',content:''}})).status()).toBe(401);
  expect((await anonymous.post('/api/auth/login',{data:{email:process.env.SEED_A_EMAIL,password:'invalid-password'}})).status()).toBe(401);
- const {client:a}=await login(process.env.SEED_A_EMAIL!);const {client:b}=await login(process.env.SEED_B_EMAIL!);
+ const {client:a}=await login(process.env.SEED_A_EMAIL!);const {client:b}=await login(process.env.SEED_B_EMAIL!);expect((await a.get('/api/auth/me')).status()).toBe(200);
  const body=process.env.TEST_BODY_MARKER||'synthetic-content';
  const res=await a.post('/api/records',{data:{title:'  Contract record  ',content:body}});expect(res.status()).toBe(201);const row=await res.json();const path=`/api/records/${row.id}`;
  expect(row.title).toBe('Contract record');expect((await a.get(path)).status()).toBe(200);

package/templates/react-nest-antd/.agents/skills/project-work/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: project-work
-description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
 ---
 
-Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
-
-For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/react-nest-antd/.claude/skills/project-work/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: project-work
-description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
 ---
 
-Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
-
-For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/react-nest-antd/.grok/skills/project-work/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: project-work
-description: Implement or fix this generated project using its documented commands and verify the requested behavior.
+description: Implement features, fix defects, or change API/data/UI behavior in this generated project, using its task map and real validation commands.
 ---
 
-Read AGENTS.md, docs/PROJECT.md and README.md. Check Git changes and the current request. Implement only the requested behavior. Run the relevant project checks, inspect the diff, and report files, commands and actual results. A failed or unrun check is not a pass. Follow the task's existing authorization for external writes.
-
-For UI work, read root DESIGN.md before editing. Follow its source/sync workflow, use the bundled design-contract Skill, run `npm run design:check` and `npm run design:verify`, and verify affected business flows in the browser.
+1. Read AGENTS.md, README.md and the task map in docs/PROJECT.md. Check project.json for the selected stack and inspect the current Git changes.
+2. State the requested observable behavior and failure cases. Follow the task map to the implementation and callers; use existing interfaces and test conventions.
+3. Implement the requested change. API or data changes include the contract, a new migration when needed, and affected authorization tests. Run `npm run api:generate` after changing OpenAPI; `npm run api:check` detects stale types without modifying source, and HTTP tests validate response schemas. UI changes first read DESIGN.md and use design-contract for source, sync and browser checks.
+4. Run the affected checks, then `npm run check` for type/lint/build feedback. For API, data, auth or complete delivery, follow README's isolated `verify` command; UI work also needs design:check and design:verify. Check both exit status and the report's overallStatus/validity.
+5. Inspect the final diff. Report the behavior, actual commands/results and remaining limits. A quick check, doctor, historical report or generated file is not a current business pass. Keep credentials and raw runtime data local; apply the user's existing authorization to external writes.

package/templates/react-nest-antd/AGENTS.md

@@ -6,6 +6,6 @@
 
 仅修改任务范围，保留其他改动。秘密只放本地环境，不提交或打印；模板 verify 使用隔离数据库。推送、发布和外部写入依任务授权执行。
 
-需要开发指引时使用 project-work Skill；未自动发现时按以上规则和 README 执行。
+实现功能、修复缺陷时使用 project-work Skill；先按 docs/PROJECT.md 的任务表定位实现、迁移和测试入口。未自动发现 Skill 时按该表和 README 执行。
 
 修改 UI 前先读根目录 DESIGN.md。使用 design-contract Skill；设计源、同步命令和一致性检查以该文件为准。交付前运行 design:check 与 design:verify，报告实际覆盖范围。

package/templates/react-nest-antd/README.md

@@ -15,14 +15,23 @@ npm run dev
 
 ## 验证
 
-安装依赖后，由已安装的 CLI 执行：
+安装前可只检查工具；doctor 不会安装依赖或启动服务：
 
 ```bash
-scaffold doctor --dir . --json
-scaffold verify --dir . --profile baseline --json
-scaffold report --dir . --json
+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
@@ -35,7 +44,7 @@ node scripts/project.mjs test:e2e
 node scripts/project.mjs api:generate
 ```
 
-接口：docs/openapi.json；结构：docs/PROJECT.md；规则：AGENTS.md。按需运行 api:generate 更新 TypeScript 客户端类型，不在 verify 中修改源码。
+接口：docs/openapi.json；结构：docs/PROJECT.md；规则：AGENTS.md。修改契约后运行 npm run api:generate 更新 TypeScript 类型。npm run api:check 在临时目录重新生成并只读比较，check/verify 自动执行；test:api 同时按 OpenAPI 检查真实响应状态、必填字段和类型。验证不会自动修改源码。
 
 ## 认证边界
 

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

@@ -12,3 +12,7 @@ Templates are maintained derivatives, not unmodified upstream distributions. Exa
 | 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-nest-antd/docs/PROJECT.md

@@ -7,3 +7,26 @@
 project.json 标识技术栈和 UI；web/ 是界面或 Next 全栈应用；独立后端位于 backend/。scripts/project.mjs 提供实际安装、开发、测试、构建命令。数据库结构以迁移为准，接口见 docs/openapi.json 和生成的 docs/api.d.ts。
 
 后续需求在团队已有权威来源或本文记录，不要求接入特定任务平台。名称和简介来自创建输入，修改 project.json 可更新界面展示。
+
+
+## 从任务找到改动位置
+
+先核对 project.json 的实际技术栈；以下路径只描述本项目。读取命中的实现和调用方后再修改，不将基础示例自动扩展成用户未要求的业务。
+
+| 任务 | 入口 | 改动约束 |
+| --- | --- | --- |
+| 页面交互 | `web/src/App.tsx`、`web/src/workspace-model.ts` | 业务状态放模型，页面负责绑定；身份结束时清空用户数据。 |
+| 设计与组件 | `DESIGN.md`、`design/`、`web/src/ui.tsx` | 先改共享设计意图，再改适配器；按 design-contract 执行同步与浏览器检查。 |
+| API 与身份隔离 | `backend/src/app.module.ts`、`backend/src/password.ts` | 查询始终限定当前用户；JWT 保留在浏览器内存。 |
+| 模型与迁移 | `backend/prisma/schema.prisma`、`backend/prisma/migrations/` | 新增 Prisma 迁移，保留已经运行过的迁移。 |
+| 后端回归 | `backend/test/api.test.ts` | 用真实 PostgreSQL 验证数据和越权行为。 |
+| HTTP 契约 | `docs/openapi.json`、`docs/api.d.ts`、`tests/contract.spec.ts` | 修改输入输出时同步契约与真实 HTTP 回归；用 api:generate 生成类型。 |
+| 用户流程 | `tests/ui.spec.ts` | 覆盖真实操作、持久化和失败反馈，测试仅使用专用数据。 |
+| 启动与依赖 | `package.json`、`scripts/project.mjs`、`compose.yaml` | 使用锁文件和项目命令；配置、账号及运行报告留在本地。 |
+
+## 修改与验证
+
+1. 将当前需求转成可观察行为与失败场景，复用现有契约和测试入口。
+2. 做能贯通当前需求的最小改动，先运行相关检查；`npm run check` 按类型、Lint、构建快速失败。
+3. API、数据、认证或完整交付使用 README 中的 `verify`，它创建隔离数据库执行原生/API/浏览器检查。UI 还需运行设计契约检查。
+4. 查看差异并报告实际结果。类型或构建通过不等于业务通过；历史报告为 STALE 时按当前内容复验。

package/templates/react-nest-antd/docs/api.d.ts

@@ -27,7 +27,7 @@ export interface paths {
                     };
                     content: {
                         "application/json": {
-                            status?: string;
+                            status: string;
                         };
                     };
                 };
@@ -73,13 +73,13 @@ export interface paths {
                     };
                     content: {
                         "application/json": {
-                            user?: {
+                            user: {
                                 id: string;
                                 email: string;
                             };
                             token?: string;
                             /** @enum {unknown} */
-                            mode?: "jwt" | "session";
+                            mode: "jwt" | "session";
                         };
                     };
                 };
@@ -135,7 +135,7 @@ export interface paths {
                     };
                     content: {
                         "application/json": {
-                            user?: {
+                            user: {
                                 id: string;
                                 email: string;
                             };
@@ -205,6 +205,13 @@ export interface paths {
                     };
                     content?: never;
                 };
+                /** @description Cross-origin session write rejected */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
                 /** @description Record absent or owned by another user */
                 404: {
                     headers: {
@@ -316,6 +323,13 @@ export interface paths {
                     };
                     content?: never;
                 };
+                /** @description Cross-origin session write rejected */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
                 /** @description Record absent or owned by another user */
                 404: {
                     headers: {
@@ -424,6 +438,13 @@ export interface paths {
                     };
                     content?: never;
                 };
+                /** @description Cross-origin session write rejected */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
                 /** @description Record absent or owned by another user */
                 404: {
                     headers: {
@@ -466,6 +487,13 @@ export interface paths {
                     };
                     content?: never;
                 };
+                /** @description Cross-origin session write rejected */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
                 /** @description Record absent or owned by another user */
                 404: {
                     headers: {

package/templates/react-nest-antd/docs/openapi.json

@@ -19,7 +19,10 @@
                     "status": {
                       "type": "string"
                     }
-                  }
+                  },
+                  "required": [
+                    "status"
+                  ]
                 }
               }
             }
@@ -85,7 +88,11 @@
                         "session"
                       ]
                     }
-                  }
+                  },
+                  "required": [
+                    "user",
+                    "mode"
+                  ]
                 }
               }
             }
@@ -127,7 +134,10 @@
                         }
                       }
                     }
-                  }
+                  },
+                  "required": [
+                    "user"
+                  ]
                 }
               }
             }
@@ -158,6 +168,9 @@
           },
           "422": {
             "description": "Invalid input or protected field"
+          },
+          "403": {
+            "description": "Cross-origin session write rejected"
           }
         }
       }
@@ -277,6 +290,9 @@
           },
           "422": {
             "description": "Invalid input or protected field"
+          },
+          "403": {
+            "description": "Cross-origin session write rejected"
           }
         }
       }
@@ -362,6 +378,9 @@
           },
           "422": {
             "description": "Invalid input or protected field"
+          },
+          "403": {
+            "description": "Cross-origin session write rejected"
           }
         }
       },
@@ -378,6 +397,9 @@
           },
           "422": {
             "description": "Invalid input or protected field"
+          },
+          "403": {
+            "description": "Cross-origin session write rejected"
           }
         }
       }

package/templates/react-nest-antd/package-lock.json

@@ -9,6 +9,8 @@
       "version": "1.0.0",
       "devDependencies": {
         "@playwright/test": "1.64.1",
+        "ajv": "8.20.0",
+        "ajv-formats": "3.0.1",
         "openapi-typescript": "7.13.0"
       }
     },
@@ -109,6 +111,41 @@
         "node": ">= 14"
       }
     },
+    "node_modules/ajv": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz",
+      "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ajv-formats": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz",
+      "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependencies": {
+        "ajv": "^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "ajv": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/ansi-colors": {
       "version": "4.1.3",
       "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.3.tgz",
@@ -182,6 +219,23 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-uri": {
+      "version": "3.1.9",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.9.tgz",
+      "integrity": "sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
     "node_modules/https-proxy-agent": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",

package/templates/react-nest-antd/package.json

@@ -4,6 +4,9 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "api:check": "node scripts/project.mjs api:check",
+    "api:generate": "node scripts/project.mjs api:generate",
+    "check": "node scripts/project.mjs check",
     "setup": "node scripts/project.mjs setup",
     "design:verify": "node scripts/design-verify.mjs",
     "design:sync": "node scripts/design.mjs sync",
@@ -15,6 +18,8 @@
     "test:e2e": "node scripts/project.mjs test:e2e"
   },
   "devDependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
     "@playwright/test": "1.64.1",
     "openapi-typescript": "7.13.0"
   }

package/templates/react-nest-antd/playwright.config.ts

@@ -1,3 +1,3 @@
 import { defineConfig } from '@playwright/test';
 const port=process.env.WEB_PORT||'5173';
-export default defineConfig({testDir:'./tests',outputDir:process.env.SCAFFOLD_REPORT_DIR?process.env.SCAFFOLD_REPORT_DIR+'/playwright':'test-results',workers:1,retries:0,timeout:30000,reporter:[['line'],['junit',{outputFile:process.env.PLAYWRIGHT_JUNIT_OUTPUT_FILE||'reports/playwright.xml'}]],use:{baseURL:`http://127.0.0.1:${port}`,headless:true,trace:'off',screenshot:'off'},webServer:{command:'node scripts/project.mjs serve',url:`http://127.0.0.1:${port}/api/health`,reuseExistingServer:false,timeout:120000,stdout:'ignore',stderr:'pipe'},expect:{timeout:10000}});
+export default defineConfig({testDir:'./tests',outputDir:process.env.SCAFFOLD_REPORT_DIR?process.env.SCAFFOLD_REPORT_DIR+'/playwright':'test-results',workers:1,retries:0,timeout:30000,reporter:[['line'],['junit',{outputFile:process.env.PLAYWRIGHT_JUNIT_OUTPUT_FILE||'reports/playwright.xml'}]],use:{baseURL:`http://127.0.0.1:${port}`,headless:true,trace:'off',screenshot:'off'},webServer:{command:'node scripts/project.mjs serve',url:`http://127.0.0.1:${port}/api/health`,reuseExistingServer:false,timeout:120000,stdout:'pipe',stderr:'pipe'},expect:{timeout:10000}});

package/templates/react-nest-antd/scripts/api-check.mjs

@@ -0,0 +1,18 @@
+import {mkdtemp,readFile,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join,resolve} from 'node:path';
+import {spawnSync} from 'node:child_process';
+
+// Generate outside the workspace: validation never repairs or overwrites source.
+const directory=await mkdtemp(join(tmpdir(),'scaffold-api-check-'));
+try{
+ const target=join(directory,'api.d.ts');
+ const result=spawnSync(process.execPath,['node_modules/openapi-typescript/bin/cli.js','docs/openapi.json','-o',target],{cwd:resolve('.'),encoding:'utf8'});
+ if(result.status!==0)throw new Error('API_CONTRACT_INVALID: OpenAPI generation failed. '+result.stderr);
+ const expected=await readFile(target,'utf8'),actual=await readFile('docs/api.d.ts','utf8');
+ if(expected!==actual){
+  const a=actual.split('\n'),e=expected.split('\n');let line=0;while(line<Math.max(a.length,e.length)&&a[line]===e[line])line++;
+  throw new Error(`API_CONTRACT_DRIFT: docs/api.d.ts differs from docs/openapi.json at line ${line+1}. Run npm run api:generate after reviewing the intended contract.`);
+ }
+ console.log('API contract and generated types match.');
+}finally{await rm(directory,{recursive:true,force:true});}

package/templates/react-nest-antd/scripts/api-contract.mjs

@@ -0,0 +1,46 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+
+export function responseValidator(document){
+ const ajv=new Ajv({strict:false,allErrors:true});addFormats(ajv);
+ ajv.addSchema(document,'contract');
+ const operations=[];
+ function dereference(value,pointer){
+  const seen=new Set();
+  while(value?.$ref){
+   const ref=value.$ref;
+   if(!ref.startsWith('#/')||seen.has(ref))throw new Error('API_CONTRACT_INVALID: unsupported or circular response reference');
+   seen.add(ref);pointer=ref.slice(1);value=pointer.slice(1).split('/').map(s=>s.replaceAll('~1','/').replaceAll('~0','~')).reduce((at,key)=>at?.[key],document);
+   if(!value)throw new Error('API_CONTRACT_INVALID: unresolved response reference');
+  }
+  return {value,pointer};
+ }
+ const pointer=value=>value.replaceAll('~','~0').replaceAll('/','~1');
+ for(const [path,item] of Object.entries(document.paths))for(const [method,operation] of Object.entries(item)){
+  if(!['get','post','put','delete','patch','head','options'].includes(method))continue;
+  const statuses=new Map();
+  for(const [status,response] of Object.entries(operation.responses)){
+   const resolved=dereference(response,`/paths/${pointer(path)}/${method}/responses/${pointer(status)}`);
+   const content=resolved.value.content?.['application/json'];
+   if(resolved.value.content&&!content)throw new Error('API_CONTRACT_INVALID: only JSON response schemas are supported');
+   const validate=content?ajv.compile({$ref:`contract#${resolved.pointer}/content/application~1json/schema`}):null;
+   statuses.set(status,validate);
+  }
+  operations.push({path,parts:path.split('/'),method,statuses});
+ }
+ return (method,url,status,headers,body)=>{
+  const parts=new URL(url,'http://contract.invalid').pathname.split('/');
+  const operation=operations.find(o=>o.method===method.toLowerCase()&&o.parts.length===parts.length&&o.parts.every((part,i)=>part===parts[i]||/^\{[^}]+\}$/.test(part)&&parts[i]!==''));
+  const label=`API_RESPONSE_INVALID: ${method.toUpperCase()} ${operation?.path??'unlisted operation'} status ${status}`;
+  if(!operation)throw new Error(label+' is absent from docs/openapi.json');
+  const key=operation.statuses.has(String(status))?String(status):operation.statuses.has(`${Math.floor(status/100)}XX`)?`${Math.floor(status/100)}XX`:'default';
+  if(!operation.statuses.has(key))throw new Error(label+' is not declared');
+  const validate=operation.statuses.get(key);
+  if(status===204&&body.length)throw new Error(label+' must have an empty body');
+  if(validate){
+   if(!/^application\/json(?:;|$)/i.test(headers['content-type']??''))throw new Error(label+' requires application/json');
+   let data;try{data=JSON.parse(body);}catch{throw new Error(label+' is not valid JSON');}
+   if(!validate(data))throw new Error(label+' '+validate.errors.map(e=>`${e.instancePath||'/'} ${e.keyword}${e.params.missingProperty?' '+e.params.missingProperty:''}`).join('; '));
+  }
+ };
+}