@cherishxn/agent-scaffold 0.0.0-stage → 1.0.0

package/templates/react-fastapi-shadcn/project.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "nameZh": "模板工作空间",
+  "nameEn": "template-project",
+  "description": "模板验证",
+  "template": "react-fastapi",
+  "ui": "shadcn"
+}

package/templates/react-fastapi-shadcn/scripts/design-coverage.mjs

@@ -0,0 +1,20 @@
+// Each entry corresponds to a concrete branch in tests/design/harness.tsx.
+const supported={
+ button:{variants:['primary','secondary','danger'],states:['default','hover','active','focus','disabled','loading']},
+ input:{variants:['text','email','password'],states:['default','hover','focus','disabled','invalid','readonly']},
+ textarea:{variants:['default'],states:['default','hover','focus','disabled','invalid','readonly']},
+ alert:{variants:['error','success'],states:['default']},
+ badge:{variants:['default'],states:['default']},panel:{variants:['default'],states:['default']},field:{variants:['default'],states:['default']}
+};
+const scenarios=['checking','login','login-error','login-busy','workspace-empty','workspace-loading','workspace-records','editor-new','editor-existing','editor-error'];
+export function validateFixtureCoverage(design){
+ const acceptance=design.widgets.acceptance;
+ if(!Array.isArray(acceptance.viewports)||!acceptance.viewports.length||acceptance.viewports.some(view=>!Number.isInteger(view.width)||!Number.isInteger(view.height)||view.width<1||view.height<1))throw new Error('Design verification requires nonempty valid viewports');
+ if(acceptance.positionTolerance!==0.6)throw new Error('Position tolerance must remain 0.6 CSS px');
+ if(!Object.keys(design.widgets.widgets).length)throw new Error('No widget coverage');
+ for(const [name,spec] of Object.entries(design.widgets.widgets)){
+  if(!supported[name])throw new Error('Unimplemented widget fixture: '+name);
+  for(const key of ['variants','states'])if(!Array.isArray(spec[key])||!spec[key].length||spec[key].some(value=>!supported[name][key].includes(value)))throw new Error('Unimplemented fixture '+name+'.'+key);
+ }
+ if(!Array.isArray(design.structure.scenarios)||!design.structure.scenarios.length||design.structure.scenarios.some(value=>!scenarios.includes(value)))throw new Error('Unimplemented page scenario');
+}

package/templates/react-fastapi-shadcn/scripts/design-next-cleanup.mjs

@@ -0,0 +1,13 @@
+// Remove only paths owned by this fixture run; preserve concurrent source edits.
+export function cleanNextFixtureConfig(file,current,original,dist) {
+ if(file==='tsconfig.json'){
+  const value=JSON.parse(current),before=JSON.parse(original);
+  if(Array.isArray(value.include))value.include=value.include.filter(path=>path!==`${dist}/types/**/*.ts`&&path!==`${dist}/dev/types/**/*.ts`);
+  return JSON.stringify(value)===JSON.stringify(before)?original:JSON.stringify(value,null,2)+'\n';
+ }
+ return current.split('\n').map(line=>{
+  if(!line.startsWith(`import "./${dist}/`))return line;
+  const suffix=line.slice(line.lastIndexOf('/types/'));
+  return original.split('\n').find(old=>old.startsWith('import ')&&old.endsWith(suffix))||'';
+ }).join('\n');
+}

package/templates/react-fastapi-shadcn/scripts/design-verify.mjs

@@ -0,0 +1,154 @@
+import {spawn} from 'node:child_process';
+import {createServer} from 'node:net';
+import {createRequire} from 'node:module';
+import {mkdir,readFile,writeFile,rm} from 'node:fs/promises';
+import {dirname,resolve,join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash,randomUUID} from 'node:crypto';
+import {cleanNextFixtureConfig} from './design-next-cleanup.mjs';
+import {syncDesign} from './design.mjs';
+import {validateFixtureCoverage} from './design-coverage.mjs';
+const root=resolve(dirname(fileURLToPath(import.meta.url)),'..');
+const require=createRequire(join(root,'package.json'));
+const {chromium}=require('@playwright/test');
+const project=JSON.parse(await readFile(join(root,'project.json'),'utf8'));
+const design=JSON.parse(await readFile(join(root,'web/src/design-runtime.json'),'utf8'));
+const output=join(root,'reports/design-check');await mkdir(output,{recursive:true});
+const nonce=randomUUID().slice(0,8),next=project.template==='next-fullstack';
+const nextDist=`.next/scaffold-design-cache-${nonce}`,nextFiles=new Map();
+const harness=join(root,`web/src/scaffold-design-check-${nonce}.tsx`);
+const entry=next?join(root,`web/app/scaffold-design-check-${nonce}/page.tsx`):join(root,`web/scaffold-design-check-${nonce}.html`);
+let server,browser,serverLog='',interrupted=false,createdHarness=false,createdEntry=false,createdDirectory=false;
+const signals=()=>{interrupted=true;server?.kill('SIGTERM');};
+process.once('SIGINT',signals);process.once('SIGTERM',signals);
+const report={schemaVersion:1,status:'FAIL',template:project.template,ui:project.ui,platform:process.platform,startedAt:new Date().toISOString(),cases:[],failures:[]};
+function compare(expected,actual,path='') {
+ if(typeof expected==='number'&&typeof actual==='number')return Math.abs(expected-actual)<=design.widgets.acceptance.positionTolerance?[]:[`${path}: ${expected} != ${actual}`];
+ if(expected===null||actual===null||typeof expected!=='object'||typeof actual!=='object')return expected===actual?[]:[`${path}: ${JSON.stringify(expected)} != ${JSON.stringify(actual)}`];
+ const keys=new Set([...Object.keys(expected),...Object.keys(actual)]);
+ return [...keys].flatMap(key=>compare(expected[key],actual[key],path?path+'.'+key:key));
+}
+async function collect(page){return page.evaluate(()=>{
+ const selectors='[data-widget],[data-part],[data-region],h1,h2,h3,p,label,button,input,textarea,a';
+ const elements=[...document.querySelectorAll(selectors)].filter(el=>el.getClientRects().length&&getComputedStyle(el).display!=='none');
+ const styles=['color','backgroundColor','borderTopColor','borderRightColor','borderBottomColor','borderLeftColor','borderTopLeftRadius','borderTopRightRadius','borderBottomLeftRadius','borderBottomRightRadius','borderTopWidth','borderRightWidth','borderBottomWidth','borderLeftWidth','fontFamily','fontSize','fontWeight','lineHeight','letterSpacing','paddingTop','paddingRight','paddingBottom','paddingLeft','opacity','outlineColor','outlineWidth','outlineStyle','outlineOffset','boxShadow'];
+ const box=rect=>({x:rect.x,y:rect.y,width:rect.width,height:rect.height});
+ return elements.map(el=>{
+  const css=getComputedStyle(el),walker=document.createTreeWalker(el,NodeFilter.SHOW_TEXT),text=[];
+  let node;while((node=walker.nextNode()))if(node.textContent.trim()){const range=document.createRange();range.selectNodeContents(node);text.push({value:node.textContent,box:box(range.getBoundingClientRect())});}
+  return {role:el.getAttribute('data-widget')||el.getAttribute('data-part')||el.getAttribute('data-region')||el.tagName.toLowerCase(),box:box(el.getBoundingClientRect()),styles:Object.fromEntries(styles.map(name=>[name,css[name]])),text,icon:el.tagName.toLowerCase()==='svg'?{viewBox:el.getAttribute('viewBox'),stroke:el.getAttribute('stroke'),strokeWidth:el.getAttribute('stroke-width'),linecap:el.getAttribute('stroke-linecap'),linejoin:el.getAttribute('stroke-linejoin'),paths:[...el.querySelectorAll('path')].map(path=>path.getAttribute('d'))}:null};
+ });
+});}
+async function checkSpecification(page){
+ const failures=await page.evaluate(design=>{
+  const failures=[],colors=design.tokens.colors;
+  const normal=(property,value)=>{const probe=document.createElement('span');probe.style.borderStyle='solid';probe.style[property]=String(value);document.body.append(probe);const result=getComputedStyle(probe)[property];probe.remove();return result;};
+  for(const element of document.querySelectorAll('[data-widget]')){
+   const name=element.getAttribute('data-widget'),spec=design.widgets.widgets[name];
+   if(!spec){failures.push('Undeclared rendered widget '+name);continue;}
+   for(const part of spec.parts)if(part!=='root'&&!element.querySelector(`[data-part="${part}"]`))failures.push(name+' missing part '+part);
+   const target=name==='field'?element.querySelector('[data-part="label"]'):element,css=getComputedStyle(target);
+   const map={height:'height',fontSize:'fontSize',fontWeight:'fontWeight',lineHeight:'lineHeight',radius:'borderTopLeftRadius',borderWidth:'borderTopWidth',paddingX:'paddingLeft',paddingY:'paddingTop'};
+   for(const [key,property] of Object.entries(map))if(spec.styles[key]!==undefined){const expected=normal(property,spec.styles[key]);if(css[property]!==expected)failures.push(name+'.'+property+': expected '+expected+', got '+css[property]);}
+   const assertColor=(property,value)=>{const expected=normal(property,value);if(css[property]!==expected)failures.push(name+'.'+property+': expected '+expected+', got '+css[property]);};
+   if(name==='button'){
+    const variant=element.getAttribute('data-variant'),hover=element.matches(':hover'),active=element.matches(':active');
+    const key=variant==='primary'?(active?'primary-active':hover?'primary-hover':'primary'):variant==='secondary'?(hover||active?'secondary-hover':'control-background'):(hover||active?'danger-hover':'danger-background');
+    assertColor('backgroundColor',colors[key]);assertColor('color',colors[variant+'-text']);
+   }
+   if(name==='input'||name==='textarea'){assertColor('backgroundColor',colors['control-background']);assertColor('color',colors.text);}
+   if(name==='alert'){const variant=element.getAttribute('data-variant');assertColor('backgroundColor',colors[variant+'-background']);assertColor('color',colors[variant+'-text']);
+    const icon=element.querySelector('[data-part="icon"]'),expected=design.widgets.icons[variant];
+    if(icon?.getAttribute('viewBox')!==expected.viewBox||icon?.getAttribute('stroke-width')!==String(expected.strokeWidth)||JSON.stringify([...icon.querySelectorAll('path')].map(path=>path.getAttribute('d')))!==JSON.stringify(expected.paths))failures.push('Icon geometry differs from declared '+variant);
+   }
+   if(name==='panel')assertColor('backgroundColor',colors.surface);
+   const rootCss=getComputedStyle(element);
+   const dimension=(node,property,value)=>{const actual=getComputedStyle(node)[property],expected=normal(property,value);if(actual!==expected)failures.push(name+'.'+property+': expected '+expected+', got '+actual);};
+   if(spec.styles.gap)dimension(element,'gap',spec.styles.gap);
+   if(spec.styles.marginY){dimension(element,'marginTop',spec.styles.marginY);dimension(element,'marginBottom',spec.styles.marginY);}
+   if(spec.styles.padding)for(const side of ['Top','Right','Bottom','Left'])dimension(element,'padding'+side,innerWidth<=parseFloat(design.tokens.spacing['mobile-breakpoint'])?design.tokens.spacing.s20:spec.styles.padding);
+   if(spec.styles.iconSize){const icon=element.querySelector('[data-part="icon"]');dimension(icon,'width',spec.styles.iconSize);dimension(icon,'height',spec.styles.iconSize);}
+   if(element.matches(':focus-visible')&&name==='button'||element.matches(':focus')&&['input','textarea'].includes(name)){
+    dimension(element,'outlineWidth','2px');if(rootCss.outlineStyle!=='solid')failures.push(name+' missing focus outline');assertColor('outlineColor',colors['control-focus']);
+   }
+   if(name==='input'||name==='textarea')assertColor('borderTopColor',colors[element.getAttribute('aria-invalid')==='true'?'error-border':element.matches(':hover')?'control-focus':'control-border']);
+   if(element.matches(':disabled')&&rootCss.opacity!=='0.5')failures.push(name+' missing disabled appearance');
+  }
+  return failures;
+ },design);
+ if(failures.length)throw new Error(failures.slice(0,12).join('\n'));
+}
+
+async function interact(page,id){
+ const [widget,,state]=id.split('.');if(widget==='page')return;
+ const control=page.locator(`[data-widget="${widget}"]`).first();
+ if(state==='hover'||state==='active'){await control.hover();if(state==='active')await page.mouse.down();}
+ if(state==='focus'){await page.keyboard.press('Tab');if(!await control.evaluate(el=>el===document.activeElement))throw new Error(id+' did not receive focus');}
+ if(state==='disabled'||state==='loading'){if(!await control.isDisabled())throw new Error(id+' must disable interaction');}
+ if(state==='loading'&&await control.getAttribute('aria-busy')!=='true')throw new Error('Loading state is not exposed');
+ if(state==='invalid'&&await control.getAttribute('aria-invalid')!=='true')throw new Error('Invalid state is not exposed');
+ if(widget==='input'&&id.split('.')[1]==='password'&&await control.getAttribute('type')!=='password')throw new Error('Password must stay masked');
+}
+async function checkKeyboard(page,id){
+ const [widget,,state]=id.split('.'),control=page.locator(`[data-widget="${widget}"]`).first();
+ if(widget==='button'&&state==='default'){
+  await control.focus();await page.keyboard.press('Enter');await page.keyboard.press('Space');
+  if(await page.locator('[data-events]').getAttribute('data-events')!=='2')throw new Error('Button must activate once per Enter/Space');
+ }
+ if((widget==='input'||widget==='textarea')&&state==='readonly'){
+  const before=await control.inputValue();await control.focus();await page.keyboard.type('x');if(await control.inputValue()!==before)throw new Error('Readonly value changed');
+ }
+}
+try {
+ await syncDesign(root,true);
+ if(next)for(const file of ['tsconfig.json','next-env.d.ts'])nextFiles.set(file,await readFile(join(root,'web',file)));
+ validateFixtureCoverage(design);
+ const digest=createHash('sha256');for(const file of ['design/tokens.json','design/widgets.json','design/structure.json','design/layout.css','design/widgets.css','web/src/ui.tsx','web/src/App.tsx','web/src/workspace-model.ts','tests/design/harness.tsx','scripts/design-verify.mjs','scripts/design-coverage.mjs','scripts/design-next-cleanup.mjs','scripts/design.mjs','web/src/structure-view.tsx','web/src/widget-icon.tsx','web/src/widget-types.ts','web/src/styles.css','web/src/design-tokens.css','web/src/design-layout.css','web/src/design-widgets.css','web/src/design-runtime.json','project.json',...(next?['web/next.config.ts']:[]),...(project.ui==='shadcn'?['web/src/tailwind.css']:[])])digest.update(file).update(await readFile(join(root,file)));report.sourceDigest=digest.digest('hex');
+ await writeFile(harness,await readFile(join(root,'tests/design/harness.tsx')),{flag:'wx'});createdHarness=true;
+ if(next){await mkdir(dirname(entry));createdDirectory=true;await writeFile(entry,`export {default} from '../../src/scaffold-design-check-${nonce}';\n`,{flag:'wx'});}
+ else await writeFile(entry,`<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"></head><body><div id="root"></div><script type="module">import React from 'react';import{createRoot}from'react-dom/client';import Harness from './src/scaffold-design-check-${nonce}.tsx';createRoot(document.getElementById('root')).render(React.createElement(Harness));</script></body></html>`,{flag:'wx'});
+ createdEntry=true;
+ const port=await new Promise((yes,no)=>{const socket=createServer();socket.on('error',no);socket.listen(0,'127.0.0.1',()=>{const port=socket.address().port;socket.close(()=>yes(port));});});
+ const web=join(root,'web'),webRequire=createRequire(join(web,'package.json'));
+ const executable=next?webRequire.resolve('next/dist/bin/next'):resolve(dirname(webRequire.resolve('vite/package.json')),'bin/vite.js');
+ server=spawn(process.execPath,[executable,...(next?['dev','--webpack','--hostname','127.0.0.1','--port',String(port)]:['--host','127.0.0.1','--port',String(port),'--strictPort'])],{cwd:web,env:{...process.env,NEXT_TELEMETRY_DISABLED:'1',...(next?{SCAFFOLD_DESIGN_DIST_DIR:nextDist}:{})},stdio:['ignore','pipe','pipe']});
+ for(const stream of [server.stdout,server.stderr])stream.on('data',data=>{serverLog=(serverLog+data).slice(-50000);});
+ server.on('error',error=>{serverLog+=error.message;});
+ const base=`http://127.0.0.1:${port}/scaffold-design-check-${nonce}${next?'':'.html'}`;
+ let ready=false;for(let attempt=0;attempt<120;attempt++){if(interrupted)throw new Error('Interrupted');if(server.exitCode!==null)throw new Error('Fixture server exited');try{const response=await fetch(base);if(response.ok){ready=true;break;}}catch{}await new Promise(resolve=>setTimeout(resolve,500));}
+ if(!ready)throw new Error('Fixture server did not become ready');
+ browser=await chromium.launch({headless:true});report.browser=browser.version();
+ const cases=Object.entries(design.widgets.widgets).flatMap(([name,spec])=>spec.variants.flatMap(variant=>spec.states.map(state=>`${name}.${variant}.${state}`))).concat(design.structure.scenarios.map(name=>'page.'+name));
+ report.expectedCases=cases.length*design.widgets.acceptance.viewports.length;
+ for(const viewport of design.widgets.acceptance.viewports){
+  const context=await browser.newContext({viewport,deviceScaleFactor:1,reducedMotion:'reduce',locale:'zh-CN',timezoneId:'UTC'});
+  const page=await context.newPage();
+  for(const id of cases){
+   if(interrupted)throw new Error('Interrupted');
+   const measurements={};let failure;
+   try{
+    for(const mode of ['reference','actual']){
+     await page.mouse.move(viewport.width-1,viewport.height-1);await page.goto(base+`?case=${encodeURIComponent(id)}&mode=${mode}`,{waitUntil:'networkidle'});
+     await page.locator(`[data-design-ready="${id}"]`).waitFor();await page.evaluate(()=>document.fonts.ready);
+     await interact(page,id);await page.evaluate(()=>new Promise(resolve=>requestAnimationFrame(()=>requestAnimationFrame(resolve))));await checkSpecification(page);measurements[mode]=await collect(page);await page.mouse.up();await checkKeyboard(page,id);
+    }
+    const differences=compare(measurements.reference,measurements.actual);if(differences.length)throw new Error(differences.slice(0,12).join('\n'));
+    if(!measurements.actual.length)throw new Error('No measurable contract elements');
+   }catch(error){failure=error.message;report.failures.push({id,viewport,failure});await page.screenshot({path:join(output,`${viewport.width}-${id}.png`),fullPage:true}).catch(()=>{});}
+   report.cases.push({id,viewport,status:failure?'FAIL':'PASS',...(failure?{failure}:{}),measurements});
+  }
+  await context.close();
+ }
+ if(report.cases.length!==report.expectedCases)throw new Error('Incomplete declared coverage');
+ report.status=report.failures.length?'FAIL':'PASS';
+}catch(error){report.failures.push({failure:error.message});}
+finally{
+ await browser?.close();server?.kill('SIGTERM');
+ if(server&&server.exitCode===null)await Promise.race([new Promise(resolve=>server.once('exit',resolve)),new Promise(resolve=>setTimeout(()=>{server.kill('SIGKILL');resolve();},3000))]);
+ if(createdHarness)await rm(harness,{force:true});if(createdDirectory)await rm(dirname(entry),{recursive:true,force:true});else if(createdEntry)await rm(entry,{force:true});
+ if(next){await rm(join(root,'web',nextDist),{recursive:true,force:true});for(const [file,content] of nextFiles){const path=join(root,'web',file),current=await readFile(path,'utf8');const cleaned=cleanNextFixtureConfig(file,current,content.toString(),nextDist);if(cleaned!==current)await writeFile(path,cleaned);}}
+ report.finishedAt=new Date().toISOString();await writeFile(join(output,'result.json'),JSON.stringify(report,null,2)+'\n');await writeFile(join(output,'server.log'),serverLog);
+ process.removeListener('SIGINT',signals);process.removeListener('SIGTERM',signals);
+}
+console.log(JSON.stringify({status:report.status,template:project.template,ui:project.ui,expectedCases:report.expectedCases,completedCases:report.cases.length,failures:report.failures.slice(0,8),report:'reports/design-check/result.json'},null,2));
+if(report.status!=='PASS')process.exitCode=1;

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

@@ -0,0 +1,108 @@
+import {readFile, writeFile, mkdir, lstat, realpath} from 'node:fs/promises';
+import {realpathSync} from 'node:fs';
+import {resolve, dirname, join, relative, sep} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const sections=['Overview','Colors','Typography','Layout','Elevation & Depth','Shapes','Components',"Do's and Don'ts"];
+const generated=['DESIGN.md','web/src/design-tokens.css','web/src/design-layout.css','web/src/design-widgets.css','web/src/design-runtime.json'];
+const variable=path=>'--design-'+path.split('.').map(part=>part.replace(/[A-Z]/g,c=>'-'+c.toLowerCase())).join('-');
+function leaves(value,path='') {
+  return Object.entries(value).flatMap(([key,child])=>{
+    if(!/^[a-zA-Z][a-zA-Z0-9-]*$/.test(key))throw new Error('Invalid design token key: '+key);
+    const at=path?path+'.'+key:key;
+    if(child && typeof child==='object' && !Array.isArray(child))return leaves(child,at);
+    if(typeof child!=='string' && (typeof child!=='number'||!Number.isFinite(child)))throw new Error('Invalid token value: '+at);
+    return [[at,child]];
+  });
+}
+function resolver(tokens) {
+  const flat=new Map(leaves(tokens));
+  function get(path,seen=[]) {
+    if(!flat.has(path))throw new Error('Unknown design token reference: '+path);
+    if(seen.includes(path))throw new Error('Cyclic design token reference: '+path);
+    const value=flat.get(path);
+    const match=typeof value==='string' && /^\{([\w.-]+)\}$/.exec(value);
+    if(match)return get(match[1],[...seen,path]);
+    if(typeof value==='string' && /[{};\n\r<>]/.test(value))throw new Error('Unsafe or partial design token reference: '+path);
+    return value;
+  }
+  for(const path of flat.keys())get(path);
+  return {flat,get};
+}
+function yaml(value,indent=0) {
+  return Object.entries(value).map(([key,child])=>' '.repeat(indent)+key+':'+(child && typeof child==='object'
+    ? '\n'+yaml(child,indent+2) : ' '+JSON.stringify(child))).join('\n');
+}
+function resolveTree(value,get) {
+  if(Array.isArray(value))return value.map(child=>resolveTree(child,get));
+  if(value && typeof value==='object')return Object.fromEntries(Object.entries(value).map(([key,child])=>[key,resolveTree(child,get)]));
+  const match=typeof value==='string' && /^\{([\w.-]+)\}$/.exec(value);
+  return match?get(match[1]):value;
+}
+export async function designFiles(root) {
+  const source=JSON.parse(await readFile(join(root,'design/tokens.json'),'utf8'));
+  const widgets=JSON.parse(await readFile(join(root,'design/widgets.json'),'utf8'));
+  const structure=JSON.parse(await readFile(join(root,'design/structure.json'),'utf8'));
+  if(widgets.schemaVersion!==1||structure.schemaVersion!==1)throw new Error('Unsupported design specification version');
+  for(const [name,spec] of Object.entries(widgets.widgets)) {
+    for(const key of ['parts','variants','states'])if(!Array.isArray(spec[key])||!spec[key].length||new Set(spec[key]).size!==spec[key].length)throw new Error('Invalid widget '+name+'.'+key);
+  }
+  const tokens=source.tokens;
+  const {flat,get}=resolver({...tokens,effects:source.effects,widgets:Object.fromEntries(Object.entries(widgets.widgets).map(([name,spec])=>[name,spec.styles]))});
+  const substitute=text=>text.replace(/\{\{([\w.-]+)\}\}/g,(_,path)=>String(get(path)));
+  const guide=substitute(await readFile(join(root,'design/guide.md'),'utf8'));
+  if(JSON.stringify([...guide.matchAll(/^## (.+)$/gm)].map(m=>m[1]))!==JSON.stringify(sections))throw new Error('Design guide must contain the eight ordered sections');
+  const cssEntries=[...flat].filter(([path])=>!['version','name','description'].includes(path));
+  const variables=new Set(cssEntries.map(([path])=>variable(path)));
+  if(variables.size!==cssEntries.length)throw new Error('Design token names produce colliding CSS variables');
+  const css='/* Generated by design:sync. Edit design/tokens.json or design/widgets.json. */\n:root {\n'+cssEntries.map(([path])=>`  ${variable(path)}: ${get(path)};`).join('\n')+'\n}\n';
+  const layout=substitute(await readFile(join(root,'design/layout.css'),'utf8'));
+  const widgetCss=substitute(await readFile(join(root,'design/widgets.css'),'utf8'));
+  for(const match of (layout+widgetCss).matchAll(/var\(\s*(--design-[\w-]+)\s*(?:,|\))/g))if(!variables.has(match[1]))throw new Error('Unknown CSS design variable: '+match[1]);
+  return new Map([
+    [generated[0],'---\n'+yaml(tokens)+'\n---\n\n'+guide],
+    [generated[1],css],
+    [generated[2],'/* Generated by design:sync. Edit design/layout.css. */\n'+layout],
+    [generated[3],'/* Generated by design:sync. Edit design/widgets.css. */\n'+widgetCss],
+    [generated[4],JSON.stringify({tokens:resolveTree(tokens,get),effects:resolveTree(source.effects,get),widgets:resolveTree(widgets,get),structure},null,2)+'\n'],
+  ]);
+}
+async function validateOutputPaths(root,paths) {
+  for(const path of paths) {
+    const file=join(root,path);
+    if(relative(root,file).split(sep).includes('..'))throw new Error('Design output escapes project');
+    let current=root;
+    for(const segment of path.split('/')) {
+      current=join(current,segment);
+      try {
+        const info=await lstat(current);
+        if(info.isSymbolicLink())throw new Error('Refusing design symlink: '+relative(root,current));
+        if(current!==file&&!info.isDirectory())throw new Error('Design output parent is not a directory');
+      }catch(error){if(error.code!=='ENOENT')throw error;}
+    }
+  }
+}
+export async function syncDesign(root,check=false) {
+  root=await realpath(root);
+  const files=await designFiles(root);
+  // Check every ancestor before the first write so failure cannot partly overwrite outputs.
+  await validateOutputPaths(root,files.keys());
+  for(const [path,content] of files) {
+    const file=join(root,path);
+    if(check) {
+      let actual;try{actual=await readFile(file,'utf8');}catch{throw new Error('Missing generated design file: '+path);}
+      if(actual!==content)throw new Error('Design drift: '+path+'; run npm run design:sync');
+    }else{
+      await mkdir(dirname(file),{recursive:true});
+      await writeFile(file,content);
+    }
+  }
+}
+if(process.argv[1] && realpathSync(process.argv[1])===fileURLToPath(import.meta.url)) {
+  try {
+    const command=process.argv[2];
+    if(!['sync','check'].includes(command))throw new Error('Use: node scripts/design.mjs sync|check');
+    await syncDesign(resolve(dirname(fileURLToPath(import.meta.url)),'..'),command==='check');
+    console.log(command==='check'?'Design documentation and UI outputs match their source.':'Generated DESIGN.md and UI design outputs.');
+  }catch(error){console.error(error.message);process.exitCode=1;}
+}

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

@@ -0,0 +1,118 @@
+import { spawn, execFileSync } from 'node:child_process';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomBytes } from 'node:crypto';
+const root=resolve(dirname(fileURLToPath(import.meta.url)),'..');
+process.chdir(root);
+const project=JSON.parse(readFileSync('project.json','utf8'));
+const stack=project.template, next=stack==='next-fullstack', fast=stack==='react-fastapi';
+if(process.env.SCAFFOLD_TEST!=='1' && existsSync('.env')) process.loadEnvFile('.env');
+const children=new Set();
+let stopping=false;
+function stop(signal='SIGTERM') { stopping=true;for(const c of children)c.kill(signal); }
+for(const sig of ['SIGTERM','SIGINT'])process.on(sig,()=>{stop(sig);process.exitCode=sig==='SIGINT'?130:143;});
+async function run(program,args,cwd='.',extra={}) {
+  if(stopping)throw new Error('Interrupted');
+  return new Promise((yes,no)=>{
+    const c=spawn(program,args,{cwd:resolve(root,cwd),stdio:'inherit',env:{...process.env,...extra}});children.add(c);
+    c.on('error',e=>{children.delete(c);no(e);});
+    c.on('exit',(code,signal)=>{children.delete(c);code===0?yes():no(new Error(`${program} failed (${code??signal})`));});
+  });
+}
+function env() {
+  for(const key of ['DATABASE_URL','AUTH_SECRET','APP_ORIGIN']) if(!process.env[key])throw new Error(`Missing ${key}; run dev:setup or provide an isolated test environment.`);
+  if(process.env.AUTH_SECRET.length<32)throw new Error('AUTH_SECRET must contain at least 32 characters.');
+}
+async function migrationGuard() {
+  env();
+  if(process.env.SCAFFOLD_TEST==='1') {
+    const context=JSON.parse(readFileSync(process.env.SCAFFOLD_TEST_CONTEXT,'utf8'));
+    const u=new URL(process.env.DATABASE_URL);
+    if(context.databaseUrl!==process.env.DATABASE_URL || u.hostname!=='127.0.0.1' || !/^[a-f0-9]{64}$/.test(context.containerId||'') || !/^[a-f0-9-]{36}$/.test(context.runId||''))throw new Error('Test database identity mismatch.');
+    // Inspect privately: Docker configuration contains the ephemeral database password.
+    const actual=JSON.parse(execFileSync('docker',['inspect','--format','{{json .}}',context.containerId],{encoding:'utf8',stdio:['ignore','pipe','pipe']}));
+    const ports=actual.NetworkSettings?.Ports?.['5432/tcp']||[];
+    const variables=actual.Config?.Env||[];
+    if(actual.Id!==context.containerId || actual.Config?.Labels?.['agent-scaffold.run']!==context.runId || actual.State?.Running!==true || ports.length!==1 || ports[0].HostIp!=='127.0.0.1' || ports[0].HostPort!==u.port || u.pathname!=='/app' || decodeURIComponent(u.username)!=='app' || !variables.includes('POSTGRES_USER=app') || !variables.includes('POSTGRES_DB=app') || !variables.includes('POSTGRES_PASSWORD='+decodeURIComponent(u.password)))throw new Error('Test database identity mismatch.');
+  }
+}
+async function migrate() {
+  await migrationGuard();
+  if(fast)await run('uv',['run','--frozen','alembic','upgrade','head'],'backend');
+  else if(stack==='react-spring')await run('./mvnw',['-q','-DskipTests','spring-boot:run','-Dspring-boot.run.arguments=--scaffold.migrate-only=true'],'backend',jdbc());
+  else await run('pnpm',['exec','prisma','migrate','deploy'],next?'web':'backend');
+}
+function jdbc() {
+  const u=new URL(process.env.DATABASE_URL);
+  return {SESSION_COOKIE_SECURE:String(process.env.APP_ORIGIN.startsWith('https://')),SPRING_DATASOURCE_URL:`jdbc:postgresql://${u.hostname}:${u.port||5432}${u.pathname}`,SPRING_DATASOURCE_USERNAME:decodeURIComponent(u.username),SPRING_DATASOURCE_PASSWORD:decodeURIComponent(u.password)};
+}
+async function seed() {
+  await migrationGuard();
+  for(const k of ['SEED_A_EMAIL','SEED_B_EMAIL','SEED_PASSWORD']) if(!process.env[k])throw new Error(`Missing explicit ${k}`);
+  if(fast)await run('uv',['run','--frozen','python','-m','app.seed'],'backend');
+  else if(stack==='react-spring')await run('./mvnw',['-q','-DskipTests','spring-boot:run','-Dspring-boot.run.arguments=--scaffold.seed-only=true'],'backend',jdbc());
+  else await run('pnpm',['exec','tsx','scripts/seed.ts'],next?'web':'backend',{SCAFFOLD_SEED:'1'});
+}
+async function serve() {
+  env();
+  const tasks=[];
+  if(fast)tasks.push(run('uv',['run','--frozen','uvicorn','app.main:app','--host','127.0.0.1','--port',process.env.PORT||'8000'],'backend'));
+  if(stack==='react-spring')tasks.push(run('java',['-jar','target/backend.jar'],'backend',jdbc()));
+  if(stack==='react-nest')tasks.push(run('node',['dist/main.js'],'backend'));
+  if(next)tasks.push(run('pnpm',['exec','next','start','--hostname','127.0.0.1','--port',process.env.WEB_PORT||'3000'],'web'));
+  else tasks.push(run(fast?'bun':'pnpm',['run','preview','--host','127.0.0.1','--port',process.env.WEB_PORT||'5173','--strictPort'],'web'));
+  try {await Promise.all(tasks);} finally {stop();}
+}
+async function install() {
+  await run('npm',['ci']);
+  await run(fast?'bun':'pnpm',fast?['install','--frozen-lockfile']:['install','--frozen-lockfile'],'web');
+  if(fast)await run('uv',['sync','--frozen'],'backend');
+  else if(stack==='react-nest')await run('pnpm',['install','--frozen-lockfile'],'backend');
+  else if(stack==='react-spring')await run('./mvnw',['-q','-DskipTests','compile'],'backend');
+  if(next||stack==='react-nest')await run('pnpm',['exec','prisma','generate'],next?'web':'backend');
+  await run('npx',['--no-install','playwright','install','chromium']);
+}
+async function setup() {
+  if(process.env.SCAFFOLD_TEST==='1')throw new Error('dev:setup cannot run in test mode.');
+  if(!existsSync('.env')) {
+    const db=randomBytes(24).toString('hex'), secret=randomBytes(32).toString('hex'), pass=randomBytes(16).toString('hex');
+    const web=process.env.WEB_PORT||String(next?3000:5173), dbPort=process.env.POSTGRES_PORT||'54329';
+    const vars={POSTGRES_USER:'app',POSTGRES_DB:'app',POSTGRES_PASSWORD:db,POSTGRES_PORT:dbPort,DATABASE_URL:`postgresql://app:${db}@127.0.0.1:${dbPort}/app`,AUTH_SECRET:secret,APP_ORIGIN:`http://localhost:${web}`,PORT:process.env.PORT||'8000',WEB_PORT:String(web),SEED_A_EMAIL:'alice@example.test',SEED_B_EMAIL:'bob@example.test',SEED_PASSWORD:pass};
+    writeFileSync('.env',Object.entries(vars).map(([k,v])=>`${k}=${v}`).join('\n')+'\n',{flag:'wx',mode:0o600});
+    writeFileSync('.scaffold-local-credentials',`Local development only\nEmail: ${vars.SEED_A_EMAIL}\nPassword: ${pass}\n`,{flag:'wx',mode:0o600});
+    process.loadEnvFile('.env');
+  }
+  await run('docker',['compose','up','-d','--wait','db']);await migrate();await seed();
+  console.log('Development database ready. Credentials are in .scaffold-local-credentials (ignored by Git).');
+}
+const command=process.argv[2];
+try {
+  mkdirSync('reports',{recursive:true});
+  if(command==='install')await install();
+  else if(command==='setup'){await install();await setup();}
+  else if(command==='dev:setup')await setup();
+  else if(command==='migrate')await migrate();
+  else if(command==='seed')await seed();
+  else if(command==='serve')await serve();
+  else if(command==='dev') {await run('node',['scripts/project.mjs','build']);await serve();}
+  else if(command==='build'||command==='typecheck'||command==='lint') {
+    await run('node',['scripts/design.mjs','check']);
+    if(next||stack==='react-nest')await run('pnpm',['exec','prisma','generate'],next?'web':'backend');
+    await run(fast?'bun':'pnpm',['run',command],'web');
+    if(fast) {
+      if(command==='build')await run('uv',['run','--frozen','python','-m','compileall','-q','app'],'backend');
+      if(command==='typecheck')await run('uv',['run','--frozen','mypy','app'],'backend');
+      if(command==='lint')await run('uv',['run','--frozen','ruff','check','app','tests'],'backend');
+    } else if(stack==='react-nest')await run('pnpm',['run',command],'backend');
+    else if(stack==='react-spring')await run('./mvnw',['-q','-DskipTests',command==='build'?'package':'compile'],'backend');
+  } else if(command==='test:native') {
+    await migrationGuard();
+    if(fast)await run('uv',['run','--frozen','python','-m','pytest','--junitxml='+resolve(process.env.SCAFFOLD_REPORT_DIR||'reports','native.xml'),'-q'],'backend');
+    else if(stack==='react-spring')await run('./mvnw',['-q','test','-Dscaffold.reports='+resolve(process.env.SCAFFOLD_REPORT_DIR||'reports','spring')],'backend',jdbc());
+    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: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.');
+} 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.spec.ts

@@ -0,0 +1,47 @@
+import {test,expect,request as requests,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 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 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);
+ expect((await (await a.get(path)).json()).content).toBe(body);
+ expect((await b.get(path)).status()).toBe(404);expect((await b.put(path,{data:{title:'hijacked',content:''}})).status()).toBe(404);expect((await b.delete(path)).status()).toBe(404);
+ const other=await (await b.get('/api/records?page=1&pageSize=100')).json();expect(other.items.some((item:{id:string})=>item.id===row.id)).toBe(false);
+ const page=await (await a.get('/api/records?page=1&pageSize=1')).json();expect(page.items.length).toBeLessThanOrEqual(1);expect(page.total).toBeGreaterThan(0);expect(page.pageSize).toBe(1);
+ const changed=await a.put(path,{data:{title:'Updated title',content:body}});expect(changed.status()).toBe(200);expect(new Date((await changed.json()).updated_at).getTime()).toBeGreaterThanOrEqual(new Date(row.created_at).getTime());
+ const relogin=await login(process.env.SEED_A_EMAIL!);expect((await (await relogin.client.get(path)).json()).title).toBe('Updated title');await relogin.client.dispose();
+ expect((await a.delete(path)).status()).toBe(204);expect((await a.get(path)).status()).toBe(404);
+ const after=await (await a.get('/api/records?page=1&pageSize=100')).json();expect(after.items.some((item:{id:string})=>item.id===row.id)).toBe(false);
+ await Promise.all([a.dispose(),b.dispose(),anonymous.dispose()]);
+});
+test('rejects invalid and protected fields without writing data',async()=>{
+ const {client:a,auth}=await login(process.env.SEED_A_EMAIL!);
+ const count=(await (await a.get('/api/records')).json()).total;
+ for(const data of [{title:'',content:''},{title:'  ',content:''},{title:'x'.repeat(121),content:''},{title:'x',content:'x'.repeat(10001)},{title:'x',content:'',owner_id:auth.user.id},{title:'x',content:'',created_at:new Date().toISOString()},{title:42,content:''}])expect((await a.post('/api/records',{data})).status()).toBe(422);
+ expect((await (await a.get('/api/records')).json()).total).toBe(count);
+ for(const query of ['page=0','pageSize=101','page=bad'])expect((await a.get('/api/records?'+query)).status()).toBe(422);
+ expect((await a.get('/api/records/not-a-uuid')).status()).toBe(422);
+ const unicode=await a.post('/api/records',{data:{title:'😀'.repeat(120),content:''}});expect(unicode.status()).toBe(201);const row=await unicode.json();
+ expect((await a.put(`/api/records/${row.id}`,{data:{title:'bad',content:'',owner_id:auth.user.id}})).status()).toBe(422);
+ expect((await (await a.get(`/api/records/${row.id}`)).json()).title).toBe('😀'.repeat(120));
+ await a.delete(`/api/records/${row.id}`);await a.dispose();
+});
+test('logout and same-origin session protection',async()=>{
+ const {client,auth}=await login(process.env.SEED_A_EMAIL!);
+ if(auth.mode==='session'){
+  const state=await client.storageState();const replay=await requests.newContext({baseURL,storageState:state,extraHTTPHeaders:{Origin:origin}});
+  const cross=await requests.newContext({baseURL,storageState:state,extraHTTPHeaders:{Origin:'https://untrusted.example'}});
+  expect((await cross.post('/api/records',{data:{title:'csrf',content:''}})).status()).toBe(403);await cross.dispose();
+  expect((await client.post('/api/auth/logout',{data:{}})).status()).toBe(204);
+  expect((await replay.get('/api/auth/me')).status()).toBe(401);await replay.dispose();
+ }else{expect(['react-fastapi','react-nest']).toContain(project.template);expect((await client.post('/api/auth/logout',{data:{}})).status()).toBe(204);}
+ await client.dispose();
+});

package/templates/react-fastapi-shadcn/tests/design/harness.tsx

@@ -0,0 +1,63 @@
+"use client";
+import {useEffect,useState} from 'react';
+import type * as React from 'react';
+import {WorkspaceView} from './App';
+import * as actualWidgets from './ui';
+import {WidgetIcon} from './widget-icon';
+import type {WidgetSet} from './widget-types';
+import {createWorkspaceModel,initialWorkspaceState,type WorkspaceState} from './workspace-model';
+import design from './design-runtime.json';
+// Independent semantic HTML oracle; it imports no component library.
+const reference:WidgetSet={
+ Button:({children,variant='primary',loading=false,disabled,type='button',...props})=><button {...props} type={type} data-widget="button" data-variant={variant} aria-busy={loading||undefined} disabled={disabled||loading}><span data-part="label">{children}</span></button>,
+ Input:({invalid,...props})=><input {...props} data-widget="input" aria-invalid={invalid||undefined}/>,
+ TextArea:({invalid,...props})=><textarea {...props} data-widget="textarea" aria-invalid={invalid||undefined}/>,
+ Alert:({children,variant='error'})=><div data-widget="alert" data-variant={variant} role={variant==='error'?'alert':'status'}><WidgetIcon kind={variant}/><div data-part="message">{children}</div></div>,
+ Badge:({children})=><span data-widget="badge" className="badge"><span data-part="label">{children}</span></span>,
+ Panel:({children,className='',...props})=><section {...props} data-widget="panel" className={`panel ${className}`}>{children}</section>,
+ Field:({children,label,htmlFor})=><div data-widget="field" className="field"><label data-part="label" htmlFor={htmlFor}>{label}</label><div data-part="control">{children}</div></div>,
+ Theme:({children})=><>{children}</>
+};
+const record={id:'record-1',title:'一条用于对齐的记录',content:'相同内容，相同交互。\nSecond line.',created_at:'2026-01-01T00:00:00Z',updated_at:'2026-01-01T00:00:00Z'};
+function scenario(name:string):WorkspaceState {
+ const state={...initialWorkspaceState(),checking:false};
+ if(name==='checking')return {...state,checking:true};
+ if(name==='login')return state;
+ if(name==='login-error')return {...state,error:'账号或密码不正确，请重试。'};
+ if(name==='login-busy')return {...state,busy:true,email:'user@example.test',password:'sample-password'};
+ state.user={id:'user-1',email:'user@example.test'};
+ if(name==='workspace-empty')return state;
+ if(name==='workspace-loading')return {...state,loading:true};
+ state.list={items:[record],total:11,page:1,pageSize:10};
+ if(name==='workspace-records')return state;
+ if(name==='editor-new')return {...state,editing:true};
+ if(name==='editor-existing')return {...state,editing:true,selected:record.id,title:record.title,content:record.content,notice:'已保存'};
+ if(name==='editor-error')return {...state,editing:true,selected:record.id,title:record.title,content:record.content,error:'请求失败或超时，输入已保留。'};
+ throw new Error('Unimplemented declared page scenario: '+name);
+}
+export default function Harness(){
+ const [query,setQuery]=useState<URLSearchParams|null>(null),[events,setEvents]=useState(0);
+ useEffect(()=>{setQuery(new URLSearchParams(window.location.search));},[]);
+ if(!query)return null;
+ const mode=query.get('mode'),id=query.get('case')||'';
+ const widgets=mode==='reference'?reference:actualWidgets;
+ const {Button,Input,TextArea,Alert,Badge,Panel,Field,Theme}=widgets;
+ let content:React.ReactNode;
+ if(id.startsWith('page.'))content=<WorkspaceView state={scenario(id.slice(5))} model={createWorkspaceModel(async()=>{throw new Error('Unexpected network call in deterministic fixture');})} widgets={widgets}/>;
+ else {
+  const [name,variant,state]=id.split('.');
+  const spec=design.widgets.widgets[name as keyof typeof design.widgets.widgets];
+  if(!spec||!(spec.variants as readonly string[]).includes(variant)||!(spec.states as readonly string[]).includes(state))throw new Error('Undeclared widget fixture: '+id);
+  const controlProps={disabled:state==='disabled',readOnly:state==='readonly',invalid:state==='invalid',onChange:()=>setEvents(value=>value+1)};
+  if(name==='button')content=<Button variant={variant as 'primary'|'secondary'|'danger'} disabled={state==='disabled'} loading={state==='loading'} onClick={()=>setEvents(value=>value+1)}>{state==='loading'?'正在处理…':'保存记录'}</Button>;
+  else if(name==='input')content=<Input {...controlProps} id="control" aria-label="测试输入" type={variant} defaultValue={variant==='email'?'user@example.test':'示例内容 Sample'} autoComplete="off"/>;
+  else if(name==='textarea')content=<TextArea {...controlProps} aria-label="测试输入" rows={3} defaultValue={'第一行内容\nSecond line'}/>;
+  else if(name==='alert')content=<Alert variant={variant as 'error'|'success'}>操作结果说明，请检查后继续。</Alert>;
+  else if(name==='badge')content=<Badge>个人工作空间</Badge>;
+  else if(name==='panel')content=<Panel><h2>记录面板</h2><p>内容可读，层级明确。</p></Panel>;
+  else if(name==='field')content=<Field label="邮箱" htmlFor="field-control"><Input id="field-control" type="email" defaultValue="user@example.test"/></Field>;
+  else throw new Error('Unimplemented declared widget: '+name);
+  content=<Theme><div style={{width:320,margin:24}}>{content}</div></Theme>;
+ }
+ return <div data-design-ready={id} data-design-mode={mode} data-events={events}>{content}</div>;
+}