stillmade-sdk 0.1.27 → 0.1.29

package/AGENTS.md

@@ -4,7 +4,7 @@ This folder is the StillMade Block SDK. Read this file before writing code; it i
 
 ## Readiness gate
 
-Do not tell the user a Block is ready, done or working until `node packages/block-cli/cli.js gate .` passes after your last edit, and report the exact status it prints. In this folder Claude Code (`.claude/settings.json`) and Cursor (`.cursor/hooks.json`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.
+Do not tell the user a Block is ready, done or working until `node packages/block-cli/cli.js gate .` passes after your last edit, and report the exact status it prints. In this folder Claude Code (`.claude/settings.json`) and Cursor (`.cursor/hooks.json`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. A module Block runs code, so the gate a hook starts does not run it and says so: run `gate` or `ready` on it yourself. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.
 
 Contract `stillmade.block-builder@1.6.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stillmade-sdk",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "StillMade Block SDK, CLI and examples",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",

package/packages/block-cli/cli.js

@@ -193,8 +193,11 @@ export async function readPackage(path) {
   if(localModule||viewFiles)moduleFiles.set(pkg,{...(localModule?.files||{}),...(viewFiles||{})});
   return pkg;
 }
+export const MODULE_EXECUTION_REQUIRED_MESSAGE='This Block runs code, so the gate a hook starts does not run it. Run `stillmade-block gate .` (`npx stillmade-block gate .` in an npm project) yourself and report the status it prints.';
 export async function main(rawArgs) {
-  const mockRequested=rawArgs.includes('--mock'),args=rawArgs.filter(value=>value!=='--mock');
+  // --no-module-execution: what the gate a hook starts passes to ready, so a module Block is refused
+  // before anything of it runs; the decision is made on the same parsed package ready would run.
+  const mockRequested=rawArgs.includes('--mock'),noModuleExecution=rawArgs.includes('--no-module-execution'),args=rawArgs.filter(value=>value!=='--mock'&&value!=='--no-module-execution');
   if(!args.length||['help','--help','-h'].includes(args[0])||args.includes('--help')||args.includes('-h'))return {help:HELP};
   if(args[0]==='templates'||args[0]==='create'&&args.includes('--list'))return {templates:Object.entries(TEMPLATES).map(([name,template])=>({name,runtime:template.runtime,description:template.description}))};
   const [command, target = '.', extra] = args, path = resolve(target);
@@ -251,7 +254,9 @@ export async function main(rawArgs) {
     // On the creator's own machine a module Block runs in the SDK's Node executor with the
     // stand-in host that answers from tests/mocks.json, as test and preview do (October 20,
     // 2026: ready refused every module Block at DOD-01, so none could pass the gate from the SDK).
-    const mock=pkg.manifest?.runtime==='module'?await standIns(path,pkg,true):null;
+    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;

package/packages/block-cli/ready-gate.js

@@ -82,9 +82,15 @@ export async function sdkBaselineForFiles(files){
 async function readJson(path,fallback){try{return JSON.parse(await readFile(path,'utf8'));}catch{return fallback;}}
 const summarize=readiness=>(readiness?.items||[]).filter(item=>['failed','blocked'].includes(item.state)).slice(0,6).map(item=>`${item.id} ${item.title}: ${String(item.reason||'').slice(0,300)}`);
 
-async function judge(path,main){
+// A module Block's code runs in a Node worker, which is no isolation boundary, so only a gate the
+// person or agent started themselves runs it (`gate`, `ready`); the gate a hook starts at the end
+// of a turn does not, and says so (October 20, 2026).
+export const RUN_READY_YOURSELF='RUN READY YOURSELF';
+async function judge(path,main,{executeModules=true}={}){
  try{
-  const readiness=await main(['ready',path]);
+  // ready decides on the package it would run: with --no-module-execution it refuses a module
+  // Block before anything of it runs (MODULE_EXECUTION_REQUIRED), so the gate never falls open.
+  const readiness=await main(['ready',path,...(executeModules?[]:['--no-module-execution'])]);
   // Every new or edited Block carries its feature map (builder-contract); search, matching and its listing read it.
   const manifest=(await main(['inspect',path]).catch(()=>null))?.manifest;
   // The starting map create writes (one entry copied from the description) does not count until it is rewritten.
@@ -97,6 +103,7 @@ async function judge(path,main){
    try{await main(['test',path]);return {ok:true,status:'PROJECT TYPE TESTS PASSED',failures:[]};}
    catch(typeError){return {ok:false,status:'FAILED',failures:[String(typeError.message).slice(0,300)]};}
   }
+  if(error.code==='MODULE_EXECUTION_REQUIRED')return {ok:false,status:RUN_READY_YOURSELF,failures:[String(error.message).slice(0,400)],limitations:0};
   if(error.code==='APPLICATION_REVIEW_REQUIRED')return {ok:false,status:'NEEDS STILLMADE REVIEW',failures:[String(error.message).slice(0,400)]};
   if(error.report?.status)return {ok:false,status:error.report.status,failures:summarize(error.report)};
   return {ok:false,status:'FAILED',failures:[String(error.message).slice(0,300)]};
@@ -104,7 +111,7 @@ async function judge(path,main){
 }
 
 /** Judge every changed package. Never throws for a failing Block; returns a verdict. */
-export async function runReadyGate({root=process.cwd(),main}={}){
+export async function runReadyGate({root=process.cwd(),main,executeModules=true}={}){
  root=resolve(root);
  main??=(await import('./cli.js')).main;
  const baseline=(await readJson(join(root,SDK_BASELINE_FILE),{packages:{}})).packages||{};
@@ -116,8 +123,10 @@ export async function runReadyGate({root=process.cwd(),main}={}){
   const cached=cache.entries[name];
   // A verdict is reused only for the same package under the same contract: a newer SDK judges again
   // (October 20, 2026: a FAILED verdict from the SDK that could not run module Blocks outlived the fix).
-  const verdict=cached?.digest===digest&&cached?.contract===BUILDER_CONTRACT_STAMP?cached:{digest,contract:BUILDER_CONTRACT_STAMP,...await judge(path,main),checkedAt:new Date().toISOString()};
-  cache.entries[name]=verdict;
+  const verdict=cached?.digest===digest&&cached?.contract===BUILDER_CONTRACT_STAMP?cached:{digest,contract:BUILDER_CONTRACT_STAMP,...await judge(path,main,{executeModules}),checkedAt:new Date().toISOString()};
+  // A verdict the hook could not reach (a module Block it did not run) is not kept: the person's own
+  // gate run judges it, and that verdict then answers the hook too.
+  if(verdict.status!==RUN_READY_YOURSELF)cache.entries[name]=verdict;
   results.push({package:name,...verdict});
  }
  await mkdir(join(root,READY_GATE_STATE),{recursive:true});
@@ -134,7 +143,7 @@ export function gateMessage(verdict){
 /** Hook entry. `agent` is claude, cursor or plain. Returns {exitCode, stdout}. */
 export async function readyGateHook({agent='plain',input={},root,main}={}){
  root=resolve(root||(agent==='cursor'?process.env.CURSOR_PROJECT_DIR||input.workspace_roots?.[0]:process.env.CLAUDE_PROJECT_DIR||input.cwd)||process.cwd());
- const verdict=await runReadyGate({root,main});
+ const verdict=await runReadyGate({root,main,executeModules:false});
  const statePath=join(root,READY_GATE_STATE,'gate-state.json'),state=await readJson(statePath,{});
  if(verdict.passed){
   await writeFile(statePath,'{}\n');

package/packages/block-sdk/builder-contract.js

@@ -152,5 +152,5 @@ export function renderBuilderContract(form='compact',{scope='all'}={}){
   `## Platform gap classes\n\n${Object.entries(GAP_CLASSES).map(([key,label])=>`- ${key}: ${label}`).join('\n')}`,
  ].join('\n\n');
  if(form==='full')return `# StillMade Block builder contract\n\n${body}`;
- return `# Building StillMade Blocks in this folder\n\nThis folder is the StillMade Block SDK. Read this file before writing code; it is the same contract StillMade's own AI and importers follow. Commands below use the downloaded SDK folder form \`node packages/block-cli/cli.js\`; when the SDK came from \`npm install --save-dev stillmade-sdk\`, type \`npx stillmade-block\` in its place. Scaffold with \`node packages/block-cli/cli.js create my-block javascript\`, then iterate with \`validate my-block\` and \`test my-block\`, check admission with \`pack my-block /tmp/my-block.stillmade-block --original\`, and finish with \`ready my-block\`, the same readiness check StillMade runs before an install or a release. \`SDK.md\` is the complete reference and \`PASTE_TO_LLM.md\` the detailed authoring guide.\n\n## Readiness gate\n\nDo not tell the user a Block is ready, done or working until \`node packages/block-cli/cli.js gate .\` passes after your last edit, and report the exact status it prints. In this folder Claude Code (\`.claude/settings.json\`) and Cursor (\`.cursor/hooks.json\`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.\n\n${body}`;
+ return `# Building StillMade Blocks in this folder\n\nThis folder is the StillMade Block SDK. Read this file before writing code; it is the same contract StillMade's own AI and importers follow. Commands below use the downloaded SDK folder form \`node packages/block-cli/cli.js\`; when the SDK came from \`npm install --save-dev stillmade-sdk\`, type \`npx stillmade-block\` in its place. Scaffold with \`node packages/block-cli/cli.js create my-block javascript\`, then iterate with \`validate my-block\` and \`test my-block\`, check admission with \`pack my-block /tmp/my-block.stillmade-block --original\`, and finish with \`ready my-block\`, the same readiness check StillMade runs before an install or a release. \`SDK.md\` is the complete reference and \`PASTE_TO_LLM.md\` the detailed authoring guide.\n\n## Readiness gate\n\nDo not tell the user a Block is ready, done or working until \`node packages/block-cli/cli.js gate .\` passes after your last edit, and report the exact status it prints. In this folder Claude Code (\`.claude/settings.json\`) and Cursor (\`.cursor/hooks.json\`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. A module Block runs code, so the gate a hook starts does not run it and says so: run \`gate\` or \`ready\` on it yourself. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.\n\n${body}`;
 }