stillmade-sdk 0.1.7 → 0.1.8

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Building StillMade Blocks in this folder
 
-This folder is the StillMade Block SDK. Read this file before writing code; it is the same contract StillMade's own AI and importers follow. 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.
+This 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.
 
 ## Readiness gate
 

package/README.md

@@ -0,0 +1,33 @@
+# StillMade SDK 0.1.0
+
+Build, test and package Blocks for [StillMade](https://stillmade.shop).
+
+## Install
+
+```sh
+npm install --save-dev stillmade-sdk
+```
+
+Needs Node.js 22 or later. Everything it runs ships inside the package. From a downloaded SDK folder, run `node packages/block-cli/cli.js` wherever this page says `npx stillmade-block`.
+
+## Build a Block
+
+```sh
+npx stillmade-block create my-block javascript   # create --list shows every template
+npx stillmade-block validate my-block
+npx stillmade-block test my-block                # add --mock for hosted operations: no credits
+npx stillmade-block gate .                       # the readiness check StillMade runs
+npx stillmade-block pack my-block                # the file to import in StillMade
+```
+
+A Block is not ready until `gate` passes. In StillMade, choose Create, then Import (or Import folder).
+
+## For coding agents
+
+Read `AGENTS.md` in this package before writing code: it is the contract every Block is checked against. Step-by-step guide: https://stillmade.shop/docs/build/with-your-ai.md
+
+## Documentation
+
+https://stillmade.shop/docs/sdk · CLI reference: https://stillmade.shop/docs/reference/cli
+
+The npm version can be newer than SDK 0.1.0: patch releases repackage the same SDK. License: PolyForm Shield 1.0.0 (see LICENSE).

package/SDK.md

@@ -106,7 +106,7 @@ recipe and JavaScript examples continue to run offline.
 ## Build your first Block
 
 ### Prerequisites
-Download and extract the [SDK 0.1.0](/block-sdk/stillmade-sdk-0.1.0.zip). Install Node.js 22 or later. Run commands from the extracted SDK folder. The runtime and its dependencies are bundled; the following example needs no account, API key, npm install, or network request.
+Install Node.js 22 or later. Then either run `npm install --save-dev stillmade-sdk` and type `npx stillmade-block` wherever this page says `node packages/block-cli/cli.js`, or download and extract the [SDK 0.1.0](/block-sdk/stillmade-sdk-0.1.0.zip) and run the commands from the extracted folder. The runtime and its dependencies are bundled; the following example needs no account, API key or network request.
 
 ### Create a Block
 ```sh
@@ -160,7 +160,11 @@ Give your coding agent (Claude Code, Cursor, Codex, Gemini CLI or similar) a lin
 ### For the coding agent
 Do every step yourself. Do not ask the person to download, unzip, open a folder or run a command; only ask about what the Block should do.
 
-1. **Get the SDK.** It is `/block-sdk/stillmade-sdk-0.1.0.zip` on the same site as this page: replace this page's path with that one (for example `https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.zip`, or `http://localhost:3000/block-sdk/stillmade-sdk-0.1.0.zip` when this page came from localhost). If `stillmade-blocks/AGENTS.md` already exists in your working folder, reuse that folder. Otherwise download and extract it into `stillmade-blocks`:
+1. **Get the SDK.** With Node.js 22 or later and npm, install it in your working folder:
+```sh
+npm install --save-dev stillmade-sdk
+```
+Then read `node_modules/stillmade-sdk/AGENTS.md` in full and run every command below as `npx stillmade-block`. Without npm, download the SDK archive instead. It is `/block-sdk/stillmade-sdk-0.1.0.zip` on the same site as this page: replace this page's path with that one (for example `https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.zip`, or `http://localhost:3000/block-sdk/stillmade-sdk-0.1.0.zip` when this page came from localhost). If `stillmade-blocks/AGENTS.md` already exists in your working folder, reuse that folder. Otherwise download and extract it into `stillmade-blocks`:
 ```sh
 curl -fsSL "<SDK URL>" -o stillmade-sdk.zip && unzip -q stillmade-sdk.zip -d stillmade-blocks && rm stillmade-sdk.zip
 ```
@@ -168,10 +172,10 @@ On Windows PowerShell:
 ```powershell
 Invoke-WebRequest "<SDK URL>" -OutFile stillmade-sdk.zip; Expand-Archive stillmade-sdk.zip stillmade-blocks; Remove-Item stillmade-sdk.zip
 ```
-The SDK needs Node.js 22 or later and nothing else; its runtime is bundled, so never run `npm install` in it.
-2. **Read `stillmade-blocks/AGENTS.md` in full** before writing code. It is the contract StillMade checks every Block against.
-3. **Build inside `stillmade-blocks`.** Scaffold with `node packages/block-cli/cli.js create <name> javascript` (or `image`, `stateful`, `capability`), then iterate with `node packages/block-cli/cli.js validate <name>` and `test <name>`.
-4. **Run the readiness gate before you call anything ready:** `node packages/block-cli/cli.js gate .` from `stillmade-blocks`. Report the exact status it prints. If it fails, fix the listed checks and run it again. If you cannot fix them, tell the person plainly that the Block is not ready and list the failing checks. A browser application reports NEEDS STILLMADE REVIEW: tell the person to import it so StillMade can run its isolated review.
+The archive needs Node.js 22 or later and nothing else; its runtime is bundled, so never run `npm install` in it. From the archive, run commands from `stillmade-blocks` as `node packages/block-cli/cli.js` where the steps below say `npx stillmade-block`.
+2. **Read `AGENTS.md` in full** before writing code (`node_modules/stillmade-sdk/AGENTS.md` from npm, `stillmade-blocks/AGENTS.md` from the archive). It is the contract StillMade checks every Block against.
+3. **Build the Block.** Scaffold with `npx stillmade-block create <name> javascript` (`npx stillmade-block create --list` shows every template, including `text`, `image-generate` and `speech` for hosted generation), then iterate with `npx stillmade-block validate <name>` and `npx stillmade-block test <name>`. Hosted operations need `test <name> --mock`, which uses recorded stand-ins and spends no credits.
+4. **Run the readiness gate before you call anything ready:** `npx stillmade-block gate .` from the folder that holds the Block. Report the exact status it prints. If it fails, fix the listed checks and run it again. If you cannot fix them, tell the person plainly that the Block is not ready and list the failing checks. A browser application reports NEEDS STILLMADE REVIEW: tell the person to import it so StillMade can run its isolated review.
 5. **Hand it over.** Give the person the full path of the `<name>` folder. In StillMade they choose **Import folder** and select that folder.
 
 `stillmade-blocks` contains hooks that run the gate automatically when a Claude Code or Cursor session started in that folder finishes a turn. In the session that downloaded the SDK those hooks are not active yet, so run the gate yourself as in step 4.
@@ -6587,9 +6591,9 @@ Accepts decoded RGBA. Thickness is an integer from 1 to 8; threshold is from 0 t
 
 ### Run commands
 ```sh
-node packages/block-cli/cli.js <command> <target> [argument] [options]
+npx stillmade-block <command> <target> [argument] [options]
 ```
-Run from the SDK folder, or add the extracted SDK to a project with `npm install --save-dev <SDK folder>` and call `stillmade-block` from npm scripts. Targets can be authoring folders or packed files, except where a command creates a new target. `--help` prints this list.
+That is the form after `npm install --save-dev stillmade-sdk`. From a downloaded SDK folder, run `node packages/block-cli/cli.js <command> …` instead. Output is a JSON object when it is piped, which is what coding agents read; `--text` prints readable text and `--json` forces JSON. Targets can be authoring folders or packed files, except where a command creates a new target. `--help` prints this list.
 
 | Command | Argument | Behavior |
 | --- | --- | --- |
@@ -7132,10 +7136,12 @@ The same publishing panel controls public cover media, full description, categor
 
 My builds includes original and forked drafts, imports, installed versions, every own release and private releases. A version can be marked deprecated or delisted, with a public notice and an optional replacement version. It stops appearing in discovery and becomes ineligible for indexing; direct version URLs, source downloads and existing pinned projects remain available unless a separate security revocation applies.
 
-Community publication does not automatically create a curated listing. Set the
-source license in `manifest.license` (or top-level `license` for a project type),
-save/test/sync, and publish an immutable Community version. Submit that released
-version from Block Developer and track the decision in My builds. Supported SPDX
+A Block published publicly from StillMade is listed in the Marketplace as soon as
+its automatic checks pass: tests for its exact source, a supported license, its
+runtime, and no exact duplicate. No one reviews it by hand. A Project Type waits
+for an admin review. Set the source license in `manifest.license` (or top-level
+`license` for a project type), save/test/sync, and publish an immutable Community
+version; track the result in My builds. Supported SPDX
 identifiers for the initial review flow are exported as `MARKETPLACE_LICENSES` and
 listed in `api-index.json`; custom/unknown licensing needs a later review workflow.
 Changing a published version's license requires a new immutable version.
@@ -7154,7 +7160,7 @@ Blocks, Project Types, and creators have their own page URLs. Public pages link
 
 ## Build with an AI coding tool
 
-The fastest route is to send your coding agent [Build a Block with your AI](/docs/build/with-your-ai) with your idea: it downloads the SDK, builds the Block and runs the readiness gate without you running anything.
+The fastest route is to send your coding agent [Build a Block with your AI](/docs/build/with-your-ai) with your idea: it installs the SDK (`npm install --save-dev stillmade-sdk`), builds the Block and runs the readiness gate without you running anything.
 
 ### Start with the SDK contract
 Use the button below to copy the complete authoring guide, then add a short description such as “Make a Block that converts an image to grayscale while preserving alpha.” The guide includes the package format, supported runtime, typed ports, permissions, fixtures, and a complete example.
@@ -9139,11 +9145,14 @@ Hosted text and speech require their separate [text review](/docs/build/hosted-t
 ## Download the StillMade SDK
 
 ### SDK 0.1.0
-[Download the complete SDK](/block-sdk/stillmade-sdk-0.1.0.zip), or install the same files as an npm package (its dependencies ship inside it, so no registry is needed):
+Install it from npm into any folder or project (Node.js 22 or later; its dependencies ship inside the package):
 ```sh
-npm install --save-dev https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.tgz
+npm install --save-dev stillmade-sdk
 npx stillmade-block create --list
 ```
+Run every CLI command as `npx stillmade-block <command>`. Coding agents should read `node_modules/stillmade-sdk/AGENTS.md` before writing a Block. The npm version can be newer than SDK 0.1.0: patch releases repackage the same SDK, and Blocks still declare `sdkVersion` 0.1.0.
+
+Without npm, [download the complete SDK](/block-sdk/stillmade-sdk-0.1.0.zip) and run the CLI from the extracted folder as `node packages/block-cli/cli.js <command>`. The same package is also served at `https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.tgz` for installs that cannot reach the npm registry.
 Includes the validators, recipe interpreter, isolated JavaScript runtime and WASM, pinned runtime dependencies and licenses, CLI, TypeScript declarations, examples, and documentation. Requires Node.js 22 or later for local use. No npm installation is required after extraction.
 
 Every finished Block must pass **Remix readiness**. Include editable source, typed I/O, controls, tests and complete license evidence. Remix works automatically through the same package contract; no custom callback or app wiring is needed. CLI validation, builder completion and import enforce it. See [the required remix contract](/docs/tools/block-remix).

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "stillmade-sdk",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "StillMade Block SDK, CLI and examples",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",
+  "homepage": "https://stillmade.shop/docs/sdk",
+  "keywords": [
+    "stillmade",
+    "stillmade-block",
+    "sdk",
+    "cli"
+  ],
   "bin": {
     "stillmade-block": "packages/block-cli/cli.js"
   },

package/packages/block-cli/format.js

@@ -1,5 +1,6 @@
 // Readable terminal output for stillmade-block. `--json` prints the result
 // object instead, for scripts and coding agents.
+import {relative,resolve} from 'node:path';
 
 export const HELP=`stillmade-block: build, test and package StillMade Blocks
 
@@ -50,6 +51,15 @@ function notes(result){
  return out;
 }
 
+// The command that runs this CLI again from the new Block folder, so the printed
+// next steps work when they are copied: npx when npm ran it, the CLI file from a
+// downloaded SDK folder, and the bare name only for a global install.
+export function cliCommand(folder,{env=process.env,argv=process.argv}={}){
+ const script=String(argv[1]||'');
+ if(env.npm_command==='exec'||env.npm_command==='run-script'||/node_modules[\\/]stillmade-sdk[\\/]/.test(script))return 'npx stillmade-block';
+ if(/packages[\\/]block-cli[\\/]cli\.js$/.test(script)&&folder)return `node ${relative(resolve(folder),script).replaceAll('\\','/')}`;
+ return 'stillmade-block';
+}
 export function formatResult(args,result){
  const command=args[0];
  if(result?.help)return result.help;
@@ -59,7 +69,8 @@ export function formatResult(args,result){
  }
  if(command==='create'&&result?.created){
   if(result.kind==='type')return lines(`Created a Project Type at ${result.created}.`);
-  return lines(`Created a ${result.runtime} Block from the ${result.template} template in ${result.created}.`,'','Next:',`  cd ${result.created}`,result.files?.includes('package.json')?'  npm install':null,result.files?.includes('package.json')?'  npm run build':null,'  stillmade-block dev .',`  stillmade-block test .${result.runtime==='capability'?' --mock':''}`,'  stillmade-block pack .');
+  const cli=cliCommand(result.created);
+  return lines(`Created a ${result.runtime} Block from the ${result.template} template in ${result.created}.`,'','Next:',`  cd ${result.created}`,result.files?.includes('package.json')?'  npm install':null,result.files?.includes('package.json')?'  npm run build':null,`  ${cli} dev .`,`  ${cli} test .${result.runtime==='capability'?' --mock':''}`,`  ${cli} pack .`);
  }
  if(command==='validate'&&result?.valid)return lines(`Valid: ${result.id}`,result.appearanceAdvice?`Advice: ${result.appearanceAdvice}`:null,result.tests===0?'Fixtures for hosted runs are checked in StillMade; try them offline with: stillmade-block test . --mock':null,result.mobileProfile?`Phone profile: ${result.mobileProfile.message}`:null);
  if(command==='test'&&Array.isArray(result?.results)){

package/packages/block-cli/templates.js

@@ -16,7 +16,7 @@ function packageFiles(pkg){
  else if(pkg.recipe)files['src/recipe.json']=json(pkg.recipe);
  return files;
 }
-const readme=(title,body,commands)=>`# ${title}\n\n${body}\n\n\`\`\`sh\n${commands.join('\n')}\n\`\`\`\n\nThe full guide: https://stillmade.shop/docs/build\n`;
+const readme=(title,body,commands)=>`# ${title}\n\n${body}\n\n\`\`\`sh\n${commands.join('\n')}\n\`\`\`\n\nInstalled the SDK from npm? Put \`npx \` in front of each command. From a downloaded SDK folder, run \`node ../packages/block-cli/cli.js\` in place of \`stillmade-block\`.\n\nThe full guide: https://stillmade.shop/docs/build\n`;
 const OFFLINE=['stillmade-block validate .','stillmade-block test .','stillmade-block dev .','stillmade-block pack .'];
 const HOSTED=['stillmade-block validate .','stillmade-block test . --mock    # recorded stand-ins, no credits','stillmade-block dev .','stillmade-block pack .'];
 const fromExample=(load,body,commands=OFFLINE)=>async()=>{const pkg=await load();return {...packageFiles(pkg),'README.md':readme(pkg.manifest.name,body,commands)};};

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

@@ -140,5 +140,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. 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. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.\n\n${body}`;
 }