stillmade-sdk 0.1.47 → 0.1.49

package/packages/block-cli/cli.js

@@ -78,7 +78,7 @@ const moduleExecutor=(pkg,host)=>{const files=moduleFiles.get(pkg);return files?
 // 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=>{
+export 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'});
@@ -125,11 +125,23 @@ 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,answered;
- // Files the person picks in the preview's own-file mode: kept in this process only, read by the run as themselves
- // (November 1, 2026, owner: try a Block on your own video, not only its example).
+ const picks=pickedFiles(),session=blockSession(path,picks);
+ const link=live?{origin:liveSite(site),key:randomBytes(24).toString('base64url')}:undefined;
+ const server=await startDevServer({folder:path,port,build,...session,pick:picks.pick,live:link});
+ 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};
+}
+// Files the person picks in the preview's own-file mode: kept in this process only, read by the run as themselves
+// (November 1, 2026, owner: try a Block on your own video, not only its example).
+export function pickedFiles(){
  const picked=new Map(),pickedMedia=url=>picked.get(url)||null;
  const pick=(bytes,{mediaType,name})=>{const id=randomBytes(8).toString('hex'),safe=String(name||'file').replace(/[^\w.-]+/g,'-').slice(0,80)||'file',url=`/api/media/picked/${id}/${safe}`;picked.set(url,{bytes,mediaType});return url;};
+ return {pick,pickedMedia};
+}
+// One Block folder in the preview: load the current source, run it with stand-ins, serve its media, pack it.
+// `dev` on a Block folder has one; `dev` on a workspace has one per Block.
+export function blockSession(path,{pickedMedia}){
+ 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})`:''}`};}
@@ -163,10 +175,7 @@ async function dev(path,options){
  const bundle=async({pkg})=>hasDigestFiles(pkg)
   ?{fileName:`${pkg.manifest.id}-${pkg.manifest.version}${MODULE_BUNDLE_SUFFIX}`,source:JSON.stringify(createModuleBundle(pkg,moduleFiles.get(pkg)))}
   :{fileName:`${pkg.manifest.id}-${pkg.manifest.version}.stillmade.json`,source:JSON.stringify(pkg)};
- const link=live?{origin:liveSite(site),key:randomBytes(24).toString('base64url')}:undefined;
- const server=await startDevServer({folder:path,port,build,load,run,media,pick,live:link,bundle});
- 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};
+ return {load,run,media,bundle};
 }
 // 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}:{};};
@@ -194,6 +203,20 @@ export async function readPackage(path) {
   if(files)moduleFiles.set(pkg,files);
   return pkg;
 }
+// A Project Type file ready to check or run: in a workspace its Steps may name a Block by folder (workspace.js
+// compileWorkflow), and its packages may name a packed Block or a Block folder, or embed a packed module bundle
+// (type-packages.js).
+const typeMocks=new WeakMap();
+async function projectTypeFrom(type,path){
+ const {findWorkspace,compileWorkflow,workspaceMocks}=await import('./workspace.js');
+ const found=await findWorkspace(path);if(found)type=await compileWorkflow(type,{root:found.root,file:path});
+ const result=await embedTypePackages(type,{folder:dirname(path),resolvePath:resolve,read:async file=>{const block=await readPackage(file);return {pkg:block,files:moduleFiles.get(block)};}});
+ if(found)typeMocks.set(result,await workspaceMocks(found.root));
+ return result;
+}
+// The recorded answers a Type's Block brings from its workspace folder, for typeModuleRunner.
+export const typeMocksFor=type=>{const mocks=typeMocks.get(type);return mocks?pkg=>mocks.get(`${pkg?.manifest?.id}@${pkg?.manifest?.version}`):undefined;};
+export async function loadProjectType(path){const type=await readPackage(path);if(!type?.stages)throw new Error(`${basename(path)} is not a Project Type.`);return projectTypeFrom(type,path);}
 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) {
   // --no-module-execution: what the gate a hook starts passes to ready, so a module Block is refused
@@ -201,14 +224,62 @@ export async function main(rawArgs) {
   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}))};
+  // A command that works on a folder may start with its options; the folder is then this one (`dev --port 4811`).
+  if(['dev','test','validate','gate','pack','build','ready','inspect','permissions'].includes(args[0])&&args[1]?.startsWith('--'))args.splice(1,0,'.');
+  // In a workspace a Block may be named by its folder alone (`test listing-facts` for blocks/listing-facts; November 6,
+  // 2026: a coding agent's `test listing-facts` from the workspace folder failed with ENOENT).
+  if(['validate','test','run','preview','pack','ready','inspect','permissions','types','dev'].includes(args[0])&&args[1]&&!args[1].startsWith('--')){
+   const named=args[1];let missing=false;try{await lstat(resolve(named));}catch{missing=true;}
+   if(missing&&/^[a-z][a-z0-9-]{0,59}$/.test(named)){const {findWorkspace,BLOCKS_DIR,WORKFLOWS_DIR}=await import('./workspace.js'),found=await findWorkspace(process.cwd());
+    if(found){for(const candidate of [join(found.root,BLOCKS_DIR,named),join(found.root,WORKFLOWS_DIR,`${named}.json`)]){try{await lstat(candidate);args[1]=candidate;break;}catch{}}}}
+  }
   const [command, target = '.', extra] = args, path = resolve(target);
+  // A workspace: several Blocks, shared code and workflows in one folder (workspace.js).
+  if(command==='init'){
+   if(args.length<2||target.startsWith('--'))throw Object.assign(new Error('Name the folder to create: stillmade-block init my-blocks [--name "Listing kit"]'),{code:'USAGE'});
+   const {initWorkspace}=await import('./workspace.js');
+   return initWorkspace(path,{name:optionValue(args,'--name')});
+  }
+  if(command==='add'){
+   const {requireWorkspace,folderName,adoptWorkspaceBlock,BLOCKS_DIR,isWorkspaceRoot}=await import('./workspace.js');
+   if(args.length<2||target.startsWith('--'))throw Object.assign(new Error('Name the Block: stillmade-block add price-drop-alert [template]'),{code:'USAGE'});
+   const {root}=await requireWorkspace(process.cwd(),'add'),name=folderName(target),folder=join(root,BLOCKS_DIR,name);
+   if(await isWorkspaceRoot(folder))throw Object.assign(new Error(`${name} is a workspace.`),{code:'USAGE'});
+   const template=extra&&!extra.startsWith('--')?extra:undefined;
+   const app=optionValue(args,'--app'),created=await main(['create',folder,...(template?[template]:[]),...(app?['--app',app]:[])]);
+   const adopted=await adoptWorkspaceBlock(folder);
+   return {...created,workspace:root,block:name,...(adopted.source?{source:adopted.source}:{}),next:`Build the Block in ${BLOCKS_DIR}/${name}${adopted.source?` (edit its code in ${BLOCKS_DIR}/${name}/src/main.js only: module/main.js is a copy that \`stillmade-block build\`, test, gate and pack write from it)`:''}, replace its placeholder \`description\` and the copyright holder in \`provenance.notice\`, write its feature map (\`manifest.features\`), then run \`stillmade-block gate\` from the workspace folder. Do not call the Block ready until the gate passes for it.`};
+  }
+  if(command==='add-type'){
+   const {requireWorkspace,addWorkflow}=await import('./workspace.js');
+   if(args.length<2||target.startsWith('--'))throw Object.assign(new Error('Name the workflow: stillmade-block add-type listing-video [block ...] [--when schedule]'),{code:'USAGE'});
+   const {root}=await requireWorkspace(process.cwd(),'add-type');
+   const when=optionValue(args,'--when'),blocks=args.slice(2).filter((value,index,list)=>!value.startsWith('--')&&list[index-1]!=='--when');
+   return addWorkflow(root,target,{blocks,...(when?{config:{first:await whenStage(when)}}:{})});
+  }
+  if(command==='build'){
+   const {requireWorkspace,buildWorkspace}=await import('./workspace.js');
+   const {root}=await requireWorkspace(path,'build'),report=await buildWorkspace(root);
+   if(report.failed.length)throw Object.assign(new Error(`Build failed for ${report.failed.map(item=>item.block).join(', ')}`),{code:'BUILD',report});
+   return {workspace:root,...report};
+  }
+  if(['test','validate','pack','dev'].includes(command)){
+   const {isWorkspaceRoot}=await import('./workspace.js');
+   if(await isWorkspaceRoot(path)){
+    if(command==='dev')return workspaceDev(path,args.slice(2));
+    if(command==='pack'){const {packWorkspace}=await import('./workspace-pack.js');return packWorkspace(path,{main,output:extra&&!extra.startsWith('--')?resolve(extra):undefined});}
+    return workspaceCheck(command,path,args.slice(2),mockRequested);
+   }
+  }
   if (command === 'create-type') {
     await writeFile(path, JSON.stringify(TYPE_SCAFFOLD, null, 2), { flag: 'wx' });
     return { created: path, kind: 'type' };
   }
   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({folder:path});
+    const template=templateNamed(extra&&!extra.startsWith('--')?extra:undefined),app=optionValue(args,'--app');
+    if(app&&template.name!=='connector')throw Object.assign(new Error('--app goes with the connector template: create <folder> connector --app gmail'),{code:'USAGE'});
+    const files=await template.files({folder:path,...(app?{app}:{})});
     // 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`;}
      // The new Block is named for its folder, never the example it started from (November 1, 2026: a no-context agent's
@@ -246,8 +317,7 @@ export async function main(rawArgs) {
   }
   if (!['validate', 'test', 'preview', 'pack', 'inspect', 'remix', 'ready', 'permissions'].includes(command)) throw Object.assign(new Error(`Unknown command ${command}. Run stillmade-block --help for the commands.`),{code:'USAGE'});
   let pkg = await readPackage(path);
-  // A Type's packages may name a packed Block or a Block folder, or embed a packed module bundle (type-packages.js).
-  if(pkg?.stages)pkg=await embedTypePackages(pkg,{folder:dirname(path),resolvePath:resolve,read:async file=>{const block=await readPackage(file);return {pkg:block,files:moduleFiles.get(block)};}});
+  if(pkg?.stages)pkg=await projectTypeFrom(pkg,path);
   if(args.includes('--original')){
     if(command!=='pack'||!extra||extra.startsWith('--'))throw new Error('Use pack <source> <output.stillmade-block> --original only for your own original implementation.');
     pkg=withOriginalSource(pkg);
@@ -299,7 +369,7 @@ export async function main(rawArgs) {
     if (command === 'inspect') return { id: pkg.id, version: pkg.version, stages: pkg.stages, workspace: typeWorkspaceSupport(pkg) };
     if(command==='permissions')return {id:pkg.id,blocks:(pkg.packages||[]).map(block=>({id:block.manifest.id,summary:summarizePermissions(block.manifest)}))};
     // Module Steps run in the SDK's local module runner, as `test` and `preview` run a module Block (type-packages.js).
-    const runner=typeModuleRunner({mock:mockRequested,readLocalFile:localFileReader(dirname(path))});
+    const runner=typeModuleRunner({mock:mockRequested,readLocalFile:localFileReader(dirname(path)),...(typeMocksFor(pkg)?{mocksFor:typeMocksFor(pkg)}:{})});
     const standIns=()=>{const calls=runner.calls();return calls.length?{standIns:calls,liveVerified:false}:{};};
     if (command === 'preview') {const preview=await previewProjectType(pkg,{inputs:extra ? JSON.parse(await readFile(resolve(extra),'utf8')) : {},run:runner.run});return {...preview,...standIns()};}
     // Export source without executing local or hosted code. This is not an
@@ -416,6 +486,48 @@ export async function main(rawArgs) {
   await writeFile(output, JSON.stringify(pkg, null, 2), { flag: packFlag(extra) });
   return { file: output, digest: report.digest, tests: report.results.length };
 }
+async function workspaceDev(root,options){
+ let port=4800;
+ for(let index=0;index<options.length;index++){
+  const value=options[index];
+  if(value==='--port'){port=Number(options[++index]);if(!Number.isInteger(port)||port<0||port>65535)throw Object.assign(new Error('--port takes a port number'),{code:'USAGE'});}
+  else throw Object.assign(new Error(`dev on a workspace does not take ${value}. --live and --build work on one Block folder (dev blocks/<name>).`),{code:'USAGE'});
+ }
+ const [{startDevServer},{workspaceProvider}]=await Promise.all([import('./dev-server.js'),import('./workspace-dev.js')]);
+ const picks=pickedFiles(),workspace=await workspaceProvider(root,{main,picks});
+ const server=await startDevServer({folder:root,port,workspace,pick:picks.pick});
+ return {dev:server.url,folder:root,workspace:true,close:server.close};
+}
+// The When Step that starts an automation workflow (StillMade's sm.when, its newest version): what starts each run is
+// turned on in the project's Automation page; an app event here is the start it suggests there.
+async function whenStage(kind){
+ const latest=BUILTIN_BLOCKS.filter(block=>block.manifest?.id==='sm.when').map(block=>block.manifest.version).sort((a,b)=>{const x=a.split('.').map(Number),y=b.split('.').map(Number);for(let i=0;i<3;i++)if(x[i]!==y[i])return x[i]-y[i];return 0;}).pop();
+ if(!latest)throw Object.assign(new Error('This SDK has no When Step.'),{code:'USAGE'});
+ const app=/^app:([a-z0-9][a-z0-9-]{0,79})\/([A-Za-z0-9_]{1,120})$/.exec(kind);
+ if(!['schedule','webhook'].includes(kind)&&!app)throw Object.assign(new Error('--when takes schedule, webhook, or an app event such as app:gmail/GMAIL_NEW_GMAIL_MESSAGE'),{code:'USAGE'});
+ return {id:'when',blockId:'sm.when',version:latest,label:kind==='schedule'?'On a schedule':kind==='webhook'?'When a webhook is called':'When the app has something new',...(app?{config:{start:{app:`app:${app[1]}`,event:app[2]}}}:{})};
+}
+// The value after a --flag, or undefined.
+function optionValue(args,flag){const index=args.indexOf(flag);if(index<0)return undefined;const value=args[index+1];if(!value||value.startsWith('--'))throw Object.assign(new Error(`${flag} takes a value`),{code:'USAGE'});return value;}
+// test or validate at a workspace's top: every Block, then every workflow, each judged as it would be alone.
+async function workspaceCheck(command,root,options,mock){
+ const {workspaceItems,buildWorkspace,unbundledImport,BLOCKS_DIR,WORKFLOWS_DIR}=await import('./workspace.js');
+ const build=await buildWorkspace(root);
+ const {blocks,workflows}=await workspaceItems(root),results=[];
+ const one=async(item,label)=>{
+  if(item.problem)return {item:label,kind:item.kind,passed:false,message:item.problem};
+  const failed=build.failed.find(entry=>entry.block===item.name);if(failed)return {item:label,kind:item.kind,passed:false,message:`Build failed: ${failed.message}`};
+  if(item.kind==='block'){const loose=await unbundledImport(item.path);if(loose)return {item:label,kind:item.kind,passed:false,message:`${loose.file} imports ${loose.specifier}. A Block runs one file: keep the code in src/main.js and run \`stillmade-block build\`.`};}
+  try{const result=await main([command,item.path,...options,...(mock?['--mock']:[])]);return {item:label,kind:item.kind,passed:true,...(Array.isArray(result?.results)?{tests:result.results.length}:{})};}
+  catch(error){const failing=(error.report?.results||[]).filter(entry=>entry&&entry.passed===false).slice(0,5).map(entry=>`${entry.name}: ${entry.message||'failed'}`);return {item:label,kind:item.kind,passed:false,message:[error.message,...failing].join('\n')};}
+ };
+ for(const item of blocks)results.push(await one(item,`${BLOCKS_DIR}/${item.name}`));
+ for(const item of workflows)results.push(await one(item,`${WORKFLOWS_DIR}/${item.name}.json`));
+ const report={workspace:root,command,passed:results.every(item=>item.passed),results,...(build.built.length?{built:build.built}:{})};
+ if(!results.length)throw Object.assign(new Error('This workspace has no Blocks yet. Add one with `stillmade-block add <name> [template]`.'),{code:'USAGE'});
+ if(!report.passed)throw Object.assign(new Error(`${results.filter(item=>!item.passed).length} of ${results.length} items need attention`),{report});
+ return report;
+}
 // pack replaces the file it wrote before under its own name, so packing again after a fix just works; an output path the
 // person names is never overwritten (November 1, 2026: a no-context agent's second pack failed with EEXIST).
 function packFlag(output){return output?'wx':'w';}