@givolt/i3-composer-agent 2.3.1 → 2.3.3

package/skills/i3-ui-prototype/scripts/native-build.cjs

@@ -0,0 +1,91 @@
+'use strict';
+const {spawnSync}=require('node:child_process');
+const http=require('node:http');
+const F=require('./native-files.cjs');
+const {fs,path,crypto,assert,hash,json,id,inside,walk,write,entries}=F;
+function verifyBuild(directory,buildId,{manifest}) {
+  id(buildId); const root=inside(directory,`builds/${buildId}`); const data=json(path.join(root,'manifest.json'));
+  assert.equal(data.buildId,buildId,'Build ID mismatch');
+  for(const step of ['typecheck','test','build'])assert.ok(Object.hasOwn(data.checks||{},step)&&typeof data.checks[step]==='string',`Required build check missing: ${step}`);
+  assert.deepEqual(entries(path.join(root,'site'),walk(path.join(root,'site'))),data.files,'Build bytes changed');
+  assert.equal(hash(JSON.stringify(data.files)),data.buildDigest,'Build digest mismatch');
+  assert.equal(data.candidateDigest,manifest(directory).digest,'Build is for an old candidate / 旧构建');
+  const scripts=Object.keys(data.files).filter(file=>/\.[cm]?js$/.test(file));
+  assert.ok(data.files['index.html'] && data.files['prototype-config.json'] && scripts.length,'Native build entry, config and JavaScript required');
+  assert.ok(scripts.some(file=>fs.readFileSync(inside(path.join(root,'site'),file),'utf8').includes(data.candidateDigest)),'Built JavaScript must embed its candidate identity / 构建标识');
+  return {...data,directory:root};
+}
+
+function verifyBrowserReport(directory,report,build) {
+  const start=Date.parse(report.startedAt),end=Date.parse(report.completedAt);
+  assert.ok(Number.isFinite(start)&&Number.isFinite(end)&&end>=start,'Browser run timestamps must be valid and ordered');
+  const base=new URL(report.previewBaseURL);
+  assert.ok(['http:','https:'].includes(base.protocol)&&!base.username&&!base.password&&!base.search&&!base.hash&&base.pathname.endsWith('/'),'Invalid preview base URL');
+  assert.ok(Array.isArray(report.observedResources)&&report.observedResources.length,'Observed browser resources required');
+  const observations=new Map();
+  for(const resource of report.observedResources) {
+    assert.ok(Object.hasOwn(build.files,resource.path),`Observed resource is outside the fixed build: ${resource.path}`);
+    const actual=new URL(resource.url),expected=new URL(resource.path==='index.html'?'':resource.path,base);
+    const entryAlias=resource.path==='index.html'&&actual.pathname===new URL('index.html',base).pathname;
+    assert.ok(actual.origin===base.origin&&(actual.pathname===expected.pathname||entryAlias)&&!actual.username&&!actual.password,`Observed resource has a different preview URL: ${resource.path}`);
+    assert.equal(resource.status,200,`Observed resource did not return 200: ${resource.path}`);
+    assert.equal(resource.sha256,build.files[resource.path],`Observed resource bytes differ: ${resource.path}`);
+    assert.ok(typeof resource.resourceType==='string'&&resource.resourceType,'Observed resource type required');
+    const type=resource.path==='index.html'?'document':/\.[cm]?js$/.test(resource.path)?'script':resource.path.endsWith('.css')?'stylesheet':resource.path==='prototype-config.json'?'fetch':null;
+    if(type)assert.equal(resource.resourceType,type,`Observed resource request type differs: ${resource.path}`);
+    observations.set(resource.path,resource);
+  }
+  const required=Object.keys(build.files).filter(file=>['index.html','prototype-config.json'].includes(file)||/\.(?:[cm]?js|css)$/.test(file));
+  for(const file of required)assert.ok(observations.has(file),`Browser did not observe required build resource: ${file}`);
+  assert.ok(Array.isArray(report.screenshots)&&report.screenshots.length>=2&&Array.isArray(report.viewports)&&report.viewports.length>=2,'Responsive screenshots required');
+  const png=Buffer.from([0x89,0x50,0x4e,0x47,0x0d,0x0a,0x1a,0x0a]);
+  for(const file of report.screenshots) {
+    const bytes=fs.readFileSync(inside(directory,file));
+    assert.ok(bytes.length>24&&bytes.subarray(0,8).equals(png),`Screenshot must be PNG: ${file}`);
+  }
+  const trace=fs.readFileSync(inside(directory,report.trace));
+  assert.ok(trace.length>=22&&trace[0]===0x50&&trace[1]===0x4b&&[[3,4],[5,6],[7,8]].some(pair=>trace[2]===pair[0]&&trace[3]===pair[1]),'Browser trace must be a ZIP artifact');
+}
+function build(directory,options,{manifest,inspect}) {
+  const checked=inspect(directory); assert.equal(checked.status,'passed',checked.errors?.join('; '));
+  const before=manifest(directory); const app=inside(directory,'app');
+  function run(args,env={}) {
+    const result=spawnSync(process.platform==='win32'?'npm.cmd':'npm',args,{cwd:app,env:{...process.env,...env},encoding:'utf8',timeout:180000,maxBuffer:5*1024*1024});
+    assert.equal(result.status,0,`npm ${args.join(' ')} failed: ${result.error?.message||result.stderr||result.stdout}`);
+    return result.stdout;
+  }
+  if(options.install) run(['ci','--ignore-scripts','--no-audit','--no-fund']);
+  assert.ok(fs.existsSync(path.join(app,'node_modules','vite')),'Local dependencies missing; explicitly build --install');
+  const typecheck=run(['run','typecheck']);
+  const test=run(['test']);
+  fs.mkdirSync(inside(directory,'builds'),{recursive:true}); const stage=fs.mkdtempSync(path.join(directory,'builds','.build-'));
+  try {
+    const output=run(['run','build','--','--outDir',path.join(stage,'site'),'--emptyOutDir'],{VITE_CANDIDATE_ID:before.digest});
+    assert.equal(manifest(directory).digest,before.digest,'Source changed during build');
+    const files=entries(path.join(stage,'site'),walk(path.join(stage,'site'))); const buildDigest=hash(JSON.stringify(files)); const buildId=`b-${buildDigest.slice(0,20)}`;
+    const data={schemaVersion:1,buildId,buildDigest,candidateDigest:before.digest,inputDigest:before.inputDigest,revision:before.revision,files,toolchain:{node:process.version},checks:{typecheck,test,build:output}};
+    write(stage,'manifest.json',data);
+    const destination=inside(directory,`builds/${buildId}`);
+    if(fs.existsSync(destination)) verifyBuild(directory,buildId,{manifest}); else fs.renameSync(stage,destination);
+    write(directory,'last-build.json',{buildId,buildDigest,candidateDigest:before.digest});
+    return {status:'built',...data,directory:destination};
+  } finally { if(fs.existsSync(stage)) fs.rmSync(stage,{recursive:true,force:true}); }
+}
+async function preview(directory,options,{manifest}) {
+  const buildId=options.buildId||json(inside(directory,'last-build.json')).buildId;
+  const checked=verifyBuild(directory,buildId,{manifest}); const site=path.join(checked.directory,'site');
+  const mime={'.html':'text/html; charset=utf-8','.js':'text/javascript; charset=utf-8','.css':'text/css; charset=utf-8','.json':'application/json','.svg':'image/svg+xml','.png':'image/png','.woff2':'font/woff2'};
+  const server=http.createServer((req,res)=>{
+    try {
+      const pathname=decodeURIComponent(new URL(req.url,'http://127.0.0.1').pathname);
+      res.setHeader('Cache-Control','no-store');
+      if(pathname==='/__prototype-build.json') { const current=verifyBuild(directory,buildId,{manifest}); res.setHeader('Content-Type','application/json'); res.end(JSON.stringify({buildId,currentCandidate:current.candidateDigest,buildDigest:current.buildDigest,files:current.files})); return; }
+      const relative=pathname==='/'?'index.html':pathname.replace(/^\//,''); const file=inside(site,relative);
+      if(!fs.existsSync(file)||!fs.statSync(file).isFile()) { res.writeHead(404); res.end('Not found'); return; }
+      res.setHeader('Content-Type',mime[path.extname(file)]||'application/octet-stream'); res.end(fs.readFileSync(file));
+    } catch(error) { res.writeHead(409); res.end(error.message); }
+  });
+  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(options.port||0,'127.0.0.1',resolve);});
+  return {server,url:`http://127.0.0.1:${server.address().port}/`,build:checked};
+}
+module.exports={build,verifyBuild,preview,verifyBrowserReport};

package/skills/i3-ui-prototype/scripts/native-delivery.cjs

@@ -0,0 +1,103 @@
+'use strict';
+const F=require('./native-files.cjs');
+const {fs,path,crypto,assert,json,inside,write}=F;
+const read=(root,file)=>fs.existsSync(inside(root,file))?json(inside(root,file)):null;
+const quote=value=>`'${String(value).replace(/'/g,"'\\''")}'`;
+
+function state(directory,options,lib) {
+  directory=path.resolve(directory);
+  const current=lib.manifest(directory),meta=json(inside(directory,'prototype.json'));
+  const review=lib.effectiveReview(meta,current);
+  const structure=lib.inspect(directory),advice=read(directory,'qa/design-advice.json'),decisions=read(directory,'design-system/decisions.json');
+  let design;
+  try { const reviewed=lib.inspectDesignReview(directory,current); design={status:reviewed.status,queries:reviewed.queries,records:reviewed.records,adopted:reviewed.adoptedAdvice.length}; }
+  catch(error) { design={status:advice?.status==='pending'||decisions?.reviewStatus==='pending'?'pending':'failed',queries:advice?.queries?.length||0,records:advice?.records?.length||0,errors:[error.message]}; }
+  let build={status:'not-run'};
+  const pointer=read(directory,'last-build.json');
+  if(pointer) {
+    try { const checked=lib.verifyBuild(directory,pointer.buildId); build={status:'current',buildId:checked.buildId,buildDigest:checked.buildDigest,checks:Object.keys(checked.checks)}; }
+    catch(error) { build={status:pointer.candidateDigest!==current.digest?'stale':'failed',buildId:pointer.buildId,errors:[error.message]}; }
+  }
+  let browser={status:'not-run'};
+  const latest=read(directory,'qa/latest.json');
+  if(latest) {
+    try {
+      const report=json(inside(directory,latest.report)),checked=lib.inspect(directory,{acceptance:true});
+      browser={status:report.candidateDigest!==current.digest||report.revision!==current.revision?'stale':checked.status==='passed'?'current':'failed',report:latest.report,reportDigest:F.hash(fs.readFileSync(inside(directory,latest.report))),runId:report.id,executor:report.executor,...(checked.errors?{errors:checked.errors}:{})};
+    } catch(error) { browser={status:'failed',errors:[error.message]}; }
+  }
+  const devtoolsReview=require('./native-devtools.cjs').check(directory,lib);
+  const execution=require('./execution-runtime.cjs').check(directory,'delivery',lib);
+  const ownership=read(directory,'.prototype-write.lock');
+  const savedDelivery=read(directory,'qa/delivery.json');
+  const deliveryCurrent=savedDelivery?.schemaVersion===1&&savedDelivery.status==='complete'&&savedDelivery.id===meta.id&&savedDelivery.revision===current.revision&&savedDelivery.candidateDigest===current.digest&&savedDelivery.inputDigest===current.inputDigest&&savedDelivery.buildId===build.buildId&&savedDelivery.buildDigest===build.buildDigest&&savedDelivery.report===browser.report&&savedDelivery.review===review.status&&savedDelivery.humanConfirmationRequired===(review.status!=='approved')&&browser.status==='current'&&((!devtoolsReview.required&&savedDelivery.browserReportDigest===undefined)||savedDelivery.browserReportDigest===browser.reportDigest)&&(!devtoolsReview.required||(devtoolsReview.status==='current'&&savedDelivery.devtoolsReviewDigest===devtoolsReview.reportDigest));
+  const executionCurrent=execution.status==='not-required'||execution.status==='passed'&&savedDelivery?.runId===execution.runId&&savedDelivery?.executionEvidenceDigest===F.hash(fs.readFileSync(inside(directory,'qa/execution-evidence.json')));
+  const delivery=savedDelivery?{status:deliveryCurrent&&executionCurrent?'current':'stale',path:'qa/delivery.json',revision:savedDelivery.revision,...(deliveryCurrent&&executionCurrent?{result:savedDelivery}:{})}:null;
+  let runtime;
+  try { const provider=require('./native-browser.cjs').resolvePlaywright(directory,options); runtime={availability:'available',...provider,launchVerified:false}; }
+  catch(error) { runtime={availability:'missing',reason:error.message}; }
+  const cli=path.join(__dirname,'native-pilot.cjs');
+  const command=(operation,args=[])=>{const argv=[process.execPath,cli,operation,directory,...args];return {argv,shell:argv.map(quote).join(' ')};};
+  let nextRevision=/^r(\d+)$/.test(current.revision)?`r${String(Number(current.revision.slice(1))+1).padStart(3,'0')}`:`${current.revision}-next`;
+  while(fs.existsSync(inside(directory,`baselines/${nextRevision}`))) nextRevision+='-next';
+  const expected=['--expected-revision',current.revision,'--expected-digest',current.digest];
+  const browserArgs=[];
+  const browserProvider=options.playwrightModule||process.env.PLAYWRIGHT_MODULE||(runtime.availability==='available'?runtime.packageRoot:null);
+  if(browserProvider) browserArgs.push('--playwright-module',browserProvider);
+  if(options.browserChannel) browserArgs.push('--browser-channel',options.browserChannel);
+  if(options.expectedCategories) browserArgs.push('--expected-categories',typeof options.expectedCategories==='string'?options.expectedCategories:JSON.stringify(options.expectedCategories));
+  if(options.expectedDescription) browserArgs.push('--expected-description',options.expectedDescription);
+  if(options.verifyBlurValidation===true) browserArgs.push('--verify-blur-validation');
+  if(options.verifyAtomicStatus===true) browserArgs.push('--verify-atomic-status');
+  const commands={state:command('state'),revise:command('revise',['--revision',nextRevision,...expected]),build:command('build',fs.existsSync(inside(directory,'app/node_modules/vite'))?[]:['--install']),browser:command('browser',browserArgs),finalize:command('finalize',expected)};
+  if(meta.runtime.contentReference) {
+    delete commands.browser;
+    commands.recordRun=command('record-run',['--report',path.join(directory,'qa/business-browser-input.json')]);
+  }
+  if(build.status==='current')commands.preview=command('preview',['--build-id',build.buildId]);
+  if(devtoolsReview.required)commands.recordDevtoolsReview=command('record-devtools-review',['--report',path.join(directory,'qa/devtools-review-input.json')]);
+  if(meta.runtime.executionPolicy){commands.executionBegin=command('execution-begin');commands.executionTemplate=command('execution-template');commands.executionCheck=command('execution-check');}
+  let generation=null;
+  if(meta.runtime.generationContract===1)try{const fixed=json(inside(directory,'inputs/generation.json'));const plan=require('./generation-contract.cjs').view(fixed);generation={presentation:fixed.presentation,pendingDecisions:fixed.pendingDecisions,pendingReferenceElements:fixed.pendingReferenceElements.length,referenceReview:plan.referenceReview,implementation:require('./generation-evidence.cjs').validateImplementation(directory,fixed,json(inside(directory,'design-system/implementation.json')),{frameworkMap:json(inside(directory,'inputs/framework.json')).componentMap})};}catch(error){generation={status:'failed',errors:[error.message]};}
+  const nextAction=ownership?'wait-for-owner':structure.status!=='passed'?'repair-structure':generation&&(generation.pendingDecisions.length||generation.pendingReferenceElements)?'resolve-generation-decisions':generation?.implementation.status==='pending'?'implement-business':meta.runtime.contentReference&&meta.business?.status!=='adapted'?'implement-business':!['reviewed','no-match','skipped'].includes(design.status)?'review-design':build.status!=='current'?'build':browser.status!=='current'?(meta.runtime.contentReference?'business-browser-review':'browser'):devtoolsReview.required&&devtoolsReview.status!=='current'?'devtools-review':deliveryCurrent?'return-result':'finalize';
+  if(generation)commands.replan=command('replan',['--scope',path.join(directory,'inputs/scope.json'),'--revision',nextRevision,...expected]);
+  const fixedScope=json(inside(directory,'inputs/scope.json'));
+  const scopes=meta.runtime.generationContract===1?{sourceFile:'inputs/scope.json',schemaVersion:fixedScope.schemaVersion,title:fixedScope.title,moduleIds:fixedScope.moduleIds,pages:fixedScope.pages.map(page=>({id:page.id,title:page.title,referencePage:page.referencePage,regions:page.regions.map(region=>({id:region.id,pattern:region.pattern||region.mode,fields:region.fields?.length||0,actions:region.actions?.length||0}))})),requirements:fixedScope.requirements.map(item=>({id:item.id,pages:item.pages,source:{type:item.source.type,reference:item.source.reference}}))}:fixedScope;
+  return {status:structure.status==='passed'?'ready':'failed',operation:'state',readOnly:true,directory,id:meta.id,revision:current.revision,candidateDigest:current.digest,inputDigest:current.inputDigest,identity:current.identity,instanceId:meta.instanceId,scopes,structure,...(generation?{generation}:{}),design,build,browser,devtoolsReview,execution,delivery,browserRuntime:runtime,ownership,verification:meta.verification,review,nextAction:meta.runtime.executionPolicy&&execution.status==='failed'?'resolve-execution-evidence':nextAction,commands,notes:['Design decisions and real provider queries remain the executing role responsibility.','Use the printed commands; no source-code inspection is required to recover flags or digests.','A missing browser provider requires an existing Playwright module path; no automatic install or global changes.','Legacy invocation fields retain their original meaning. New policy checks are reported separately in execution; native-source correlation is not tamper-proof attestation.']};
+}
+
+function finalize(directory,options,lib) {
+  directory=path.resolve(directory);
+  const before=lib.manifest(directory),checked=lib.inspect(directory,{acceptance:true});
+  assert.equal(checked.status,'passed',`Current acceptance required / 当前实际验收未通过: ${checked.errors?.join('; ')}`);
+  const devtools=require('./native-devtools.cjs');
+  const requiredReview=devtools.check(directory,lib);assert.ok(!requiredReview.required||requiredReview.status==='current',`Current DevTools review required: ${requiredReview.errors?.join('; ')||requiredReview.status}`);
+  require('./execution-runtime.cjs').requireStage(directory,'delivery',lib);
+  const owner=`finalize-${crypto.randomUUID()}`;
+  lib.claim(directory,{owner,expectedRevision:options.expectedRevision||before.revision,expectedDigest:options.expectedDigest||before.digest});
+  try {
+    const again=lib.inspect(directory,{acceptance:true});assert.equal(again.status,'passed',again.errors?.join('; '));
+    const devtoolsReview=devtools.check(directory,lib);assert.ok(!devtoolsReview.required||devtoolsReview.status==='current','Current DevTools review required');
+    assert.equal(lib.manifest(directory).digest,before.digest,'Candidate changed before final handoff');
+    const meta=json(inside(directory,'prototype.json')),scope=json(inside(directory,'inputs/scope.json'));
+    const review=lib.effectiveReview(meta,before);
+    const latest=json(inside(directory,'qa/latest.json')),report=json(inside(directory,latest.report));
+    const delivery={schemaVersion:1,status:'complete',operation:'finalize',id:meta.id,revision:before.revision,candidateDigest:before.digest,inputDigest:before.inputDigest,framework:meta.framework,template:meta.template,expertMode:meta.expertMode,expert:meta.expert.status,verification:'passed',review:review.status,checks:{structure:'passed',acceptance:'passed',build:'current',browser:'current'},buildId:report.buildId,buildDigest:report.buildDigest,report:latest.report,executor:report.executor,tool:report.tool,handoff:path.join(directory,'HANDOFF.md'),receipt:'qa/delivery.json',openQuestions:scope.openQuestions||[],humanConfirmationRequired:review.status!=='approved'};
+    const execution=require('./execution-runtime.cjs').requireStage(directory,'delivery',lib);
+    delivery.invocationVerification=execution.invocationVerification;delivery.tamperProof=false;
+    if(execution.status==='passed'){delivery.execution=execution;delivery.runId=execution.runId;delivery.policyDigest=execution.policyDigest;delivery.checks.execution='passed';delivery.executionEvidenceDigest=F.hash(fs.readFileSync(inside(directory,'qa/execution-evidence.json')));}
+    delivery.browserReportDigest=F.hash(fs.readFileSync(inside(directory,latest.report)));
+    if(devtoolsReview.required){delivery.devtoolsReview=devtoolsReview.report;delivery.devtoolsReviewDigest=devtoolsReview.reportDigest;delivery.checks.devtoolsReview='current';delivery.invocationEvidence=execution.status==='passed'?'Native response IDs correlated with the configured host transcript; not tamper-proof.':'Verify actual Skill/MCP calls independently in the host transcript';}
+    const start='<!-- native-delivery:start -->',end='<!-- native-delivery:end -->';
+    const block=[start,'## 当前真实交付状态',`- 原型：${delivery.id} / ${delivery.revision}`,`- candidateDigest：${delivery.candidateDigest}`,`- inputDigest：${delivery.inputDigest}`,`- 构建：${delivery.buildId} / ${delivery.buildDigest}`,`- 浏览器：${latest.report}；实际执行者 ${report.executor}；${report.tool}`,`- 专业模式：${delivery.expertMode} / ${delivery.expert}`,`- 调用核验：${delivery.invocationVerification}；runId：${delivery.runId||'原合同'}；非不可篡改认证。`,`- verification：passed；review：${delivery.review}。本工具不确认或冻结基线。`,`- 待确认问题：${delivery.openQuestions.length?JSON.stringify(delivery.openQuestions):'无新增；仍需用户评审。'}`,end].join('\n');
+    const file=inside(directory,'HANDOFF.md'),previous=fs.existsSync(file)?fs.readFileSync(file,'utf8'):'';
+    const begin=previous.indexOf(start),finish=previous.indexOf(end);
+    assert.ok((begin===-1&&finish===-1)||(begin>=0&&finish>begin&&previous.indexOf(start,begin+1)===-1&&previous.indexOf(end,finish+1)===-1),'Ambiguous generated handoff markers; preserve the user file');
+    const updated=begin===-1?`${previous.trimEnd()}\n\n${block}\n`:`${previous.slice(0,begin)}${block}${previous.slice(finish+end.length)}`;
+    assert.equal(lib.manifest(directory).digest,before.digest,'Candidate changed while finalizing');
+    if(updated!==previous) write(directory,'HANDOFF.md',updated);
+    write(directory,'qa/delivery.json',delivery);
+    return delivery;
+  } finally { lib.release(directory,owner); }
+}
+module.exports={state,finalize};

package/skills/i3-ui-prototype/scripts/native-devtools.cjs

@@ -0,0 +1,92 @@
+'use strict';
+// Checks evidence completeness and current identity, not the truth of a model's
+// claims. Actual Skill/MCP invocation must be checked against the host transcript.
+const F=require('./native-files.cjs');
+const {fs,path,assert,hash,json,inside,write,crypto}=F;
+const zlib=require('node:zlib');
+const KINDS=['dom','screenshot','console','network','accessibility','performance'];
+const METHODS=['evaluate_script','take_screenshot','list_console_messages','list_network_requests','take_snapshot','performance_start_trace','performance_stop_trace'];
+const limitations='Evidence structure, file bytes and current identity checked; verify actual Skill/MCP calls and findings independently in the raw host transcript.';
+function policy(){return {schemaVersion:1,required:true,skill:'i3-browser-testing-with-devtools',provider:'chrome-devtools-mcp',observations:[...KINDS]};}
+function readPolicy(directory){
+ const configured=json(inside(directory,'inputs/acceptance.json')).browserReview;
+ const frameworkFile=inside(directory,'inputs/framework.json');
+ if(fs.existsSync(frameworkFile)){const fixed=json(frameworkFile).acceptance?.browserReview;if(fixed!==undefined)assert.deepEqual(configured,fixed,'DevTools browser review policy differs from its fixed framework input');}
+ if(configured===undefined)return null;
+ assert.equal(configured.schemaVersion,1,'Unknown DevTools review policy');assert.equal(configured.required,true,'DevTools review policy cannot silently opt out');
+ assert.deepEqual(configured.observations,KINDS,'Required DevTools observations changed');assert.equal(configured.skill,policy().skill);assert.equal(configured.provider,'chrome-devtools-mcp');return configured;
+}
+const text=(value,label)=>assert.ok(typeof value==='string'&&value.trim(),`${label} required`);
+const crcTable=Array.from({length:256},(_,value)=>{for(let bit=0;bit<8;bit++)value=(value>>>1)^((value&1)?0xedb88320:0);return value>>>0;});
+function crc32(bytes){let crc=0xffffffff;for(const byte of bytes)crc=(crc>>>8)^crcTable[(crc^byte)&255];return (crc^0xffffffff)>>>0;}
+function verifyPng(bytes){
+ assert.ok(bytes.length>=57&&bytes.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10])),'Complete PNG screenshot required');
+ let offset=8,header=null,ended=false;const image=[];
+ while(offset<bytes.length){
+  assert.ok(offset+12<=bytes.length,'Truncated PNG chunk');const size=bytes.readUInt32BE(offset),end=offset+size+12;assert.ok(end<=bytes.length,'Truncated PNG data');
+  const kind=bytes.toString('ascii',offset+4,offset+8),data=bytes.subarray(offset+8,offset+8+size);assert.equal(crc32(bytes.subarray(offset+4,offset+8+size)),bytes.readUInt32BE(offset+8+size),'Invalid PNG chunk CRC');
+  if(!header){assert.equal(kind,'IHDR','PNG header must be first');assert.equal(size,13,'Invalid PNG IHDR');header=data;}
+  else assert.notEqual(kind,'IHDR','Duplicate PNG header');
+  if(kind==='IDAT')image.push(data);
+  if(kind==='IEND'){assert.equal(size,0,'Invalid PNG end');assert.equal(end,bytes.length,'Trailing PNG bytes');ended=true;break;}offset=end;
+ }
+ assert.ok(ended&&image.length,'PNG needs image data and IEND');
+ const width=header.readUInt32BE(0),height=header.readUInt32BE(4),depth=header[8],channels={0:1,2:3,3:1,4:2,6:4}[header[9]];
+ assert.ok(width&&height&&channels&&[1,2,4,8,16].includes(depth),'Invalid PNG dimensions or color format');assert.equal(header[10],0,'Unsupported PNG compression');assert.equal(header[11],0,'Unsupported PNG filter method');assert.equal(header[12],0,'Expected noninterlaced Chrome screenshot PNG');
+ const stride=Math.ceil(width*channels*depth/8)+1,expected=stride*height;assert.ok(Number.isSafeInteger(expected)&&expected<=64*1024*1024,'PNG decoded image is too large');
+ let pixels;try{pixels=zlib.inflateSync(Buffer.concat(image),{maxOutputLength:64*1024*1024});}catch{throw new Error('Invalid PNG compressed image data');}
+ assert.equal(pixels.length,expected,'Incomplete PNG pixels');for(let row=0;row<height;row++)assert.ok(pixels[row*stride]<=4,'Invalid PNG scanline filter');
+}
+function validate(directory,report,current,build,configured){
+ assert.equal(report.schemaVersion,1);assert.equal(report.status,'passed','DevTools review has not passed');
+ assert.equal(report.revision,current.revision,'DevTools review revision is stale');assert.equal(report.candidateDigest,current.digest,'DevTools review candidate is stale');
+ assert.equal(report.buildId,build.buildId,'DevTools review build is stale');assert.equal(report.buildDigest,build.buildDigest,'DevTools review build bytes differ');
+ text(report.executor,'DevTools executor');const start=Date.parse(report.startedAt),end=Date.parse(report.completedAt);assert.ok(Number.isFinite(start)&&Number.isFinite(end)&&end>=start,'DevTools review timestamps required');
+ const url=new URL(report.previewBaseURL);assert.ok(url.protocol==='http:'&&['127.0.0.1','localhost','[::1]'].includes(url.hostname)&&!url.username&&!url.password,'DevTools preview must be the known local build');
+ assert.equal(report.skill?.name,configured.skill,'Required browser Skill missing');text(report.skill.toolCallId,'Skill tool call ID');text(report.skill.evidence,'Skill host transcript locator');
+ assert.equal(report.mcp?.name,'chrome-devtools-mcp');text(report.mcp.version,'MCP version');text(report.mcp.evidence,'MCP host transcript locator');
+ assert.ok(Array.isArray(report.mcp.calls)&&report.mcp.calls.length,'Actual MCP call locators required');
+ for(const call of report.mcp.calls){assert.ok(typeof call.tool==='string'&&call.tool.startsWith('mcp__'),'Native MCP tool name required');text(call.toolCallId,'MCP tool call ID');}
+ assert.equal(new Set(report.mcp.calls.map(call=>call.toolCallId)).size,report.mcp.calls.length,'Duplicate MCP call IDs');
+ for(const method of METHODS)assert.ok(report.mcp.calls.some(call=>call.tool.endsWith(`__${method}`)),`Missing DevTools method: ${method}`);
+ assert.ok(Array.isArray(report.openItems),'DevTools openItems required');assert.ok(!report.openItems.some(item=>item?.blocking===true),'Blocking DevTools findings remain');
+ const evidenceDigests={},seen=new Set();
+ for(const kind of KINDS){
+  const observed=report.observations?.[kind];assert.equal(observed?.status,'passed',`Missing passed DevTools observation: ${kind}`);text(observed.summary,`${kind} finding`);
+  assert.ok(typeof observed.evidence==='string'&&observed.evidence.startsWith('qa/')&&!seen.has(observed.evidence),'Each DevTools observation needs a distinct QA evidence path');seen.add(observed.evidence);
+  const file=inside(directory,observed.evidence);assert.ok(fs.statSync(file).isFile(),`${kind} evidence is not a file`);const bytes=fs.readFileSync(file);assert.ok(bytes.length&&bytes.length<=64*1024*1024,`${kind} evidence is empty or too large`);
+  if(kind==='screenshot')verifyPng(bytes);
+  if(kind==='performance'){
+   assert.ok(!bytes.subarray(0,2).equals(Buffer.from('PK')),'Playwright ZIP is not a DevTools trace');
+   let trace;try{const decoded=bytes[0]===31&&bytes[1]===139?zlib.gunzipSync(bytes,{maxOutputLength:64*1024*1024}):bytes;trace=JSON.parse(decoded.toString('utf8'));}catch{throw new Error('Parseable DevTools trace JSON required');}
+   const events=Array.isArray(trace)?trace:trace?.traceEvents;assert.ok(Array.isArray(events)&&events.length&&events.some(event=>typeof event.name==='string'),'Nonempty DevTools trace events required');
+  }
+  evidenceDigests[observed.evidence]=hash(bytes);
+ }
+ if(report.evidenceDigests)assert.deepEqual(report.evidenceDigests,evidenceDigests,'DevTools evidence bytes changed');
+ return evidenceDigests;
+}
+function check(directory,lib){
+ try{
+  const configured=readPolicy(directory);if(!configured)return {status:'not-required',required:false};
+  const file=inside(directory,'qa/devtools-review.json');if(!fs.existsSync(file))return {status:'not-run',required:true,missing:[...KINDS],limitations};
+  const report=json(file),current=lib.manifest(directory),build=lib.verifyBuild(directory,report.buildId);
+  const latestFile=inside(directory,'last-build.json');if(fs.existsSync(latestFile))assert.equal(json(latestFile).buildId,report.buildId,'DevTools review is not for the latest build');
+  const browserFile=inside(directory,'qa/latest.json');if(fs.existsSync(browserFile)){const supplemental=json(inside(directory,json(browserFile).report));assert.equal(supplemental.buildId,report.buildId,'DevTools review and browser regression build differ');assert.equal(supplemental.buildDigest,report.buildDigest,'DevTools review and browser regression bytes differ');}
+  const evidenceDigests=validate(directory,report,current,build,configured);assert.ok(report.evidenceDigests,'Recorded DevTools evidence hashes required');
+  return {status:'current',required:true,report:'qa/devtools-review.json',reportDigest:hash(fs.readFileSync(file)),revision:report.revision,candidateDigest:report.candidateDigest,buildId:report.buildId,buildDigest:report.buildDigest,evidenceDigests,invocationVerified:false,limitations};
+ }catch(error){return {status:'failed',required:true,errors:[error.message],limitations};}
+}
+function record(directory,report,lib){
+ const configured=readPolicy(directory);assert.ok(configured,'This fixed input has no DevTools review policy; use its original contract');
+ const current=lib.manifest(directory),build=lib.verifyBuild(directory,report.buildId),copy=JSON.parse(JSON.stringify(report));
+ const latestFile=inside(directory,'last-build.json');if(fs.existsSync(latestFile))assert.equal(json(latestFile).buildId,report.buildId,'DevTools review is not for the latest build');
+ copy.evidenceDigests=validate(directory,copy,current,build,configured);
+ require('./execution-runtime.cjs').requireStage(directory,'browser',lib,{devtoolsReport:copy});
+ const owner=`devtools-${crypto.randomUUID()}`;lib.claim(directory,{owner,expectedRevision:current.revision,expectedDigest:current.digest});
+ try{
+  assert.equal(lib.manifest(directory).digest,current.digest,'Candidate changed during DevTools review');validate(directory,copy,current,lib.verifyBuild(directory,copy.buildId),configured);
+  write(directory,'qa/devtools-review.json',copy);return {status:'passed',report:'qa/devtools-review.json',candidateDigest:current.digest,buildId:copy.buildId,invocationVerified:false,limitations};
+ }finally{lib.release(directory,owner);}
+}
+module.exports={KINDS,policy,readPolicy,validate,check,record};

package/skills/i3-ui-prototype/scripts/native-files.cjs

@@ -0,0 +1,35 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const assert = require('node:assert/strict');
+const hash = value => crypto.createHash('sha256').update(value).digest('hex');
+const json = file => JSON.parse(fs.readFileSync(file,'utf8'));
+const id = value => { assert.match(value || '',/^[a-z0-9]+(?:-[a-z0-9]+)*$/,'Invalid identifier'); return value; };
+function inside(root,relative) {
+  assert.ok(typeof relative==='string' && relative && !path.isAbsolute(relative) && !path.win32.isAbsolute(relative) && !relative.includes('\\') && relative.split('/').every(p=>p && p!=='.' && p!=='..'),'Unsafe prototype path');
+  let current=path.resolve(root);
+  for(const part of relative.split('/')) { current=path.join(current,part); if(fs.existsSync(current)) assert.ok(!fs.lstatSync(current).isSymbolicLink(),'Prototype symlink refused'); }
+  return current;
+}
+function walk(root,prefix='',exclude=()=>false) {
+  const location=prefix?inside(root,prefix):root;
+  if(!fs.existsSync(location)) return [];
+  return fs.readdirSync(location,{withFileTypes:true}).sort((a,b)=>a.name.localeCompare(b.name)).flatMap(entry=>{
+    const relative=prefix?`${prefix}/${entry.name}`:entry.name;
+    if(exclude(relative,entry.name)) return [];
+    assert.ok(!entry.isSymbolicLink(),`Prototype symlink refused: ${relative}`);
+    return entry.isDirectory()?walk(root,relative,exclude):entry.isFile()?[relative]:[];
+  });
+}
+function write(root,relative,value) {
+  const file=inside(root,relative); fs.mkdirSync(path.dirname(file),{recursive:true});
+  const tmp=`${file}.${crypto.randomUUID()}.tmp`;
+  try { fs.writeFileSync(tmp,typeof value==='string'?value:JSON.stringify(value,null,2)+'\n',{flag:'wx'}); fs.renameSync(tmp,file); }
+  finally { if(fs.existsSync(tmp)) fs.unlinkSync(tmp); }
+}
+function entries(root,files) { return Object.fromEntries([...new Set(files)].sort().map(file=>[file,hash(fs.readFileSync(inside(root,file)))])); }
+const cacheRoots = new Set(['node_modules','dist','.vite','.git','coverage',...['app','starter'].flatMap(root=>['node_modules','dist','.vite','.git','coverage'].map(name=>`${root}/${name}`))]);
+// A source/public subdirectory named "dist", or an imported .log file, is still source.
+const excluded = (relative,name) => cacheRoots.has(relative) || name==='.DS_Store' || ['app/tsconfig.tsbuildinfo','starter/tsconfig.tsbuildinfo'].includes(relative);
+module.exports={fs,path,crypto,assert,hash,json,id,inside,walk,write,entries,excluded};