stillmade-sdk 0.1.27 → 0.1.28

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.28",
   "description": "StillMade Block SDK, CLI and examples",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",

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

@@ -82,11 +82,16 @@ 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]);
   // 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;
+  if(!executeModules&&manifest?.runtime==='module')return {ok:false,status:RUN_READY_YOURSELF,failures:['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.'],limitations:0};
+  const readiness=await main(['ready',path]);
   // The starting map create writes (one entry copied from the description) does not count until it is rewritten.
   const placeholder=features=>features.length===1&&features[0].id==='main'&&features[0].asks?.length===1&&features[0].asks[0]===features[0].does;
   if(PASSING.has(readiness.status)&&manifest&&!(Array.isArray(manifest.features)&&manifest.features.length&&!placeholder(manifest.features)))
@@ -104,7 +109,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 +121,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 +141,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}`;
 }