stillmade-sdk 0.1.47 → 0.1.48

package/packages/block-cli/format.js

@@ -10,6 +10,15 @@ Start
   create <folder> [template]   Start a Block from a template (create --list shows all)
   create-type <file.json>      Start a Project Type
 
+Several Blocks in one folder (a workspace)
+  init <folder> [--name "Listing kit"]  Start a workspace: blocks/, shared/, workflows/ and the agent guides
+  add <name> [template]        Add blocks/<name> from a template (--app gmail with the connector template)
+  add-type <name> [block ...]  Add workflows/<name>.json, a Project Type made of the workspace's Blocks
+                               (--when schedule starts it with StillMade's When Step: an automation)
+  build                        Join src/main.js and shared/ code into each module Block's module/main.js
+  From the workspace folder, dev, test, validate, gate and pack cover every Block and workflow in it;
+  pack writes one .stillmade-pack file for StillMade's Import.
+
 Build and check
   validate [folder]            Check the manifest, source and interface (--mobile adds the phone profile)
   test [folder]                Run tests/fixtures.json
@@ -69,6 +78,13 @@ export function formatResult(args,result){
   const width=Math.max(...result.templates.map(item=>item.name.length));
   return lines('Templates (stillmade-block create <folder> <template>):','',...result.templates.map(item=>`  ${item.name.padEnd(width)}  ${item.description}`));
  }
+ // A workspace's own results (workspace.js).
+ if(command==='init'&&result?.kind==='workspace')return lines(`Started the workspace "${result.name}" in ${result.created}.`,'',`Next:`,`  cd ${result.created}`,'  npm install',`  npx stillmade-block add <name> [template]`,'  npx stillmade-block dev');
+ if(command==='add'&&result?.block)return lines(`Added blocks/${result.block} from the ${result.template} template.`,result.source?`Edit its code in blocks/${result.block}/${result.source} only: module/main.js is a copy that build, test, gate and pack write from it.`:null,'A running preview picks it up.');
+ if(command==='add-type'&&result?.kind==='workflow')return lines(`Added ${relative(process.cwd(),result.created)||result.created}: ${result.steps.join(' -> ')}, ${result.connections} ${result.connections===1?'connection':'connections'} where the ports agree.`,result.next);
+ if(command==='build'&&result?.workspace)return lines(result.built.length?`Built ${result.built.join(', ')}.`:'Nothing to build: every module/main.js is current.',...Object.entries(result.shared||{}).filter(([,files])=>files.length).map(([block,files])=>`  ${block} uses shared/${files.join(', shared/')}`));
+ if(result?.workspace&&Array.isArray(result.results)&&result.command)return lines(`${result.results.length} of ${result.results.length} passed ${result.command}.`,...result.results.map(item=>`  PASS  ${item.item}${item.tests!==undefined?` (${item.tests} ${item.tests===1?'test':'tests'})`:''}`));
+ if(command==='pack'&&result?.pack)return lines(`Wrote ${result.pack} (${result.items.filter(item=>item.kind!=='workflow').length} Blocks, ${result.items.filter(item=>item.kind==='workflow').length} ${result.items.filter(item=>item.kind==='workflow').length===1?'workflow':'workflows'}).`,...result.items.map(item=>`  ${item.kind.padEnd(10)} ${item.id}@${item.version}`),'Import it in StillMade: Create, then Import. StillMade asks which ones to bring in.');
  if((command==='create'||command==='create-type')&&result?.created){
   if(result.kind==='type')return lines(`Created a Project Type at ${result.created}.`);
   const cli=cliCommand(result.created);
@@ -99,7 +115,10 @@ export function formatResult(args,result){
 export function formatError(error){
  const out=[`Error: ${error?.message||error}${error?.code?` (${error.code})`:''}`];
  const report=error?.report;
- if(Array.isArray(report?.results)){
+ if(report?.workspace&&Array.isArray(report.results)){
+  for(const item of report.results)out.push(item.passed?`  PASS  ${item.item}`:`  FAIL  ${item.item}: ${indent(item.message||'failed','        ').trimStart()}`);
+ }else if(Array.isArray(report?.failed)&&report.failed.length&&error?.code==='BUILD')out.push(...report.failed.map(item=>`  ${item.block}: ${item.message}`));
+ else if(Array.isArray(report?.results)){
   for(const item of report.results)out.push(item.passed?`  PASS  ${item.name}`:`  FAIL  ${item.name}: ${item.message||item.code||'failed'}`);
   out.push(...notes(report));
  }else if(Array.isArray(report?.findings))out.push(...report.findings.map(item=>`  ${item.message||pretty(item)}`));

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

@@ -128,6 +128,33 @@ async function judge(path,main,{executeModules=true}={}){
  }
 }
 
+async function workspaceGate(root){
+ const empty={workflows:[],problems:new Map(),blocksDigest:''};
+ const {isWorkspaceRoot,workspaceItems,buildWorkspace,unbundledImport}=await import('./workspace.js');
+ if(!(await isWorkspaceRoot(root)))return empty;
+ const problems=new Map();
+ let build={failed:[]};
+ try{build=await buildWorkspace(root);}catch(error){const {blocks}=await workspaceItems(root);for(const item of blocks)if(item.source)problems.set(item.path,error.message);}
+ const {blocks,workflows}=await workspaceItems(root);
+ for(const item of blocks){
+  const failed=build.failed.find(entry=>entry.block===item.name);if(failed){problems.set(item.path,`Build failed: ${failed.message}`);continue;}
+  const loose=await unbundledImport(item.path);if(loose)problems.set(item.path,`${loose.file} imports ${loose.specifier}. A Block runs one file: keep the code in src/main.js and run \`stillmade-block build\`.`);
+ }
+ return {workflows:workflows.map(item=>item.path),problems,blocksDigest:await blocksDigest(blocks)};
+}
+async function blocksDigest(blocks){const digests=[];for(const item of blocks){try{digests.push(item.name,await packageDigest(item.path));}catch{}}return sha256(digests.join('\0'));}
+/** The digest the gate keys each workspace item's verdict by ({'blocks/x': digest, 'workflows/y.json': digest}), and the cached verdicts. */
+export async function workspaceVerdicts(root){
+ const {workspaceItems}=await import('./workspace.js');
+ const {blocks,workflows}=await workspaceItems(root),digests={},all=await blocksDigest(blocks);
+ for(const item of blocks){try{digests[posix(relative(root,item.path))]=await packageDigest(item.path);}catch{}}
+ for(const item of workflows){try{digests[posix(relative(root,item.path))]=sha256(String(await packageDigest(item.path))+all);}catch{}}
+ const cache=await readJson(join(root,READY_GATE_STATE,'ready-cache.json'),{entries:{}});
+ const verdicts={};
+ for(const [name,digest] of Object.entries(digests)){const entry=cache.entries?.[name];verdicts[name]=entry?{current:entry.digest===digest&&entry.contract===BUILDER_CONTRACT_STAMP,ok:!!entry.ok,status:entry.status,failures:entry.failures||[],checkedAt:entry.checkedAt}:null;}
+ return verdicts;
+}
+
 /** Judge every changed package. Never throws for a failing Block; returns a verdict. */
 export async function runReadyGate({root=process.cwd(),main,executeModules=true}={}){
  root=resolve(root);
@@ -135,8 +162,13 @@ export async function runReadyGate({root=process.cwd(),main,executeModules=true}
  const baselines=new Map();
  const cachePath=join(root,READY_GATE_STATE,'ready-cache.json'),cache=await readJson(cachePath,{version:1,entries:{}});
  const results=[];
- for(const path of await findPackages(root)){
-  const name=posix(relative(root,path)),digest=await packageDigest(path);
+ // A workspace (workspace.js): module Blocks are built from src/main.js first, and its workflows are judged too,
+ // each against the Blocks it names, so a changed Block judges its workflows again.
+ const workspace=await workspaceGate(root),packages=[...await findPackages(root),...workspace.workflows];
+ for(const path of packages){
+  const name=posix(relative(root,path)),digest=workspace.workflows.includes(path)?sha256(String(await packageDigest(path))+workspace.blocksDigest):await packageDigest(path);
+  const early=workspace.problems.get(path);
+  if(early){results.push({package:name,digest,ok:false,status:'FAILED',failures:[early],limitations:0});continue;}
   if(await shippedDigest(root,path,baselines)===digest)continue;
   const cached=cache.entries[name];
   // A verdict is reused only for the same package under the same contract: a newer SDK judges again

package/packages/block-cli/templates.js

@@ -222,6 +222,58 @@ export default async function run(input, stillmade) {
   return { title: (title?.title || []).map((part) => part.plain_text || '').join('').trim() || 'Untitled page' };
 }
 `;
+// Connector examples: the action StillMade's connections service names for each app (packages/block-platform/automation-templates.js
+// uses the same names), what it takes, and an answer recorded for offline tests.
+const connectorApp=value=>{const app=String(value||'gmail').toLowerCase().replace(/^app:/,'');if(!/^[a-z0-9][a-z0-9-]{0,79}$/.test(app))throw Object.assign(new Error('--app takes an app name, such as gmail, slack or notion.'),{code:'USAGE'});return app;};
+const CONNECTOR_EXAMPLES={
+ gmail:{label:'Gmail',name:'Gmail digest',operation:'GMAIL_FETCH_EMAILS',action:{label:'Make digest',running:'Reading your email…'},description:'Lists the subjects and senders of the emails that match a search.',
+  inputs:{query:{type:'text',primary:true,required:true,semantic:'email_search',description:'A Gmail search, such as from:listings newer_than:1d.'}},outputs:{digest:{type:'text',primary:true,semantic:'email_digest',description:'One line per email: the subject and who sent it.'}},ui:[{control:'text',port:'query',label:'Search'}],
+  code:`// Runs Gmail's GMAIL_FETCH_EMAILS action with the account the person connected. Locally, tests/mocks.json answers.
+export default async function run(input, stillmade) {
+  const result = await stillmade.connections.call('app:gmail', 'GMAIL_FETCH_EMAILS', { query: input.query, max_results: 10 });
+  const messages = result?.messages || result?.data?.messages || [];
+  const lines = messages.map((message) => \`\${message.subject || '(no subject)'} · \${message.sender || message.from || 'unknown sender'}\`);
+  return { digest: lines.length ? lines.join('\\n') : 'No emails match this search.' };
+}
+`,test:'Two emails',input:{query:'from:listings newer_than:1d'},answer:{messages:[{subject:'Price drop: 22 Ridge Rd',sender:'alerts@listings.example'},{subject:'New listing: 1418 Juniper Lane',sender:'alerts@listings.example'}]},
+  expected:{digest:'Price drop: 22 Ridge Rd · alerts@listings.example\nNew listing: 1418 Juniper Lane · alerts@listings.example'}},
+ slack:{label:'Slack',name:'Slack post',operation:'SLACK_SEND_MESSAGE',action:{label:'Post message',running:'Posting to Slack…'},description:'Posts a message to a Slack channel.',
+  inputs:{channel:{type:'text',required:true,semantic:'slack_channel',description:'The channel, such as #listings.'},text:{type:'text',primary:true,required:true,semantic:'message_text',description:'What to post.'}},outputs:{posted:{type:'text',primary:true,semantic:'confirmation',description:'Where the message went.'}},ui:[{control:'text',port:'channel'},{control:'text',port:'text'}],
+  code:`// Runs Slack's SLACK_SEND_MESSAGE action with the account the person connected. Locally, tests/mocks.json answers.
+export default async function run(input, stillmade) {
+  const result = await stillmade.connections.call('app:slack', 'SLACK_SEND_MESSAGE', { channel: input.channel, text: input.text });
+  return { posted: result?.ok === false ? 'Slack did not post the message.' : \`Posted to \${input.channel}\` };
+}
+`,test:'Posts',input:{channel:'#listings',text:'22 Ridge Rd dropped 3%.'},answer:{ok:true},expected:{posted:'Posted to #listings'}},
+ notion:{label:'Notion',name:'Notion page',operation:'NOTION_CREATE_NOTION_PAGE',action:{label:'Add page',running:'Adding the page…'},description:'Adds a page with a title under a Notion page.',
+  inputs:{parent:{type:'text',required:true,semantic:'notion_page_id',description:'The Notion page to add it under.'},title:{type:'text',primary:true,required:true,semantic:'page_title',description:'The new page\'s title.'}},outputs:{page:{type:'text',primary:true,semantic:'notion_page_id',description:'The new page.'}},ui:[{control:'text',port:'parent'},{control:'text',port:'title'}],
+  code:`// Runs Notion's NOTION_CREATE_NOTION_PAGE action with the account the person connected. Locally, tests/mocks.json answers.
+export default async function run(input, stillmade) {
+  const result = await stillmade.connections.call('app:notion', 'NOTION_CREATE_NOTION_PAGE', { parent_id: input.parent, title: input.title });
+  return { page: result?.id || result?.data?.id || '' };
+}
+`,test:'Adds a page',input:{parent:'b1b2c3d4e5f60718293a4b5c6d7e8f90',title:'Listing notes'},answer:{id:'c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4'},expected:{page:'c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4'}},
+ googlesheets:{label:'Google Sheets',name:'Sheet rows',operation:'GOOGLESHEETS_GET_ROWS',action:{label:'Read rows',running:'Reading the sheet…'},description:'Reads the rows of a Google Sheet.',
+  inputs:{sheet:{type:'text',primary:true,required:true,semantic:'spreadsheet_id',description:'The spreadsheet ID from its address.'}},outputs:{rows:{type:'json',primary:true,semantic:'table_rows',description:'The rows, each a list of cell values.'}},ui:[{control:'text',port:'sheet'}],
+  code:`// Runs Google Sheets' GOOGLESHEETS_GET_ROWS action with the account the person connected. Locally, tests/mocks.json answers.
+export default async function run(input, stillmade) {
+  const result = await stillmade.connections.call('app:googlesheets', 'GOOGLESHEETS_GET_ROWS', { spreadsheet_id: input.sheet });
+  return { rows: result?.values || result?.data?.values || [] };
+}
+`,test:'Two rows',input:{sheet:'1AbCdEfGhIjKlMnOpQrStUvWxYz'},answer:{values:[['Address','Price'],['22 Ridge Rd','$412,000']]},expected:{rows:[['Address','Price'],['22 Ridge Rd','$412,000']]}},
+};
+function genericConnector(app){
+ const label=app[0].toUpperCase()+app.slice(1),operation=`${app.toUpperCase().replace(/-/g,'_')}_ACTION_NAME`;
+ return {generic:true,label,name:`${label} action`,operation,action:{label:`Run ${label} action`,running:`Running the ${label} action…`},description:`Runs one ${label} action with the person's connected account.`,
+  inputs:{request:{type:'object',primary:true,required:true,semantic:'action_input',description:`What the ${label} action takes.`}},outputs:{result:{type:'object',primary:true,semantic:'action_result',description:`What ${label} answered.`}},ui:[],
+  code:`// Runs one ${label} action with the account the person connected. Put the action's name from the app's list of actions
+// in place of ${operation}, here and in tests/mocks.json. Locally, tests/mocks.json answers.
+export default async function run(input, stillmade) {
+  const result = await stillmade.connections.call('app:${app}', '${operation}', input.request);
+  return { result: result && typeof result === 'object' ? result : { value: result } };
+}
+`,test:'Answers',input:{request:{}},answer:{ok:true},expected:{result:{ok:true}}};
+}
 const STORAGE=`// A module Block that remembers settings in the project's Block storage
 // (manifest storage.cloud "metered"). Values persist across runs, devices and
 // new versions of the Block. Locally, storage is kept in memory per run.
@@ -283,6 +335,15 @@ const STARTERS={
    'tests/mocks.json':json({connections:{'app:openapi:notion/retrievePage':{object:'page',properties:{Name:{type:'title',title:[{plain_text:'Launch plan'}]}}}}}),
    'README.md':readme(pkg.name,'A module Block that calls a published adapter. People sign in once per Block; tests/mocks.json records the adapter\'s answers for offline tests.',HOSTED,options)};
  }},
+ // A Block of the person's own that calls a signed-in catalog app (Gmail, Slack, Notion, Google Sheets...) by its action
+ // name (owner, November 6, 2026: connector Blocks in a workspace). `add <name> connector --app gmail`.
+ connector:{description:'Call a signed-in app (Gmail, Slack, Notion, Google Sheets...) by its action name; --app picks the app.',runtime:'module',files:async options=>{
+  const app=connectorApp(options?.app),example=CONNECTOR_EXAMPLES[app]||genericConnector(app);
+  const pkg=manifest({id:`example.${app}-connector`,action:example.action,version:'1.0.0',name:example.name,description:example.description,runtime:'module',inputs:example.inputs,outputs:example.outputs,permissions:{connections:[`app:${app}`]},ui:example.ui});
+  return {'stillmade.block.json':json(pkg),'module/main.js':example.code,'tests/fixtures.json':json([{name:example.test,input:example.input,expected:example.expected}]),
+   'tests/mocks.json':json({connections:{[`app:${app}/${example.operation}`]:example.answer}}),
+   'README.md':readme(pkg.name,`A module Block that runs ${example.label}'s ${example.operation} action with the account the person connects in StillMade. It asks them to connect ${example.label} on its first run and shows the price of each action before it runs; the account never reaches the Block. tests/mocks.json records the app's answer for offline tests.${example.generic?` ${example.operation} is a placeholder: put the action name from the app's list of actions in module/main.js and tests/mocks.json.`:''}`,HOSTED,options)};
+ }},
  storage:{description:'Remember values across runs in the project\'s Block storage.',runtime:'module',files:async options=>{
   const pkg=manifest({id:'example.remember-settings',action:{label:'Save settings',running:'Saving settings…'},version:'1.0.0',name:'Remember settings',description:'Keeps a name and a run count in project storage.',runtime:'module',storage:{schemaVersion:1,scope:'project',desktop:'device-unmetered',cloud:'metered'},inputs:{name:{type:'text',primary:true,required:false,semantic:'person_name',description:'A name to remember.'}},outputs:{greeting:{type:'text',primary:true,semantic:'greeting',description:'A greeting with the run count.'}},ui:[{control:'text',port:'name'}]});
   return {'stillmade.block.json':json(pkg),'module/main.js':STORAGE,'tests/fixtures.json':json([{name:'First run',input:{name:'Ada'},expected:{greeting:'Hello Ada, run 1'}}]),'tests/mocks.json':json({storage:{}}),'README.md':readme(pkg.name,'A module Block with project storage. tests/mocks.json can seed stored values under "storage".',OFFLINE,options)};

package/packages/block-cli/type-packages.js

@@ -85,23 +85,26 @@ const sourceFiles=pkg=>{
  * mocks when it records some, else by the stand-ins with --mock. No provider is ever called.
  * Returns {test, run} for testProjectType/previewProjectType and calls() for the report.
  */
-export function typeModuleRunner({mock=false,readLocalFile}={}){
+// mocksFor(pkg): the Block's own recorded answers (a workspace Block's tests/mocks.json), used before --mock's stand-ins.
+export function typeModuleRunner({mock=false,readLocalFile,mocksFor=()=>undefined}={}){
  const hosts=[];
  const hostFor=(pkg,mocks,source)=>{const host=createMockHost({mocks:validateMocks(mocks),readLocalFile,manifest:pkg.manifest});hosts.push({host,source});return host.host;};
  const executor=(pkg,host)=>createNodeModuleExecutor({files:sourceFiles(pkg),...(host?{host}:{})});
  const test=(pkg,options={})=>{
   if(pkg.manifest.runtime!=='module')return testPackage(pkg,options);
-  const module=executor(pkg,mock?hostFor(pkg,undefined,'recorded stand-in'):undefined);
+  const own=mocksFor(pkg),module=executor(pkg,own?hostFor(pkg,own,'tests/mocks.json'):mock?hostFor(pkg,undefined,'recorded stand-in'):undefined);
   return testPackage(pkg,{...options,module,moduleFor:fixture=>fixture?.mocks?executor(pkg,hostFor(pkg,fixture.mocks,'fixture mocks')):module,timeoutMs:Math.min(options.timeoutMs??MODULE_LIMITS.wallClockMs,MODULE_LIMITS.wallClockMs)});
  };
  const run=(pkg,input,options={})=>{
   if(pkg.manifest.runtime!=='module')return runPackageAsync(pkg,input,options);
   const recorded=pkg.tests?.find(fixture=>fixture?.mocks)?.mocks;
-  const host=recorded?hostFor(pkg,recorded,'fixture mocks'):mock?hostFor(pkg,undefined,'recorded stand-in'):undefined;
+  const own=mocksFor(pkg),host=recorded?hostFor(pkg,recorded,'fixture mocks'):own?hostFor(pkg,own,'tests/mocks.json'):mock?hostFor(pkg,undefined,'recorded stand-in'):undefined;
   return runPackageAsync(pkg,input,{...options,module:executor(pkg,host)});
  };
  const calls=()=>hosts.flatMap(({host,source})=>host.calls.map(call=>({api:call.api,name:call.name,source:call.source==='mocks'?source:'recorded stand-in'})));
- return {test,run,calls};
+ // Media a stand-in made during a run, for the workspace preview's workflow result.
+ const file=url=>{for(const {host} of hosts){const made=host.file?.(url);if(made)return made;}return null;};
+ return {test,run,calls,file};
 }
 
 // What `create-type` writes: one job Step, then the Editor, which has captions and export built in, so no

package/packages/block-cli/workspace-dev.js

@@ -0,0 +1,124 @@
+// What `stillmade-block dev` serves for a workspace (dev-server.js `workspace`): the side list of every Block, workflow
+// and shared file with its state, each Block's own preview session, follow-the-agent, the workflow run with stand-ins
+// and the readiness gate (owner, November 6, 2026). Nothing here reaches StillMade or a provider.
+import {join} from 'node:path';
+import {readFile} from 'node:fs/promises';
+import {blockKind,buildWorkspace,readWorkspaceState,workspaceItems,findWorkspace,folderName,adoptWorkspaceBlock,BLOCKS_DIR,WORKFLOWS_DIR,SHARED_DIR} from './workspace.js';
+import {runReadyGate,workspaceVerdicts} from './ready-gate.js';
+import {LICENSE_HOLDER_PLACEHOLDER,TEMPLATES} from './templates.js';
+import {blockSession,loadProjectType,localFileReader,typeMocksFor} from './cli.js';
+import {typeModuleRunner} from './type-packages.js';
+import {previewProjectType} from '../block-platform/type-preview.js';
+import {packageForStage} from '../block-platform/stage-package.js';
+import {briefInputNames} from '../block-platform/brief-ports.js';
+import {BUILTIN_BLOCKS} from '../block-platform/catalog.js';
+import {describeTrigger} from '../block-sdk/triggers.js';
+
+const NAME=/^[a-z][a-z0-9-]{0,59}$/;
+const PLACEHOLDER_DESCRIPTION=/^Replace with one sentence/;
+// The starting feature map `create` writes (one entry copied from the description) does not count until rewritten (ready-gate.js).
+const placeholderFeatures=features=>!Array.isArray(features)||!features.length||features.length===1&&features[0].id==='main'&&features[0].asks?.length===1&&features[0].asks[0]===features[0].does;
+const portList=ports=>Object.entries(ports||{}).map(([name,port])=>({name,type:port?.type||'json',...(port?.required?{required:true}:{})}));
+
+export async function workspaceProvider(root,{main,picks}){
+ const sessions=new Map();let lastRunner=null;
+ const blockPath=key=>{const name=key.slice(BLOCKS_DIR.length+1);return key.startsWith(`${BLOCKS_DIR}/`)&&NAME.test(name)?join(root,BLOCKS_DIR,name):null;};
+ const workflowPath=key=>{const name=key.slice(WORKFLOWS_DIR.length+1);return key.startsWith(`${WORKFLOWS_DIR}/`)&&NAME.test(name)?join(root,WORKFLOWS_DIR,`${name}.json`):null;};
+
+ async function list(){
+  const [{config},{blocks,workflows,shared},state,verdicts]=await Promise.all([findWorkspace(root),workspaceItems(root),readWorkspaceState(root),workspaceVerdicts(root)]);
+  const usedBy={};for(const [block,files] of Object.entries(state.shared||{}))for(const file of files)(usedBy[file]||=[]).push(block);
+  const items=[];
+  for(const item of blocks){
+   const key=`${BLOCKS_DIR}/${item.name}`,manifest=item.manifest||{},gate=verdicts[key],built=state.buildFailures?.[item.name];
+   const checklist=[
+    {id:'description',label:'Description says what it does for the person',done:!!manifest.description&&!PLACEHOLDER_DESCRIPTION.test(manifest.description)},
+    {id:'license',label:'License names who it is made for',done:!String(manifest.provenance?.notice||'').includes(LICENSE_HOLDER_PLACEHOLDER)},
+    {id:'features',label:'Feature map: one entry per thing it can do',done:!placeholderFeatures(manifest.features)},
+   ];
+   const status=item.problem||built||gate?.current&&!gate.ok?'needs-fix':gate?.current&&gate.ok?'ready':checklist.some(entry=>!entry.done)?'building':'unchecked';
+   items.push({key,kind:'block',folder:item.name,name:manifest.name||item.name,version:manifest.version||null,runtime:manifest.runtime||null,blockKind:blockKind(manifest),
+    ...(manifest.triggers?.length?{triggers:manifest.triggers.map(trigger=>{try{return describeTrigger(trigger);}catch{return String(trigger?.event||'');}})}:{}),
+    ...(manifest.permissions?.connections?.length?{apps:manifest.permissions.connections}:{}),
+    status,checklist,...(item.problem?{problem:item.problem}:{}),...(built?{buildProblem:built}:{}),
+    source:item.source?'src/main.js':null,shared:state.shared?.[item.name]||[],gate:gate||null});
+  }
+  for(const item of workflows){
+   const key=`${WORKFLOWS_DIR}/${item.name}`,gate=verdicts[`${WORKFLOWS_DIR}/${item.name}.json`],stages=Array.isArray(item.type?.stages)?item.type.stages:[];
+   items.push({key,kind:'workflow',folder:item.name,name:item.type?.name||item.name,version:item.type?.version||null,steps:stages.length,automation:stages[0]?.blockId==='sm.when',
+    status:item.problem?'needs-fix':gate?.current?(gate.ok?'ready':'needs-fix'):'unchecked',...(item.problem?{problem:item.problem}:{}),gate:gate||null});
+  }
+  return {name:config.name,version:config.version,root,items,shared:shared.filter(file=>file!=='README.md').map(file=>({file,usedBy:usedBy[file]||[]}))};
+ }
+
+ // Which Blocks a set of saved paths touches: what to build, what to reload, and which item the agent is working on.
+ async function changed(paths){
+  const plan={build:new Set(),reload:new Set(),focus:null},state=await readWorkspaceState(root);
+  let items=null;const blockItems=async()=>items||=(await workspaceItems(root)).blocks;
+  for(const path of paths){
+   const block=/^blocks\/([^/]+)\/(.+)$/.exec(path),workflow=/^workflows\/([^/]+)\.json$/.exec(path);
+   if(block){
+    const [,name,rest]=block;if(/^(node_modules|\.stillmade|dist)\//.test(rest))continue;
+    if(rest==='src/main.js')plan.build.add(name);
+    plan.reload.add(`${BLOCKS_DIR}/${name}`);plan.focus=`${BLOCKS_DIR}/${name}`;
+   }else if(workflow){plan.focus=`${WORKFLOWS_DIR}/${workflow[1].replace(/\.samples$/,'')}`;}
+   else if(path.startsWith(`${SHARED_DIR}/`)){
+    const file=path.slice(SHARED_DIR.length+1);
+    for(const item of await blockItems())if(item.source&&(!state.shared?.[item.name]||state.shared[item.name].includes(file))){plan.build.add(item.name);plan.reload.add(`${BLOCKS_DIR}/${item.name}`);}
+   }
+  }
+  for(const name of plan.build)plan.reload.add(`${BLOCKS_DIR}/${name}`);
+  return {build:[...plan.build],reload:[...plan.reload],focus:plan.focus};
+ }
+
+ // The workflow with its Steps' ports, for the preview's Steps row, and the inputs a run starts from.
+ async function workflow(key){
+  const path=workflowPath(key);if(!path)throw new Error('No such workflow in this workspace.');
+  const raw=JSON.parse(await readFile(path,'utf8')),type=await loadProjectType(path);
+  const steps=type.stages.map((stage,index)=>{
+   const pkg=packageForStage(type,stage,BUILTIN_BLOCKS),manifest=pkg?.manifest||{};
+   return {id:stage.id,label:stage.label||manifest.name||stage.blockId,blockId:stage.blockId,version:stage.version,folder:raw.stages?.[index]?.block||null,name:manifest.name||stage.blockId,runtime:manifest.runtime||null,blockKind:blockKind(manifest),inputs:portList(manifest.inputs),outputs:portList(manifest.outputs)};
+  });
+  return {key,name:type.name,version:type.version,description:type.description||'',automation:type.stages[0]?.blockId==='sm.when',steps,connections:type.connections||[],samples:await samplesFor(path,type)};
+ }
+ // workflows/<name>.samples.json, else each Step's first example minus what another Step feeds it (and never a brief:
+ // a Block's own example is never a Step's brief).
+ async function samplesFor(path,type){
+  try{return JSON.parse(await readFile(path.replace(/\.json$/,'.samples.json'),'utf8'));}catch(error){if(error.code!=='ENOENT')throw new Error(`${path.slice(root.length+1).replace(/\.json$/,'.samples.json')}: ${error.message}`);}
+  const samples={};
+  for(const stage of type.stages){
+   const pkg=packageForStage(type,stage,BUILTIN_BLOCKS),input=pkg?.tests?.[0]?.input;if(!input)continue;
+   const fed=new Set((type.connections||[]).filter(edge=>edge.to.stage===stage.id).map(edge=>edge.to.port)),briefs=new Set(briefInputNames(pkg.manifest));
+   const own=Object.fromEntries(Object.entries(input).filter(([port])=>!fed.has(port)&&!briefs.has(port)));
+   if(Object.keys(own).length)samples[stage.id]=own;
+  }
+  return samples;
+ }
+ async function runWorkflow(key,inputs,onStep){
+  const path=workflowPath(key);if(!path)throw new Error('No such workflow in this workspace.');
+  const type=await loadProjectType(path),runner=typeModuleRunner({mock:true,readLocalFile:localFileReader(root),...(typeMocksFor(type)?{mocksFor:typeMocksFor(type)}:{})});
+  lastRunner=runner;
+  const result=await previewProjectType(type,{inputs:inputs&&typeof inputs==='object'?inputs:await samplesFor(path,type),run:runner.run,onResult:onStep,interactive:true});
+  const calls=runner.calls();
+  return {...result,...(calls.length?{standIns:calls}:{})};
+ }
+
+ return {
+  root,
+  session(key){const path=blockPath(key);if(!path)return null;if(!sessions.has(key))sessions.set(key,blockSession(path,picks));return sessions.get(key);},
+  folderOf:key=>join(root,key),
+  list,changed,workflow,runWorkflow,
+  build:names=>buildWorkspace(root,{only:names}),
+  media:url=>lastRunner?.file(url)||null,
+  async check(){const verdict=await runReadyGate({root,main});return {passed:verdict.passed,checked:verdict.checked,results:verdict.results.map(({package:name,status,ok,failures})=>({package:name,status,ok,failures}))};},
+  templates:()=>Object.entries(TEMPLATES).map(([name,template])=>({name,runtime:template.runtime,description:template.description})),
+  // The preview's New Block: the same `add` an agent runs.
+  async add({name,template}={}){
+   const folder=folderName(name),path=join(root,BLOCKS_DIR,folder);
+   if(template!==undefined&&!Object.hasOwn(TEMPLATES,template))throw new Error(`Unknown template ${template}.`);
+   const created=await main(['create',path,...(template?[template]:[])]);
+   await adoptWorkspaceBlock(path);
+   return {key:`${BLOCKS_DIR}/${folder}`,template:created.template};
+  },
+ };
+}

package/packages/block-cli/workspace-pack.js

@@ -0,0 +1,62 @@
+// `stillmade-block pack` at a workspace's top: every Block and workflow, each packed exactly as `pack` packs it alone,
+// in one .stillmade-pack file (packages/block-sdk/stillmade-pack.js).
+import {mkdtemp,readFile,rm,writeFile} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join,resolve} from 'node:path';
+import {createHash} from 'node:crypto';
+import {createRequire} from 'node:module';
+import {PACK_FORMAT,PACK_INDEX,PACK_LIMITS,PACK_SUFFIX,validatePackIndex} from '../block-sdk/stillmade-pack.js';
+import {blockKind,buildWorkspace,findWorkspace,workspaceItems,unbundledImport,BLOCKS_DIR,WORKFLOWS_DIR} from './workspace.js';
+
+const require=createRequire(import.meta.url);
+function zipCodec(){try{return require('fflate');}catch{return createRequire(new URL('../../client/package.json',import.meta.url))('fflate');}}
+const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+
+export async function packWorkspace(root,{main,output}={}){
+ const {config}=await findWorkspace(root);
+ const build=await buildWorkspace(root);
+ if(build.failed.length)throw Object.assign(new Error(`Build failed for ${build.failed.map(item=>item.block).join(', ')}`),{code:'BUILD',report:build});
+ const {blocks,workflows}=await workspaceItems(root);
+ if(!blocks.length)throw Object.assign(new Error('This workspace has no Blocks to pack yet.'),{code:'USAGE'});
+ const broken=[...blocks,...workflows].find(item=>item.problem);if(broken)throw new Error(broken.problem);
+ for(const item of blocks){const loose=await unbundledImport(item.path);if(loose)throw Object.assign(new Error(`${BLOCKS_DIR}/${item.name}: ${loose.file} imports ${loose.specifier}. Keep the code in src/main.js and run \`stillmade-block build\`.`),{code:'BUILD'});}
+ const scratch=await mkdtemp(join(tmpdir(),'stillmade-pack-')),files={},items=[];
+ try{
+  // Each item through the same pack a single Block or Type gets; a failing test stops the whole pack.
+  const one=async(item,folder,suffix)=>{
+   let result;
+   try{result=await main(['pack',item.path,join(scratch,`${folder}-${item.name}${suffix}`)]);}
+   catch(error){throw Object.assign(new Error(`${folder}/${item.name}: ${error.message}`),{code:error.code,report:error.report});}
+   return new Uint8Array(await readFile(result.file));
+  };
+  for(const item of blocks){
+   const suffix=await suffixFor(item),bytes=await one(item,BLOCKS_DIR,suffix),manifest=item.manifest;
+   const path=`${BLOCKS_DIR}/${manifest.id}-${manifest.version}${suffix}`;
+   files[path]=bytes;
+   items.push({kind:'block',blockKind:blockKind(manifest),id:manifest.id,version:manifest.version,name:manifest.name,...(manifest.description?{description:String(manifest.description).slice(0,300)}:{}),folder:item.name,path,sha256:sha256(bytes)});
+  }
+  for(const item of workflows){
+   const bytes=await one(item,WORKFLOWS_DIR,'.stillmade.json'),type=JSON.parse(new TextDecoder().decode(bytes));
+   const path=`${WORKFLOWS_DIR}/${type.id}-${type.version}.stillmade.json`;
+   const own=new Set(items.map(entry=>`${entry.id}@${entry.version}`));
+   files[path]=bytes;
+   items.push({kind:'workflow',id:type.id,version:type.version,name:type.name,...(type.description?{description:String(type.description).slice(0,300)}:{}),...(type.stages?.[0]?.blockId==='sm.when'?{automation:true}:{}),folder:item.name,path,sha256:sha256(bytes),
+    needs:[...new Set(type.stages.map(stage=>`${stage.blockId}@${stage.version}`))].filter(need=>own.has(need))});
+  }
+ }finally{await rm(scratch,{recursive:true,force:true});}
+ const index=validatePackIndex({format:PACK_FORMAT,name:config.name,version:config.version,...(config.description?{description:config.description}:{}),items});
+ const archive=zipCodec().zipSync({[PACK_INDEX]:new TextEncoder().encode(`${JSON.stringify(index,null,2)}\n`),...files},{level:6});
+ if(archive.byteLength>PACK_LIMITS.bytes)throw Object.assign(new Error(`The pack is ${Math.round(archive.byteLength/1048576)} MB; StillMade's Import takes up to ${PACK_LIMITS.bytes/1048576} MB. Pack fewer Blocks, or move large files out of module/.`),{code:'STILLMADE_PACK'});
+ const slug=config.name.toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^-+|-+$/g,'')||'blocks';
+ const file=output||resolve(root,`${slug}-${config.version}${PACK_SUFFIX}`);
+ if(!file.endsWith(PACK_SUFFIX))throw Object.assign(new Error(`A workspace pack ends in ${PACK_SUFFIX}.`),{code:'USAGE'});
+ await writeFile(file,archive);
+ return {pack:file,bytes:archive.byteLength,items:index.items.map(({kind,blockKind:kindOfBlock,id,version,name,needs})=>({kind:kindOfBlock||kind,id,version,name,...(needs?{needs}:{})})),...(build.built.length?{built:build.built}:{})};
+}
+// The file name pack gives a Block: a portable archive for a portable folder, a module bundle for a Block with digested
+// files (module/ or src/view-files/), else plain package JSON.
+async function suffixFor(item){
+ const {readPackage}=await import('./cli.js'),{hasDigestFiles,MODULE_BUNDLE_SUFFIX}=await import('../block-sdk/module-bundle.js');
+ const pkg=await readPackage(item.path);
+ return pkg.portable?'.stillmade-block':hasDigestFiles(pkg)?MODULE_BUNDLE_SUFFIX:'.stillmade.json';
+}