stillmade-sdk 0.1.36 → 0.1.38

package/packages/block-cli/cli.js

@@ -36,7 +36,7 @@ import {textGenerate} from '../block-sdk/capability-example.js';
 import {scanPackage} from '../block-sdk/admission.js';
 import {admitLocalPackage} from '../block-sdk/local-admission.js';
 import {requiresDesktopExecution} from '../block-sdk/desktop-execution.js';
-import {digest,validateManifest} from '../block-sdk/contracts.js';
+import {assertStorableText,digest,validateManifest,stableStringify} from '../block-sdk/contracts.js';
 import { testPackage, validatePackage } from '../block-sdk/testing.js';
 import { runPackageAsync } from '../block-sdk/runtime.js';
 import { validateProjectType } from '../block-platform/project-types.js';
@@ -76,20 +76,31 @@ const moduleExecutor=(pkg,host)=>{const files=moduleFiles.get(pkg);return files?
 // Stand-ins for host calls (hosted operations, files, network, connections,
 // storage, project reads): on with --mock, or whenever the folder has
 // tests/mocks.json. They never contact a provider or spend credits.
+const blockFolder=async path=>{try{if((await lstat(path)).isDirectory())return path;}catch{}return null;};
+const localFileReader=folder=>async name=>{
+ if(!folder)throw Object.assign(new Error('Local files are read from a Block folder.'),{code:'MODULE_FILE_READ'});
+ const full=resolve(folder,name);
+ if(!full.startsWith(folder+sep))throw Object.assign(new Error(`${name} is outside the Block folder.`),{code:'MODULE_FILE_READ'});
+ const info=await lstat(full);if(!info.isFile())throw Object.assign(new Error(`${name} is not a file.`),{code:'MODULE_FILE_READ'});
+ return new Uint8Array(await readFile(full));
+};
 async function standIns(path,pkg,requested){
- let mocks,folder=null;
- try{if((await lstat(path)).isDirectory())folder=path;}catch{}
+ let mocks;const folder=await blockFolder(path);
  if(folder){try{mocks=JSON.parse(await readFile(join(folder,MOCKS_FILE),'utf8'));}catch(error){if(error.code!=='ENOENT')throw Object.assign(new Error(`${MOCKS_FILE}: ${error.message}`),{code:'MOCK_HOST'});}}
  if(!requested&&mocks===undefined)return null;
- const readLocalFile=async name=>{
-  if(!folder)throw Object.assign(new Error('Local files are read from a Block folder.'),{code:'MODULE_FILE_READ'});
-  const full=resolve(folder,name);
-  if(!full.startsWith(folder+sep))throw Object.assign(new Error(`${name} is outside the Block folder.`),{code:'MODULE_FILE_READ'});
-  const info=await lstat(full);if(!info.isFile())throw Object.assign(new Error(`${name} is not a file.`),{code:'MODULE_FILE_READ'});
-  return new Uint8Array(await readFile(full));
- };
- return createMockHost({mocks:validateMocks(mocks),readLocalFile,manifest:pkg.manifest});
+ return createMockHost({mocks:validateMocks(mocks),readLocalFile:localFileReader(folder),manifest:pkg.manifest});
+}
+// A module fixture's own mocks take the place of tests/mocks.json for that fixture (MODULES.md), with or
+// without --mock, as ready and StillMade's import review already did (October 27, 2026: test, pack and dev
+// answered every fixture from tests/mocks.json, or left it unanswered when there was none).
+// Returns hostFor(mocks), a fresh stand-in host for one fixture, or null for other runtimes.
+async function fixtureStandIns(path,pkg){
+ if(pkg.manifest?.runtime!=='module')return null;
+ const readLocalFile=localFileReader(await blockFolder(path));
+ return mocks=>createMockHost({mocks:validateMocks(mocks),readLocalFile,manifest:pkg.manifest});
 }
+// A run whose input is a fixture's (dev's Example picker, run without an input file) uses that fixture's mocks.
+const fixtureFor=(pkg,input)=>pkg.manifest?.runtime==='module'?pkg.tests?.find(test=>test?.mocks&&stableStringify(test.input)===stableStringify(input)):undefined;
 // `dev`: preview the folder in StillMade's view host with hot reload. Hosted
 // calls always use stand-ins here; the page runs only on this machine.
 // --live also lets the StillMade site (--site, default STILLMADE_SITE_URL or
@@ -113,7 +124,7 @@ async function dev(path,options){
  }
  if(!(await lstat(path)).isDirectory())throw Object.assign(new Error('dev previews a Block folder.'),{code:'USAGE'});
  const {startDevServer}=await import('./dev-server.js');
- let mock,mocksText,memory;
+ let mock,mocksText,memory,answered;
  const load=async()=>{
   let pkg;
   try{pkg=await readPackage(path);}catch(error){return {problem:`${error.message}${error.code?` (${error.code})`:''}`};}
@@ -128,15 +139,18 @@ async function dev(path,options){
  };
  const run=async(pkg,input)=>{
   const state=pkg.manifest.state?memory??initialBlockState(pkg.manifest):undefined;
-  const result=await runPackageAsync(pkg,input,{...(state?{state}:{}),...(pkg.manifest.runtime==='module'?{module:moduleExecutor(pkg,mock?.host)}:{}),...(pkg.manifest.runtime==='capability'&&mock?{capability:mock.capability}:{})});
+  // The Example picker sends that example's input: unedited, it runs against the example's own mocks.
+  const fixture=fixtureFor(pkg,input),own=fixture?(await fixtureStandIns(path,pkg))(fixture.mocks):null;
+  answered=own?{host:own,files:fixture.mocks.files}:null;
+  const result=await runPackageAsync(pkg,input,{...(state?{state}:{}),...(pkg.manifest.runtime==='module'?{module:moduleExecutor(pkg,(own||mock)?.host)}:{}),...(pkg.manifest.runtime==='capability'&&mock?{capability:mock.capability}:{})});
   if(pkg.manifest.state)memory=result.state;
-  const calls=mock?.calls.splice(0)||[];
+  const calls=own?own.calls.map(call=>({...call,source:call.source==='mocks'?'fixture mocks':call.source})):mock?.calls.splice(0)||[];
   return {outputs:result.outputs,...(result.logs?{logs:result.logs}:{}),...(calls.length?{standIns:calls}:{}),...(result.state!==undefined?{state:result.state}:{})};
  };
  const media=async url=>{
-  const made=mock?.file(url);if(made)return made;
+  const made=answered?.host.file(url)||mock?.file(url);if(made)return made;
   let mocks={};try{mocks=JSON.parse(mocksText||'{}');}catch{}
-  const local=mocks.files?.[url];if(typeof local!=='string')return null;
+  const local=answered?.files?.[url]??mocks.files?.[url];if(typeof local!=='string')return null;
   const full=resolve(path,local);if(!full.startsWith(path+sep))return null;
   try{const bytes=await readFile(full);return {bytes,mediaType:{png:'image/png',jpg:'image/jpeg',jpeg:'image/jpeg',webp:'image/webp',gif:'image/gif',mp4:'video/mp4',webm:'video/webm',mp3:'audio/mpeg',wav:'audio/wav',m4a:'audio/mp4',ogg:'audio/ogg'}[full.split('.').pop().toLowerCase()]||'application/octet-stream'};}catch{return null;}
  };
@@ -149,7 +163,8 @@ async function dev(path,options){
  const liveUrl=link&&`${link.origin}/create/import?live=${encodeURIComponent(`${server.url}/__live/${link.key}`)}`;
  return {dev:server.url,folder:path,...(build?{build}:{}),...(liveUrl?{live:liveUrl}:{}),close:server.close};
 }
-const standInNote=mock=>mock?.calls.length?{standIns:mock.calls.map(call=>({api:call.api,name:call.name,source:call.source==='mocks'?MOCKS_FILE:'recorded stand-in'})),liveVerified:false}:{};
+// own: the hosts that answered fixtures from their own mocks.
+const standInNote=(mock,own=[])=>{const calls=[...(mock?.calls||[]).map(call=>[call,MOCKS_FILE]),...own.flatMap(host=>host.calls.map(call=>[call,'fixture mocks']))];return calls.length?{standIns:calls.map(([call,file])=>({api:call.api,name:call.name,source:call.source==='mocks'?file:'recorded stand-in'})),liveVerified:false}:{};};
 const mobileProfile=()=>({policy:PLATFORM_CHECK_POLICY,targets:PLATFORM_CHECK_TARGETS,themes:PLATFORM_CHECK_THEMES,passed:null,message:'Static SDK validation passed. Import this exact source or run the repository platform runner to complete the trusted embedded UI profile.'});
 export async function readPackage(path) {
   const info = await lstat(path);
@@ -188,7 +203,7 @@ export async function main(rawArgs) {
   }
   if (command === 'create') {
     if(args.length<2)throw Object.assign(new Error('Name the folder to create: stillmade-block create my-block [template]'),{code:'USAGE'});
-    const template=templateNamed(extra),files=await template.files();
+    const template=templateNamed(extra),files=await template.files({folder:path});
     // Every new Block starts with a feature map (one entry from its name and description) for the builder to rewrite as it grows.
     {const created=JSON.parse(files['stillmade.block.json']);if(!created.features&&!created.stages){created.features=blockFeatures(created).map(({source,...feature})=>feature);files['stillmade.block.json']=`${JSON.stringify(created,null,2)}\n`;}}
     // Editors pick up the generated types for the view, src/run.js and module code.
@@ -198,15 +213,18 @@ export async function main(rawArgs) {
     await mkdir(path,{recursive:true});
     const names=['stillmade.block.json',...Object.keys(files).filter(name=>name!=='stillmade.block.json')];
     for(const name of names){await mkdir(dirname(join(path,name)),{recursive:true});await writeFile(join(path,name),files[name],{flag:'wx'});}
-    // Coding agents read command output: restate the readiness rule where they will see it.
-    return { created: path, sdkVersion: '0.1.0', template:template.name, runtime:template.runtime, files:names, next: 'Build the Block and write its feature map (`manifest.features`: one entry per thing it can do), then run `stillmade-block gate .`. Do not call the Block ready until the gate passes; report the status it prints.' };
+    // Coding agents read command output: restate the readiness rule where they will see it, with the folder as it
+    // was typed (October 27, 2026: `gate .` in the folder holding an extracted SDK judged the SDK's examples too).
+    return { created: path, sdkVersion: '0.1.0', template:template.name, runtime:template.runtime, files:names, next: `Build the Block and write its feature map (\`manifest.features\`: one entry per thing it can do), then run \`stillmade-block gate ${/\s/.test(target)?`"${target}"`:target}\`. Do not call the Block ready until the gate passes; report the status it prints.` };
   }
   if (command === 'gate') {
     // Every new or edited Block in a folder must pass readiness before anyone calls it ready.
     const {runReadyGate,gateMessage}=await import('./ready-gate.js');
-    const verdict=await runReadyGate({root:path,main});
-    if(!verdict.passed)throw Object.assign(new Error(gateMessage(verdict)),{code:'READINESS_GATE_FAILED',report:{results:verdict.results}});
-    return {passed:true,checked:verdict.checked,results:verdict.results.map(({package:name,status,limitations})=>({package:name,status,limitations}))};
+    // Each ready this gate runs says how many fixtures ran and passed (a verdict reused for unchanged content has no count).
+    const counts=new Map(),judge=async gateArgs=>{try{const result=await main(gateArgs);if(gateArgs[0]==='ready')counts.set(gateArgs[1],result?.fixtures);return result;}catch(error){if(gateArgs[0]==='ready')counts.set(gateArgs[1],error.report?.fixtures);throw error;}};
+    const verdict=await runReadyGate({root:path,main:judge}),counted=result=>{const fixtures=counts.get(resolve(path,result.package));return fixtures?{fixtures}:{};};
+    if(!verdict.passed)throw Object.assign(new Error(gateMessage(verdict)),{code:'READINESS_GATE_FAILED',report:{results:verdict.results.map(result=>({...result,...counted(result)}))}});
+    return {passed:true,checked:verdict.checked,results:verdict.results.map(({package:name,status,limitations})=>({package:name,status,limitations,...counted({package:name})}))};
   }
   if(command==='run')return main(['preview',...args.slice(1),...(mockRequested?['--mock']:[])]);
   if(command==='dev')return dev(path,args.slice(2));
@@ -237,10 +255,15 @@ export async function main(rawArgs) {
     // 2026: ready refused every module Block at DOD-01, so none could pass the gate from the SDK).
     const module=pkg.manifest?.runtime==='module';
     if(module&&noModuleExecution)throw Object.assign(new Error(MODULE_EXECUTION_REQUIRED_MESSAGE),{code:'MODULE_EXECUTION_REQUIRED'});
-    const mock=module?await standIns(path,pkg,true):null;
-    const readiness=await assessBlockReadiness(pkg,{moduleExecution:true,files:moduleFiles.get(pkg),...(mock?{host:mock.host}:{})});
-    if(['FAILED','BLOCKED BY PLATFORM CAPABILITY'].includes(readiness.status))throw Object.assign(new Error(`Block readiness: ${readiness.status}`),{report:readiness});
-    return readiness;
+    const mock=module?await standIns(path,pkg,true):null,hostFor=await fixtureStandIns(path,pkg),files=moduleFiles.get(pkg);
+    // Admission runs first, exactly as readiness would run it, so the report can say how many fixtures ran
+    // and passed (October 27, 2026); readiness keeps its own budget (20 s by default) for both.
+    const started=Date.now();let admission;
+    try{admission=await admitLocalPackage(pkg,{moduleExecution:true,files,...(mock?{host:mock.host}:{}),...(hostFor?{hostFor:mocks=>hostFor(mocks).host}:{})});}catch{}
+    const readiness=await assessBlockReadiness(pkg,{moduleExecution:true,files,...(mock?{host:mock.host}:{}),...(admission?{admission,budgetMs:Math.max(1000,20000-(Date.now()-started))}:{})});
+    const report={...readiness,...(admission?{fixtures:fixtureCounts(pkg,admission)}:{})};
+    if(['FAILED','BLOCKED BY PLATFORM CAPABILITY'].includes(readiness.status))throw Object.assign(new Error(`Block readiness: ${readiness.status}`),{report});
+    return report;
   }
   if(command==='remix'){
     const result=await remixBlock(pkg);
@@ -252,6 +275,8 @@ export async function main(rawArgs) {
     return {file:output,parent:result.parent,digest:await digest(result.content),draft:true,validated:false,message:'Editable remix created. Run validate and test before packaging a release. No source code was executed by remix.'};
   }
 
+  // StillMade cannot store text with a NUL character; say where it is before the author imports the package.
+  if(['validate','test','pack','ready'].includes(command))assertStorableText(pkg);
   if (pkg.stages) {
     const valid = validateProjectType(pkg, BUILTIN_BLOCKS);
     if (!valid.valid) throw new Error(valid.errors.map(e => e.message).join('. '));
@@ -332,10 +357,11 @@ export async function main(rawArgs) {
       if(saved.packageDigest!==sourceDigest)throw Error('Saved memory belongs to another Block build');
       state=validateBlockState(pkg.manifest,saved.state);
     }
-    const mock=await standIns(path,pkg,mockRequested);
-    const result=await runPackageAsync(pkg,inputPath?JSON.parse(await readFile(resolve(inputPath),'utf8')):pkg.tests[0].input,{...(state?{state}:{}),...(pkg.manifest.runtime==='module'?{module:moduleExecutor(pkg,mock?.host)}:{}),...(pkg.manifest.runtime==='capability'&&mock?{capability:mock.capability}:{})});
+    const mock=await standIns(path,pkg,mockRequested),input=inputPath?JSON.parse(await readFile(resolve(inputPath),'utf8')):pkg.tests[0].input;
+    const fixture=fixtureFor(pkg,input),own=fixture?(await fixtureStandIns(path,pkg))(fixture.mocks):null;
+    const result=await runPackageAsync(pkg,input,{...(state?{state}:{}),...(pkg.manifest.runtime==='module'?{module:moduleExecutor(pkg,(own||mock)?.host)}:{}),...(pkg.manifest.runtime==='capability'&&mock?{capability:mock.capability}:{})});
     if(savePath)await writeFile(resolve(savePath),JSON.stringify({packageDigest:sourceDigest,state:validateBlockState(pkg.manifest,result.state)},null,2),{flag:'wx'});
-    return {...result,...standInNote(mock)};
+    return {...result,...(own?standInNote(null,[own]):standInNote(mock))};
   }
   if(requiresDesktopExecution(pkg)&&['test','pack'].includes(command)){
     const report=await admitLocalPackage(pkg);if(!report.passed)throw Object.assign(new Error('Desktop source admission failed'),{report});
@@ -351,29 +377,59 @@ export async function main(rawArgs) {
     await writeFile(output,JSON.stringify(pkg,null,2),{flag:'wx'});
     return {file:output,digest:await digest(pkg),tests:0,reviewRequired:true,...(pkg.manifest.runtime==='capability'?{liveVerified:false}:{}),message:pkg.manifest.runtime==='capability'?'Source packaged without provider execution. Import into StillMade, choose a model and payment method, and approve the fixtures and sample before confirming installation.':'Source packaged. Import into StillMade to run all fixtures and preview on your connected ComfyUI backend before confirming installation.'};
   }
-  const mock=['module','capability'].includes(pkg.manifest.runtime)?await standIns(path,pkg,mockRequested):null;
+  const mock=['module','capability'].includes(pkg.manifest.runtime)?await standIns(path,pkg,mockRequested):null,hostFor=await fixtureStandIns(path,pkg),own=[];
   let report;
   if(pkg.manifest.runtime==='capability'&&mock){
    // Checks on the model's words are listed rather than run against a stand-in.
    const {pkg:checked,notChecked}=standInFixtures(pkg);
    report={...await testPackage(checked,{capability:mock.capability}),digest:await digest(pkg),execution:'stand-ins',liveVerified:false,reviewRequired:true,...(notChecked.length?{notChecked}:{})};
-  }else report = await testPackage(pkg,pkg.manifest.runtime==='module'?{module:moduleExecutor(pkg,mock?.host),timeoutMs:MODULE_LIMITS.wallClockMs}:{});
-  Object.assign(report,standInNote(mock));
+  }else if(pkg.manifest.runtime==='module'){
+   const module=moduleExecutor(pkg,mock?.host);
+   const moduleFor=module&&(test=>{if(!test?.mocks)return module;const host=hostFor(test.mocks);own.push(host);return moduleExecutor(pkg,host.host);});
+   report=await testPackage(pkg,{module,...(moduleFor?{moduleFor}:{}),timeoutMs:MODULE_LIMITS.wallClockMs});
+  }else report = await testPackage(pkg,{});
+  Object.assign(report,standInNote(mock,own));
   if (!report.passed) throw Object.assign(new Error('Fixture tests failed'), { report });
   if (command === 'test') return report;
   if (hasDigestFiles(pkg)) {
     const files=moduleFiles.get(pkg),output=resolve(extra || `${pkg.manifest.id}-${pkg.manifest.version}${MODULE_BUNDLE_SUFFIX}`);
     if(!output.endsWith(MODULE_BUNDLE_SUFFIX))throw new Error(`Module output must end in ${MODULE_BUNDLE_SUFFIX}`);
     await writeFile(output,JSON.stringify(createModuleBundle(pkg,files)),{flag:'wx'});
-    return {file:output,digest:report.digest,tests:report.results.length,files:Object.keys(pkg.module?.files||{}).length+Object.keys(pkg.view?.files?.files||{}).length,...standInNote(mock),message:'Import this bundle in StillMade (Create, then Import). StillMade checks every file digest and uploads the files once before saving the Block.'};
+    return {file:output,digest:report.digest,tests:report.results.length,files:Object.keys(pkg.module?.files||{}).length+Object.keys(pkg.view?.files?.files||{}).length,...standInNote(mock,own),message:'Import this bundle in StillMade (Create, then Import). StillMade checks every file digest and uploads the files once before saving the Block.'};
   }
   const output = jsonOutput(extra,`${pkg.manifest.id}-${pkg.manifest.version}.stillmade.json`);
   await writeFile(output, JSON.stringify(pkg, null, 2), { flag: 'wx' });
   return { file: output, digest: report.digest, tests: report.results.length };
 }
+// How many fixtures admission ran and passed, for the ready and gate reports.
+function fixtureCounts(pkg,admission){
+ const rows=(admission.results||[]).filter(row=>/ contract test: /.test(row.name)),failed=rows.filter(row=>!row.passed);
+ return {total:pkg.tests?.length||0,ran:rows.length,passed:rows.length-failed.length,...(admission.execution?{execution:admission.execution}:{}),...(failed.length?{failed:failed.slice(0,10).map(row=>({name:row.name.replace(/^.*? contract test: /,''),message:String(row.message||row.code||'failed').slice(0,300)}))}:{})};
+}
+// Readable ready and gate results, which format.js prints as JSON (October 27, 2026: --text printed JSON): the
+// verdict, how many fixtures ran and passed, then what failed and what is not verified.
+const plural=(count,word)=>`${count} ${word}${count===1?'':'s'}`;
+const fixtureText=fixtures=>fixtures.ran?`${fixtures.passed} of ${plural(fixtures.total,'fixture')} passed`:`${plural(fixtures.total,'fixture')} not run here`;
+const readinessLines=report=>{
+ const failed=(report.items||[]).filter(item=>['failed','blocked'].includes(item.state));
+ return [report.fixtures?`${fixtureText(report.fixtures)}.`:null,...(report.fixtures?.failed||[]).map(item=>`  FAIL  ${item.name}: ${item.message}`),report.fixtures?.execution==='local-stand-ins'?'Hosted calls were answered by each fixture\'s own mocks, else tests/mocks.json, else stand-ins. No provider was called.':null,
+  failed.length?'Failed:':null,...failed.map(item=>`  ${item.id} ${item.title}: ${item.reason}`),report.limitations?.length?`Not verified (${report.limitations.length}):`:null,...(report.limitations||[]).map(line=>`  ${line}`)].filter(Boolean);
+};
+const gateLines=results=>results.map(result=>`  ${result.package}: ${result.status}${result.fixtures?`, ${fixtureText(result.fixtures)}`:''}${result.limitations?`, ${result.limitations} not verified`:''}`);
+export function readinessText(command,result){
+ if(command==='ready'&&Array.isArray(result?.items))return `${[`Readiness: ${result.status}`,...readinessLines(result)].join('\n')}\n`;
+ if(command==='gate'&&Array.isArray(result?.results))return `${[result.checked?`Readiness gate passed: ${plural(result.checked,'Block')} checked.`:'Readiness gate passed: no new or edited Blocks to check.',...gateLines(result.results)].join('\n')}\n`;
+ return null;
+}
+export function readinessErrorText(command,error){
+ const report=error?.report,head=`Error: ${error?.message||error}${error?.code?` (${error.code})`:''}`;
+ if(command==='ready'&&Array.isArray(report?.items))return `${[head,...readinessLines(report)].join('\n')}\n`;
+ if(command==='gate'&&Array.isArray(report?.results))return `${[head,'Checked:',...gateLines(report.results)].join('\n')}\n`;
+ return null;
+}
 if (process.argv[1] && (()=>{try{return realpathSync(process.argv[1])===fileURLToPath(import.meta.url);}catch{return false;}})()) {
   // Readable text in a terminal; the JSON result object when piped (scripts,
   // coding agents) or with --json. --text forces readable text.
   const argv=process.argv.slice(2),asJson=argv.includes('--json')||!process.stdout.isTTY&&!argv.includes('--text'),args=argv.filter(value=>!['--json','--text'].includes(value));
-  main(args).then(result => process.stdout.write(asJson?`${JSON.stringify(result, null, 2)}\n`:formatResult(args,result))).catch(error => { process.stderr.write(asJson?`${JSON.stringify({ error: error.message, code: error.code, report: error.report })}\n`:formatError(error)); process.exitCode = 1; });
+  main(args).then(result => process.stdout.write(asJson?`${JSON.stringify(result, null, 2)}\n`:readinessText(args[0],result)??formatResult(args,result))).catch(error => { process.stderr.write(asJson?`${JSON.stringify({ error: error.message, code: error.code, report: error.report })}\n`:readinessErrorText(args[0],error)??formatError(error)); process.exitCode = 1; });
 }