dewctl 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dewdrop Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# dewctl
+
+The Dewdrop CLI builds your three.js game, uploads it to Dewdrop as you work,
+and publishes it for players.
+
+## Start a game
+
+In a new, empty folder, with Node.js 24 or newer:
+
+```sh
+npx dewctl init
+npm install
+npx dewctl login
+npx dewctl dev --watch
+```
+
+`dev --watch` prints a link to play your game and uploads it again each time
+you save. When it's ready, `npx dewctl publish` puts it in front of players.
+
+## Docs
+
+The development flow, every command, `dewdrop.json` and troubleshooting are in
+the docs: https://alpha.dewdrop.world/docs
+
+## License
+
+MIT

package/examples/starter/index.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>My game</title>
+  </head>
+  <body>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/examples/starter/main.js

@@ -0,0 +1,34 @@
+// Your game. Save a change while `dewctl dev --watch` runs and the game on Dewdrop updates.
+import * as THREE from 'three';
+
+const scene=new THREE.Scene();
+scene.background=new THREE.Color('#142232');
+const camera=new THREE.PerspectiveCamera(55,innerWidth/innerHeight,0.1,100);
+camera.position.set(0,0,5);
+const renderer=new THREE.WebGLRenderer();
+// On Dewdrop, describe the look of your whole game here…
+renderer.prompt='A polished turquoise cube floating in a dark blue studio, soft cinematic lighting, clean stylized 3D game art.';
+renderer.setSize(innerWidth,innerHeight);
+document.body.appendChild(renderer.domElement);
+const cube=new THREE.Mesh(new THREE.BoxGeometry(1.5,1.5,1.5),new THREE.MeshStandardMaterial({color:'#4edbb1',roughness:0.65}));
+// …and what this mesh is.
+cube.userData.description='A polished turquoise cube';
+scene.add(cube);
+scene.add(new THREE.AmbientLight(0xffffff,1));
+const light=new THREE.DirectionalLight(0xffffff,2);
+light.position.set(3,4,5);
+scene.add(light);
+const heading=document.createElement('h1');
+heading.textContent='Hello from your Dewdrop game';
+heading.style.cssText='position:absolute;top:20px;left:24px;color:white;font:24px sans-serif;';
+document.body.appendChild(heading);
+addEventListener('resize',()=>{
+  camera.aspect=innerWidth/innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(innerWidth,innerHeight);
+});
+renderer.setAnimationLoop(time=>{
+  cube.rotation.x=time/2400;
+  cube.rotation.y=time/1800;
+  renderer.render(scene,camera);
+});

package/examples/starter/vite.config.js

@@ -0,0 +1,3 @@
+import dew from 'dewdrop-sdk/vite';
+
+export default { plugins: [dew()] };

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "dewctl",
+  "version": "0.5.0",
+  "description": "Build and publish three.js games on Dewdrop.",
+  "license": "MIT",
+  "type": "module",
+  "bin": { "dewctl": "src/main.js" },
+  "files": ["src", "examples", "README.md"],
+  "engines": { "node": ">=24" },
+  "scripts": { "test": "node --test tests/*.test.js" }
+}

package/src/client.js

@@ -0,0 +1,95 @@
+// Requests to Dewdrop, only ever to the address in dewdrop.json, signed in with the session login stored.
+import {RUN} from './command.js';
+export class ApiError extends Error {
+  constructor(status,message){super(message);this.status=status;}
+}
+// A member's address becomes a path segment; refuse anything that could reach another route.
+const EMAIL=/^[^\s@/?#%]+@[^\s@/?#%]+\.[^\s@/?#%]+$/;
+export function sleep(ms,signal) {
+  return new Promise((resolve,reject)=>{
+    const timer=setTimeout(done,ms);
+    function done(){signal?.removeEventListener('abort',cancel);resolve();}
+    function cancel(){clearTimeout(timer);reject(signal.reason);}
+    if(signal?.aborted)cancel();else signal?.addEventListener('abort',cancel,{once:true});
+  });
+}
+// An upload is sent in parts of at most this many bytes.
+export const PART_BYTES=32*1024*1024;
+export class Client {
+  constructor(origin,credentials,{fetcher=fetch,pollMs=1000,timeoutMs=180000}={}){this.origin=origin;this.credentials=credentials;this.fetcher=fetcher;this.pollMs=pollMs;this.timeoutMs=timeoutMs;}
+  // A request signed in with `token`. When Dewdrop can't be reached the failure is marked transient, which a watcher
+  // or a sign-in waits out; a refused token asks for a new sign-in, whatever Dewdrop's words.
+  async request(path,{method='GET',body,token,signal,type}={}) {
+    if(!path.startsWith('/v1/'))throw new Error('Invalid API path.');
+    const bytes=Buffer.isBuffer(body);
+    let response;
+    try {
+      response=await this.fetcher(this.origin+path,{method,redirect:'error',signal:signal?AbortSignal.any([signal,AbortSignal.timeout(120000)]):AbortSignal.timeout(120000),headers:{...(token?{authorization:`Bearer ${token}`}:{}),...(body!==undefined?{'content-type':type??(bytes?'application/octet-stream':'application/json')}:{})},body:body===undefined?undefined:bytes||typeof body==='string'?body:JSON.stringify(body)});
+    } catch(error) {
+      if(signal?.aborted)throw error;
+      const reason=error.name==='TimeoutError'?'no answer in two minutes':error.cause?.code??error.cause?.message??error.message;
+      throw Object.assign(new Error(`Couldn't reach ${this.origin} (${reason}). Check your connection.`),{transient:true});
+    }
+    const contentType=response.headers.get('content-type')??'';
+    if(!contentType.includes('application/json'))throw new ApiError(response.status,`${this.origin} didn't answer as Dewdrop does (HTTP ${response.status}). Try again in a moment.`);
+    const data=await response.json();
+    if(response.status===401&&token)throw new ApiError(401,`Your sign-in has ended: it expired or was signed out. Run ${RUN} login.`);
+    if(!response.ok)throw new ApiError(response.status,data.error??`HTTP ${response.status}`);
+    return data;
+  }
+  // The session this computer holds, or why there is none to use.
+  session() {
+    const current=this.credentials.stored();
+    if(!current)throw new ApiError(401,`You're not signed in. Run ${RUN} login.`);
+    if(typeof current.expires==='number'&&Date.now()>=current.expires)throw new ApiError(401,`Your sign-in expired on ${new Date(current.expires).toISOString().slice(0,10)}. Run ${RUN} login.`);
+    return current;
+  }
+  async api(path,options={}){return this.request(path,{...options,token:this.session().token});}
+  game(game,signal){return this.api(`/v1/games/${game}`,{signal});}
+  releases(game){return this.api(`/v1/games/${game}/releases`);}
+  // Makes the game this developer's if it is new, and confirms it is theirs if not: asked before anything is built, so
+  // a name someone else has, or a sign-in that has ended, is known at once.
+  async claim(game,signal) {
+    try { return await this.api(`/v1/games/${game}`,{method:'PUT',body:{},signal}); }
+    catch(error) {
+      if(error.status===409&&/owns this game name/.test(error.message))throw new ApiError(409,`Someone else already has a game named ${game}. Choose another name: change "game" in dewdrop.json.`);
+      throw error;
+    }
+  }
+  // Uploads a build of a claimed game under its id, in parts of PART_BYTES, then completes it with the number of
+  // parts; Dewdrop must confirm the same id.
+  async upload(game,bundle,signal) {
+    const parts=Math.max(1,Math.ceil(bundle.body.length/PART_BYTES));
+    for(let index=0;index<parts;index++) {
+      await this.api(`/v1/games/${game}/releases/${bundle.id}/parts/${index}`,{method:'PUT',body:bundle.body.subarray(index*PART_BYTES,(index+1)*PART_BYTES),signal});
+    }
+    const result=await this.api(`/v1/games/${game}/releases/${bundle.id}`,{method:'POST',body:{parts},signal});
+    if(result.release!==bundle.id)throw new Error('Dewdrop stored a different release than was uploaded, so nothing was changed. Try again.');
+    return result;
+  }
+  activate(game,release,signal){return this.point(game,'dev',release,signal);}
+  stop(game,signal){return this.point(game,'dev',null,signal);}
+  publish(game,release,signal){return this.point(game,'live',release,signal);}
+  // Points a version at a release, then follows the game until that version is ready, fails, or somebody points it
+  // elsewhere. The PUT answers with the game, so it is the first look.
+  async point(game,version,release,signal) {
+    let state=await this.api(`/v1/games/${game}/${version}`,{method:'PUT',body:{release},signal});
+    if(release===null&&version==='live')return state;
+    const doing=release===null?'Stopping the dev version':version==='dev'?'Starting the dev version':'Publishing',deadline=Date.now()+this.timeoutMs;
+    for(;;) {
+      const current=state[version],now=current.release?.slice(0,12);
+      if(current.release!==release)throw new Error(version==='live'?`The published version changed meanwhile: it is now ${now??'unpublished'}.`:`The dev version changed meanwhile: it now ${now?`runs ${now}`:'is stopped'}.`);
+      if(current.error)throw new Error(current.error);
+      if(current.ready)return state;
+      if(Date.now()>=deadline)throw new Error(`${doing} is taking longer than three minutes. Run ${RUN} status to follow it.`);
+      await sleep(this.pollMs,signal);
+      state=await this.game(game,signal);
+    }
+  }
+  // Sets the game's thumbnail to the image, sent as itself under its type.
+  thumbnail(game,bytes,type,signal){return this.api(`/v1/games/${game}/thumbnail`,{method:'PUT',body:bytes,type,signal});}
+  async member(game,email,on,signal) {
+    if(!EMAIL.test(email??''))throw new Error("Pass the developer's email address, for example dev@example.com.");
+    return this.api(`/v1/games/${game}/members/${email}`,on?{method:'PUT',body:{},signal}:{method:'DELETE',signal});
+  }
+}

package/src/command.js

@@ -0,0 +1,2 @@
+// How the developer runs this CLI, for the commands its messages suggest: through npx when npx started it, else by name.
+export const RUN=process.env.npm_command==='exec'?'npx dewctl':'dewctl';

package/src/credentials.js

@@ -0,0 +1,92 @@
+// The developer's sign-in, kept in an owner-only JSON file under ~/.dewdrop. A login's write and a logout's
+// compare-and-clear exclude each other across processes through a lock beside the file, held for the few
+// milliseconds either takes; a lock nobody releases is reported. A session past its expiry reads as absent, yet a
+// logout that saw its token still clears it.
+import {mkdirSync, openSync, closeSync, fstatSync, readFileSync, writeFileSync, renameSync, unlinkSync, constants, lstatSync, existsSync} from 'node:fs';
+import {join, dirname, resolve} from 'node:path';
+import {homedir} from 'node:os';
+import {createHash,randomBytes} from 'node:crypto';
+
+const LOCK_TRIES=100,LOCK_WAIT_MS=20;
+
+export class Credentials {
+  constructor(origin,{file=process.env.DEWDROP_CREDENTIALS_FILE}={}) {
+    this.origin=origin;
+    this.file=resolve(file||join(homedir(),'.dewdrop',`${origin.replace(/[^a-zA-Z0-9.-]+/g,'_').slice(0,40)}-${createHash('sha256').update(origin).digest('hex').slice(0,16)}.json`));
+  }
+  fileCheck(path,fd) {
+    const stat=fd===undefined?lstatSync(path):fstatSync(fd);
+    if(!stat.isFile() || (stat.mode&0o077)!==0 || process.getuid && stat.uid!==process.getuid())throw new Error(`${path} holds your sign-in, so it must be a file only you can read. Run: chmod 600 ${path}`);
+  }
+  // The folder the sign-in is kept in, made if missing and checked private to this user; login checks it before it
+  // asks anyone to approve a link, so a sign-in is never approved only to find nowhere to keep it.
+  prepare() {
+    const dir=dirname(this.file);
+    mkdirSync(dir,{recursive:true,mode:0o700});
+    const parent=lstatSync(dir);
+    if(!parent.isDirectory() || (parent.mode&0o077)!==0 || process.getuid && parent.uid!==process.getuid())throw new Error(`${dir} holds your sign-in, so it must be a folder only you can open. Run: chmod 700 ${dir}`);
+    if(existsSync(this.file))this.fileCheck(this.file);
+    return dir;
+  }
+  // The stored session regardless of expiry, or null when none is kept. A file holding another address's session, or
+  // one anyone but the owner can read, is refused rather than used. `clear` compares against this so a session that
+  // expired between a logout's read and its request can still be removed.
+  stored() {
+    let fd;
+    try {fd=openSync(this.file,constants.O_RDONLY|constants.O_NOFOLLOW);}
+    catch(error){if(error.code==='ENOENT')return null;throw error;}
+    let row;
+    try {this.fileCheck(this.file,fd);row=JSON.parse(readFileSync(fd,'utf8'));}
+    finally{closeSync(fd);}
+    if(row.origin!==this.origin)throw new Error(`${this.file} holds a sign-in for ${row.origin}, not ${this.origin}.`);
+    return row.session??null;
+  }
+  // The stored session, or null when none is kept or the kept one has passed its expiry.
+  read() {
+    const session=this.stored();
+    if(session&&typeof session.expires==='number'&&Date.now()>=session.expires)return null;
+    return session;
+  }
+  lockPath(){return `${this.file}.lock`;}
+  // Runs `fn` holding the file's lock, so no other dewctl process writes or clears it meanwhile.
+  locked(fn) {
+    mkdirSync(dirname(this.file),{recursive:true,mode:0o700});
+    const lock=this.lockPath();
+    let fd;
+    for(let attempt=0;fd===undefined;attempt++) {
+      try{fd=openSync(lock,constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL,0o600);}
+      catch(error){
+        if(error.code!=='EEXIST')throw error;
+        if(attempt>=LOCK_TRIES)throw new Error(`Another dewctl is using your sign-in right now. If none is running, remove ${lock}.`);
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,LOCK_WAIT_MS);
+      }
+    }
+    try{return fn();}
+    finally{closeSync(fd);unlinkSync(lock);}
+  }
+  write(session) {
+    const dir=this.prepare();
+    this.locked(()=>{
+      if(existsSync(this.file))this.fileCheck(this.file);
+      const temp=join(dir,`.session-${randomBytes(8).toString('hex')}`);
+      writeFileSync(temp,JSON.stringify({origin:this.origin,session}),{flag:'wx',mode:0o600});
+      renameSync(temp,this.file);
+    });
+  }
+  // Removes the stored session only while the file still holds what the caller saw — the token `expected`, or
+  // nothing when `expected` is null — under the file's lock, so a logout that raced a fresh login leaves the new
+  // session alone. Answers whether the file is now clear of what the caller saw.
+  clear(expected) {
+    if(expected!==null&&typeof expected!=='string')throw new Error('clear takes the token seen, or null for none.');
+    // No credential directory holds nothing: nothing to lock or remove.
+    if(!existsSync(dirname(this.file)))return expected===null;
+    return this.locked(()=>{
+      const raw=this.stored();
+      // A named token clears while the file still holds it, expiry aside. `null` — what logout passes when it read
+      // no usable session — clears an absent or expired one, but keeps a fresh login stored meanwhile.
+      if(expected===null?(raw!==null&&!(typeof raw.expires==='number'&&Date.now()>=raw.expires)):(!raw||raw.token!==expected))return false;
+      try{unlinkSync(this.file);}catch(e){if(e.code!=='ENOENT')throw e;}
+      return true;
+    });
+  }
+}

package/src/login.js

@@ -0,0 +1,35 @@
+// Signing in by link. The CLI makes its own sign-in token and prints a link carrying the token's hash, not the token,
+// and this computer's name; the developer opens it, checks that it shows the code printed here, and approves it.
+// Meanwhile the CLI asks Dewdrop, with the token, whose it is, which Dewdrop answers once the link is approved.
+import {createHash,randomBytes} from 'node:crypto';
+import {hostname} from 'node:os';
+import {sleep} from './client.js';
+import {RUN} from './command.js';
+
+// This computer's name as the link carries it: its host name without a trailing .local, in the plain characters
+// Dewdrop accepts.
+export function machineLabel(name=hostname()) {
+  const label=String(name).replace(/\.local$/i,'').replace(/[^\w .@()-]+/g,'-').replace(/^[-\s]+|[-\s]+$/g,'').slice(0,80).trim();
+  return label||'computer';
+}
+// A fresh token and the link that asks Dewdrop to approve it, with the code both the page and the terminal show:
+// the first eight hex digits of the token's hash.
+export function signInLink(origin,{token=randomBytes(32).toString('base64url'),name=hostname()}={}) {
+  const hash=createHash('sha256').update(token).digest('hex'),label=machineLabel(name);
+  return {token,code:`${hash.slice(0,4)}-${hash.slice(4,8)}`.toUpperCase(),label,url:`${origin}/account/cli?h=${hash}&label=${encodeURIComponent(label)}`};
+}
+// The account the token belongs to, once the link is approved. Until then Dewdrop refuses the token (401); a busy or
+// briefly unreachable Dewdrop is waited out too. Anything else is a real failure and ends the wait.
+export async function waitForApproval(client,token,{signal,pollMs=2000,timeoutMs=10*60*1000}={}) {
+  const deadline=Date.now()+timeoutMs;
+  for(;;) {
+    try { return await client.request('/v1/me',{token,signal}); }
+    catch(error) {
+      if(signal?.aborted)throw signal.reason;
+      const waiting=error.status===401||error.status===429||error.status>=500||error.transient;
+      if(!waiting)throw error;
+    }
+    if(Date.now()>=deadline)throw new Error(`Nobody approved the sign-in link in ten minutes. Run ${RUN} login again.`);
+    await sleep(pollMs,signal);
+  }
+}

package/src/main.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+// Dewdrop's developer commands: sign in, connect a directory to a game, then run, publish, share and inspect it.
+import {spawn} from 'node:child_process';
+import {readFileSync} from 'node:fs';
+import {readProject,platformOrigin,initProject,DEWDROP} from './project.js';
+import {Credentials} from './credentials.js';
+import {Client} from './client.js';
+import {deploy,watch,size} from './watch.js';
+import {devPlayUrl} from './play.js';
+import {signInLink,waitForApproval} from './login.js';
+import {RUN} from './command.js';
+import {syncThumbnail} from './thumbnail.js';
+
+const HELP=`${RUN} — make three.js games on Dewdrop
+
+  init [--game NAME]                       Connect this folder to a game; an empty folder gets the starter game.
+                                           The game is named after the folder unless --game names it
+  login                                    Sign in: prints a link to open in your browser and approve
+  logout                                   Sign this computer out
+  dev [--watch] [--release ID]             Build, upload and play the dev version; --watch repeats this on every
+                                           save, --release plays an earlier upload without building
+  stop                                     Stop the dev version and disconnect its players; uploads are kept
+  publish [--release ID]                   Publish the dev version, or an earlier upload, for players; uploads
+                                           the thumbnail dewdrop.json names when it has changed
+  unpublish                                Take the game down for players
+  share EMAIL                              Let another developer play and update the dev version
+  unshare EMAIL                            Take that back
+  status                                   Show the dev and published versions and where to play them
+  releases                                 List your uploads; any id, or its first 8 characters, feeds --release
+  --version                                Show this CLI's version
+
+  Run the commands in your game's folder: they read the game from its dewdrop.json.
+  Docs: ${DEWDROP}/docs
+`;
+// Each command's flags; share and unshare also take one address. Anything else on the line is refused.
+const COMMANDS={init:['--game'],login:[],logout:[],dev:['--watch','--release'],stop:[],publish:['--release'],unpublish:[],share:[],unshare:[],status:[],releases:[]};
+const VALUED=['--game','--release'];
+function options(command,args) {
+  const out={};
+  for(let i=0;i<args.length;i++) {
+    const key=args[i];
+    if(COMMANDS[command].includes(key)) {
+      if(!VALUED.includes(key))out[key.slice(2)]=true;
+      else if(!args[i+1]||args[i+1].startsWith('--'))throw new Error(`${key} needs a value.`);
+      else out[key.slice(2)]=args[++i];
+    } else if(['share','unshare'].includes(command)&&!key.startsWith('-')&&out.email===undefined)out.email=key;
+    else throw new Error(`${command} doesn't take ${key}. Run ${RUN} --help to see what it takes.`);
+  }
+  if(out.release!==undefined&&!/^[a-f0-9]{8,64}$/.test(out.release))throw new Error(`--release takes a release id, or its first 8 or more characters, from ${RUN} releases.`);
+  if(out.watch&&out.release)throw new Error('Choose --watch or --release, not both.');
+  return out;
+}
+// Opens the link in this computer's browser. login prints the link too, so a browser that won't start is no failure.
+function open(url) {
+  const command=process.platform==='darwin'?'open':'xdg-open';
+  const child=spawn(command,[url],{stdio:'ignore',detached:true});
+  child.on('error',()=>{});
+  child.unref();
+}
+// A browser is opened for a person at this computer's own screen: never over SSH, and on Linux only with a display.
+const atScreen=()=>Boolean(process.stdout.isTTY&&!process.env.SSH_CONNECTION&&!process.env.SSH_TTY&&(process.platform!=='linux'||process.env.DISPLAY||process.env.WAYLAND_DISPLAY));
+// A version as status prints it: its release and whether that is loading, ready or failed, or else whether it stopped.
+function describe(pointer,idle) {
+  if(pointer.release)return `${pointer.release.slice(0,12)}, ${pointer.error?`failed: ${pointer.error}`:pointer.ready?'ready':'loading'}`;
+  if(pointer.error)return `couldn't stop: ${pointer.error}`;
+  return pointer.ready?idle:'stopping';
+}
+// Columns padded to their widest cell, for the lists the CLI prints.
+const columns=rows=>{const widths=rows[0].map((_,i)=>Math.max(...rows.map(row=>String(row[i]).length)));return rows.map(row=>row.map((cell,i)=>i===row.length-1?cell:String(cell).padEnd(widths[i])).join('  ')).join('\n');};
+// A release named by its whole id or its first characters, from the game's uploads.
+async function releaseId(client,game,id) {
+  if(id.length===64)return id;
+  const matches=(await client.releases(game)).releases.filter(release=>release.sha256.startsWith(id));
+  if(matches.length===1)return matches[0].sha256;
+  throw new Error(matches.length?`${id} matches ${matches.length} releases; give more of its characters.`:`No upload of ${game} starts with ${id}. Run ${RUN} releases to list them.`);
+}
+async function main() {
+  // The paths, permissions and processes the CLI relies on are POSIX ones.
+  if(process.platform==='win32')throw new Error('The Dewdrop CLI runs on macOS and Linux. On Windows, run it inside WSL (Windows Subsystem for Linux).');
+  const [command,...args]=process.argv.slice(2);
+  if(!command||['--help','help','-h'].includes(command)||args.some(arg=>arg==='--help'||arg==='-h')){console.log(HELP);return;}
+  if(['--version','-v','version'].includes(command)){console.log(JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version);return;}
+  if(!Object.hasOwn(COMMANDS,command))throw new Error(`There's no ${command} command. Run ${RUN} --help to see them.`);
+  const flags=options(command,args);
+  if(command==='init') {
+    const config=initProject(process.cwd(),flags.game);
+    const run=RUN;
+    if(config.starter)console.log(`Set up ${config.game} here. Next:\n  npm install\n  ${run} login\n  ${run} dev --watch\nThe game is created on Dewdrop the first time you run dev. To try it here without Dewdrop, run npm run dev.`);
+    else console.log(`Created dewdrop.json for ${config.game}. Next: ${run} login, then ${run} dev --watch.`);
+    if(config.buildScript==='build')console.log('Using your build script (npm run build) to build for Dewdrop. It must build with the Dewdrop plugin (vite build --mode dew); if it doesn\'t, add a build:dew script that does and set "build" in dewdrop.json to ["npm","run","build:dew"].');
+    if(!config.starter&&!config.buildScript)console.log('No build:dew or build script is in package.json, so dewdrop.json builds with npm run build:dew. Add that script, building with the Dewdrop plugin (vite build --mode dew), or set "build" in dewdrop.json to your own command.');
+    return;
+  }
+  // Every command but init reads the game from the project's dewdrop.json.
+  const project=readProject(process.cwd());
+  const origin=platformOrigin();
+  const credentials=new Credentials(origin),client=new Client(origin,credentials);
+  // The commands that wait on Dewdrop stop waiting at Ctrl-C; the rest end the ordinary way.
+  const controller=new AbortController(),{signal}=controller;
+  if(['login','stop','unpublish','publish','dev'].includes(command)) {
+    process.once('SIGINT',()=>controller.abort(new Error('Stopped.')));
+    process.once('SIGTERM',()=>controller.abort(new Error('Stopped.')));
+  }
+  // login makes a sign-in token and prints the link that approves it; the token is kept once Dewdrop says whose it is.
+  if(command==='login') {
+    credentials.prepare();
+    const link=signInLink(origin);
+    console.log(`Open this link to sign in the Dewdrop CLI:\n\n  ${link.url}\n\nCheck that the page shows ${link.code}, then choose Sign in the CLI. Waiting…`);
+    if(atScreen())open(link.url);
+    let me;
+    try { me=await waitForApproval(client,link.token,{signal}); }
+    catch(error) { throw signal.aborted?new Error('Sign-in cancelled.'):error; }
+    credentials.write({token:link.token,email:me.email,expires:me.expires});
+    console.log(`Signed in as ${me.username??me.email}.`);
+    return;
+  }
+  if(command==='logout') {
+    const session=credentials.read();
+    if(session) {
+      try { await client.request('/v1/logout',{method:'POST',token:session.token,body:{}}); }
+      catch(error) { if(error.status!==401)throw error; }
+    }
+    // The store is cleared only while it still holds what was read — a login that ran meanwhile stored a newer token, and that one stays.
+    if(!credentials.clear(session?.token??null)){console.log(session?'Signed out; a newer sign-in on this computer is kept.':'A sign-in on this computer finished meanwhile and is kept.');return;}
+    console.log(session?'Signed out.':'You weren\'t signed in.');
+    return;
+  }
+  const game=project.game;
+  if(command==='status') {
+    let state;
+    try { state=await client.game(game); }
+    catch(error) { if(error.status===404)throw new Error(`${game} isn't on Dewdrop yet. Run ${RUN} dev to create it.`); throw error; }
+    const url=devPlayUrl(state);
+    console.log(`${game}\n  Dev version:  ${describe(state.dev,'stopped')}${state.dev.release?` — ${url}`:''}\n  Published:    ${describe(state.live,'not published')}${state.live.release?` — ${state.urls.play}`:''}\n  Thumbnail:    ${state.urls.thumbnail??'none'}`);
+    return;
+  }
+  if(command==='releases'){
+    const {releases}=await client.releases(game);
+    if(!releases.length){console.log(`No uploads of ${game} yet. Run ${RUN} dev to make one.`);return;}
+    console.log(columns([['RELEASE','UPLOADED (UTC)','SIZE','BY'],...releases.map(release=>[release.sha256.slice(0,12),new Date(release.created).toISOString().slice(0,16).replace('T',' '),size(release.bytes),release.email])]));
+    return;
+  }
+  if(['share','unshare'].includes(command)) {
+    if(!flags.email)throw new Error(`${command} needs the developer's email address.`);
+    await client.member(game,flags.email,command==='share');
+    console.log(command==='share'?`Shared ${game} with ${flags.email}. They can play and update the dev version.`:`Removed ${flags.email} from ${game}.`);
+    return;
+  }
+  if(command==='stop'){
+    await client.stop(game,signal);
+    console.log(`Stopped ${game}'s dev version. Its uploads are kept; run ${RUN} dev to start it again.`);return;
+  }
+  if(command==='unpublish'){await client.publish(game,null,signal);console.log(`Unpublished ${game}. Players can no longer open it.`);return;}
+  if(command==='publish') {
+    const current=await client.game(game,signal);
+    const release=flags.release?await releaseId(client,game,flags.release):current.dev.release;
+    if(!release)throw new Error(`${game} has no dev version to publish. Run ${RUN} dev first, or publish an earlier upload with --release (see ${RUN} releases).`);
+    // The thumbnail goes first, so an image Dewdrop refuses stops the publish before anything changes for players.
+    if(project.thumbnail&&await syncThumbnail(project,client,current,signal))console.log(`Uploaded the thumbnail, ${project.thumbnail}.`);
+    const state=await client.publish(game,release,signal);
+    console.log(`Published ${release.slice(0,12)}. Players can open ${game} at ${state.urls.play}`);return;
+  }
+  if(flags.release){
+    const release=await releaseId(client,game,flags.release);
+    const state=await client.activate(game,release,signal);
+    console.log(`Playing ${release.slice(0,12)} at ${devPlayUrl(state)}`);return;
+  }
+  if(flags.watch)await watch(project,client,{signal,reread:()=>readProject(project.root)});
+  else if((await deploy(project,client,{signal})).changed)throw new Error(`Files changed during the build, so nothing was uploaded. Run ${RUN} dev again, or ${RUN} dev --watch to rebuild on every save.`);
+}
+main().catch(error=>{console.error(`dewctl: ${error.message}`);process.exitCode=1;});

package/src/play.js

@@ -0,0 +1,5 @@
+// The dev version's play link, the same for every upload, so reopening it or a reload after a watched save rejoins
+// the same room, playing as the signed-in developer.
+export function devPlayUrl(game) {
+  return `${game.urls.dev}/dev`;
+}

package/src/project.js

@@ -0,0 +1,206 @@
+// The project as dewdrop.json describes it, its build, and the archive its bundle folder is uploaded as.
+import {readFileSync, writeFileSync, existsSync, lstatSync, readdirSync, openSync, closeSync, fstatSync, readSync, constants, realpathSync, mkdirSync, rmSync} from 'node:fs';
+import {resolve, relative, join, isAbsolute, basename, dirname} from 'node:path';
+import {createHash,randomBytes} from 'node:crypto';
+import {spawn} from 'node:child_process';
+import {packTar} from './tar.js';
+import {RUN} from './command.js';
+
+const MAX_BYTES = 1024 * 1024 * 1024;
+const ignored = new Set(['node_modules','dist','target']);
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const GAME_NAME = /^[a-z][a-z0-9-]{0,47}$/;
+export const DEWDROP = 'https://alpha.dewdrop.world';
+// Dewdrop's address, or the one DEWDROP_PLATFORM names for tests: an https:// origin, or plain http:// to this
+// computer's own loopback address, which a credential never leaves. The slash an address bar adds is the same origin.
+export function platformOrigin(value = process.env.DEWDROP_PLATFORM ?? DEWDROP) {
+  const url = URL.parse(value);
+  if (!url || (url.origin !== value && `${url.origin}/` !== value) || !(url.protocol === 'https:' || url.protocol === 'http:' && url.hostname === '127.0.0.1')) {
+    throw new Error(`DEWDROP_PLATFORM must be an https:// address with no path, like https://example.com, not ${value}.`);
+  }
+  return url.origin;
+}
+export function projectPath(root, path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\\') || path.split('/').some(p=>p === '..' || p === '.' || !p)) throw new Error(`Path must be relative to the project: ${path}`);
+  const file = resolve(root,path);
+  if (!file.startsWith(`${resolve(root)}/`)) throw new Error(`Path leaves the project: ${path}`);
+  return file;
+}
+export function readProject(root = process.cwd()) {
+  root = realpathSync(root);
+  const file = join(root,'dewdrop.json');
+  if (!existsSync(file)) throw new Error(`No dewdrop.json here. Run this in your game's folder, or ${RUN} init to start one.`);
+  let config;
+  try { config = JSON.parse(readFileSync(file,'utf8')); }
+  catch (error) { throw new Error(`dewdrop.json isn't valid JSON: ${error.message}`); }
+  if (config.version !== 1) throw new Error('dewdrop.json needs "version": 1.');
+  if (!GAME_NAME.test(config.game ?? '')) throw new Error("Set game in dewdrop.json to the game's name (for example my-game).");
+  projectPath(root,config.bundle);
+  if (config.thumbnail !== undefined) projectPath(root,config.thumbnail);
+  if (config.build !== undefined && (!Array.isArray(config.build) || !config.build.length || config.build.some(v=>typeof v !== 'string' || !v || v.includes('\0')))) throw new Error('build must be an argument array, such as ["npm","run","build:dew"].');
+  return {...config,root};
+}
+
+// Opens a file of the project as a regular file under `root` and no symlink, hands `fn` its descriptor, and closes it.
+function opened(file, root, fn) {
+  const actual = realpathSync(file);
+  if (!actual.startsWith(`${root}/`) || actual !== file) throw new Error(`Symlinks cannot be uploaded: ${file}`);
+  const fd = openSync(file,constants.O_RDONLY|constants.O_NOFOLLOW);
+  try {
+    const stat=fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_BYTES) throw new Error(`Not a regular file under 1 GiB: ${file}`);
+    return fn(fd,stat);
+  } finally { closeSync(fd); }
+}
+const readRegular=(file,root)=>opened(file,root,fd=>readFileSync(fd));
+// Copies the file's `size` bytes into `target` at `offset`, straight from the descriptor, and answers how many it
+// copied: a file whose size changed since it was walked copies another number, and the archive refuses it.
+function readInto(file, root, size, target, offset) {
+  return opened(file,root,(fd,stat)=>{
+    if (stat.size!==size) return stat.size;
+    let copied=0;
+    while (copied<size) {
+      const count=readSync(fd,target,offset+copied,size-copied,copied);
+      if (count===0) break;
+      copied+=count;
+    }
+    return copied;
+  });
+}
+// Every regular file under `start`, by its path under `root`, with its size: what is walked is not read, so a
+// bundle over the budget is refused on its sizes alone and the files are read once, into the archive. Names starting
+// with a dot are always left out; watching also leaves out the bundle folder, node_modules, dist and target, and
+// passes over the symlinks an upload refuses.
+function walk(root, start, files, {watch = false, output, budget = {bytes:0}} = {}) {
+  if (watch && (start === output || start.startsWith(`${output}/`))) return;
+  if (!existsSync(start)) return;
+  const stat=lstatSync(start);
+  if (stat.isSymbolicLink()) {
+    if (watch) return;
+    throw new Error(`Symlinks cannot be uploaded: ${start}`);
+  }
+  if (stat.isDirectory()) {
+    for (const name of readdirSync(start).sort()) {
+      if (name.startsWith('.') || watch && ignored.has(name)) continue;
+      walk(root,join(start,name),files,{watch,output,budget});
+    }
+  } else {
+    if (files.size >= 4096) throw new Error(watch ? 'More than 4096 files are in the project folder, too many for dev to follow. Move what the game doesn\'t need out of it (node_modules, dist, target, the bundle folder and names starting with a dot don\'t count).' : 'The build\'s output has more than 4096 files, the most Dewdrop takes.');
+    if (!watch && (budget.bytes += stat.size) > MAX_BYTES) throw new Error('The build\'s output is over 1 GiB, the most Dewdrop takes.');
+    files.set(relative(root,start).split('\\').join('/'),{file:start,size:stat.size});
+  }
+}
+// The project's files as one digest of their paths and bytes, which changes whenever any file the walk follows does.
+export function fingerprint(project) {
+  const files=new Map();
+  walk(project.root,project.root,files,{watch:true,output:projectPath(project.root,project.bundle)});
+  const digest=createHash('sha256');
+  for (const [path,{file}] of [...files].sort(([a],[b])=>a<b?-1:1)) { const data=readRegular(file,project.root); digest.update(`${path}\0${data.length}\0`).update(data); }
+  return digest.digest('hex');
+}
+export function snapshot(project) {
+  const directory=projectPath(project.root,project.bundle);
+  if (!existsSync(directory)) throw new Error(project.build
+    ? `The build wrote no ${project.bundle} folder. Set "bundle" in dewdrop.json to the folder your Dewdrop build (vite build --mode dew) writes.`
+    : `There's no ${project.bundle} folder to upload. Build the game first, or set "build" in dewdrop.json so ${RUN} dev builds it.`);
+  const root=realpathSync(directory);
+  if (root!==directory) throw new Error(`The ${project.bundle} folder can't be a symlink.`);
+  const files=new Map();
+  walk(root,root,files);
+  // The Dewdrop build writes main.js at the top of its output; one deeper down means "bundle" names the folder above it.
+  if (!files.has('main.js')) {
+    const nested=[...files.keys()].filter(path=>path.endsWith('/main.js')).sort((a,b)=>a.split('/').length-b.split('/').length)[0];
+    throw new Error(nested
+      ? `There's no main.js at the top of ${project.bundle}, but there is ${project.bundle}/${nested}. Set "bundle": "${project.bundle}/${dirname(nested)}" in dewdrop.json.`
+      : `There's no main.js in ${project.bundle}. Build with the Dewdrop plugin (vite build --mode dew), and set "bundle" in dewdrop.json to the folder that build writes.`);
+  }
+  let bytes=0;
+  const entries=[...files].map(([path,{file,size}])=>{
+    if (path.length>240 || !path.split('/').every(p=>/^[A-Za-z0-9_][A-Za-z0-9_. -]*$/.test(p)&&!p.endsWith('.')&&!p.endsWith(' '))) throw new Error(`Can't upload ${path}: a name in it must start with a letter, digit or _ and hold only letters, digits, _, ., - and spaces, and the whole path must be under 240 characters.`);
+    bytes+=size;
+    return {path,size,read:(target,offset)=>readInto(file,root,size,target,offset)};
+  });
+  // The same files always make the same bytes, which give the upload its id.
+  const body=packTar(entries);
+  return {body,id:hash(body),bytes,files:files.size};
+}
+export async function build(project, signal) {
+  if (!project.build) return;
+  signal?.throwIfAborted();
+  const [command,...args]=project.build;
+  const group=process.platform!=='win32';
+  await new Promise((resolve,reject)=>{
+    const child=spawn(command,args,{cwd:project.root,stdio:'inherit',shell:false,detached:group});
+    function kill(which) {
+      try { if(group&&child.pid)process.kill(-child.pid,which);else child.kill(which); }
+      catch(error) { if(error.code!=='ESRCH')reject(error); }
+    }
+    function cancel() {
+      kill('SIGTERM');
+      // npm may exit before its build grandchildren; keep the process group bounded too.
+      setTimeout(()=>kill('SIGKILL'),1000);
+    }
+    function cleanup() { signal?.removeEventListener('abort',cancel); }
+    child.once('error',error=>{cleanup();reject(new Error(`Couldn't run ${command} (${error.code==='ENOENT'?'not found':error.message}). Check "build" in dewdrop.json.`));});
+    child.once('exit',(code,sig)=>{
+      cleanup();
+      if(signal?.aborted)reject(signal.reason);
+      else if(code===0)resolve();
+      else reject(new Error(`The build (${project.build.join(' ')}) failed with ${sig?`signal ${sig}`:`exit code ${code}`}; the dev version is unchanged.`));
+    });
+    signal?.addEventListener('abort',cancel,{once:true});
+    if(signal?.aborted)cancel();
+  });
+}
+// The one project shape: a Vite project with the SDK's plugin, which previews locally with `npm run dev` and
+// builds for Dewdrop with `npm run build:dew`. A directory holding none of the starter's files gets the
+// starter game, depending on the SDK and this CLI from npm; one holding any of them has a game of its own and gets
+// dewdrop.json alone, so nothing of it is touched and no starter is left half written.
+const STARTER_FILES=['package.json','src','index.html','vite.config.js'];
+// The SDK a new game depends on, and this CLI, at its own version.
+const SDK_RANGE='^0.3.1';
+const CLI_RANGE=`^${JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version}`;
+// A game name from the project directory, or a random one when the directory name yields nothing usable.
+function gameNameFrom(root) {
+  const slug=basename(resolve(root)).toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^[^a-z]+/,'').replace(/-+$/,'').slice(0,48).replace(/-+$/,'');
+  return GAME_NAME.test(slug)?slug:`game-${randomBytes(4).toString('hex')}`;
+}
+// The build command for a project of its own: its build:dew or build npm script when it has one, named so init can
+// say which it chose, else the default with no script, so init can tell the developer to add one.
+function buildCommandFor(root) {
+  try {
+    const scripts=JSON.parse(readFileSync(join(root,'package.json'),'utf8')).scripts;
+    for(const name of ['build:dew','build'])if(scripts&&typeof scripts[name]==='string')return {build:['npm','run',name],script:name};
+  } catch {}
+  return {build:['npm','run','build:dew'],script:null};
+}
+export function initProject(root, game) {
+  const path=join(root,'dewdrop.json');
+  if(existsSync(path))throw new Error('This folder already has a dewdrop.json.');
+  const starter=!STARTER_FILES.some(file=>existsSync(join(root,file)));
+  game??=gameNameFrom(root);
+  if(!GAME_NAME.test(game))throw new Error('A game name is 1–48 lowercase letters, digits or dashes, starting with a letter.');
+  const {build,script}=starter?{build:['npm','run','build:dew'],script:'build:dew'}:buildCommandFor(root);
+  const config={version:1,game,bundle:'dist',build};
+  // Everything init writes, so a failure part-way removes it again and a retry starts from the same empty folder.
+  const made=[];
+  const write=(file,data)=>{writeFileSync(file,data,{flag:'wx'});made.push(file);};
+  const folder=dir=>{if(!existsSync(dir)){mkdirSync(dir,{recursive:true});made.push(dir);}};
+  try {
+    if(starter) {
+      folder(join(root,'src'));
+      const template=name=>readFileSync(new URL(`../examples/starter/${name}`,import.meta.url),'utf8');
+      write(join(root,'src/main.js'),template('main.js'));
+      write(join(root,'index.html'),template('index.html').replace('<title>My game</title>',`<title>${game}</title>`));
+      write(join(root,'vite.config.js'),template('vite.config.js'));
+      const devDependencies={'dewdrop-sdk':SDK_RANGE,dewctl:CLI_RANGE,vite:'^8'};
+      write(join(root,'package.json'),JSON.stringify({name:game,private:true,type:'module',scripts:{dev:'vite','build:dew':'vite build --mode dew'},dependencies:{three:'0.185.1'},devDependencies},null,2)+'\n');
+      if(!existsSync(join(root,'.gitignore')))write(join(root,'.gitignore'),'dist/\nnode_modules/\n.env*\n');
+    }
+    write(path,JSON.stringify(config,null,2)+'\n');
+  } catch(error) {
+    for(const file of made.reverse())rmSync(file,{recursive:true,force:true});
+    throw error;
+  }
+  return {...config,starter,buildScript:script};
+}

package/src/tar.js

@@ -0,0 +1,48 @@
+// The archive an upload is sent as: ustar, regular files only, written byte for byte the same for the same files.
+const BLOCK=512;
+const octal=(value,length)=>value.toString(8).padStart(length-1,'0')+'\0';
+const field=(block,offset,length,text)=>block.write(text,offset,length,'latin1');
+
+function header(path,size) {
+  const block=Buffer.alloc(BLOCK);
+  let name=path,prefix='';
+  if(Buffer.byteLength(path)>100) {
+    const cut=path.lastIndexOf('/',155);
+    if(cut<1||Buffer.byteLength(path.slice(cut+1))>100)throw new Error(`This file's path is too long to upload: ${path}`);
+    prefix=path.slice(0,cut);
+    name=path.slice(cut+1);
+  }
+  field(block,0,100,name);
+  field(block,100,8,octal(0o644,8));
+  field(block,108,8,octal(0,8));
+  field(block,116,8,octal(0,8));
+  field(block,124,12,octal(size,12));
+  field(block,136,12,octal(0,12));
+  field(block,148,8,'        ');
+  field(block,156,1,'0');
+  field(block,257,6,'ustar\0');
+  field(block,263,2,'00');
+  field(block,345,155,prefix);
+  let sum=0;
+  for(const byte of block)sum+=byte;
+  field(block,148,8,sum.toString(8).padStart(6,'0')+'\0 ');
+  return block;
+}
+
+// One archive of `entries` — `{path, size, read}` each, `read(target, offset)` copying the file's `size` bytes into
+// `target` at `offset` and answering how many it copied — in path order, with no owner, time or mode but the fixed
+// ones. The archive is one buffer the size of the whole, each file read straight into its place, so an upload is
+// held in memory once however large it is.
+const padded=size=>size+(size%BLOCK?BLOCK-size%BLOCK:0);
+export function packTar(entries) {
+  const sorted=[...entries].sort((a,b)=>a.path<b.path?-1:a.path>b.path?1:0);
+  const out=Buffer.alloc(sorted.reduce((sum,{size})=>sum+BLOCK+padded(size),0)+2*BLOCK);
+  let offset=0;
+  for(const {path,size,read} of sorted) {
+    header(path,size).copy(out,offset);
+    offset+=BLOCK;
+    if(read(out,offset)!==size)throw new Error(`${path} changed while it was being uploaded. Try again.`);
+    offset+=padded(size);
+  }
+  return out;
+}

package/src/thumbnail.js

@@ -0,0 +1,41 @@
+// The game's thumbnail as dewdrop.json names it: read, checked for what Dewdrop takes, and named by its content, the
+// way the game's thumbnail link ends, so a publish uploads it only when it differs from the one the game shows.
+import {createHash} from 'node:crypto';
+import {existsSync, readFileSync, realpathSync, openSync, fstatSync, closeSync, constants} from 'node:fs';
+import {projectPath} from './project.js';
+
+const MAX_BYTES = 1024 * 1024;
+export const TYPES = {png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp'};
+// What the image's bytes say it is: Dewdrop takes PNG, JPEG and WebP, by their bytes, and nothing else.
+function typeOf(bytes) {
+  if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'png';
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'jpeg';
+  if (bytes.length >= 12 && bytes.toString('latin1', 0, 4) === 'RIFF' && bytes.toString('latin1', 8, 12) === 'WEBP') return 'webp';
+  return null;
+}
+// The image is the project's own file: a symlink, which could reach anything on this computer, is refused as the
+// bundle's files are, and its size decides before its bytes are read, so a path to a huge file is refused, not loaded.
+export function readThumbnail(project) {
+  const path = projectPath(project.root, project.thumbnail);
+  if (!existsSync(path)) throw new Error(`The thumbnail dewdrop.json names, ${project.thumbnail}, isn't there.`);
+  if (realpathSync(path) !== path) throw new Error(`${project.thumbnail} is a symlink; name the image itself, inside the project.`);
+  let bytes;
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile()) throw new Error(`The thumbnail dewdrop.json names, ${project.thumbnail}, isn't a file.`);
+    if (stat.size > MAX_BYTES) throw new Error(`${project.thumbnail} is over 1 MB, the most a thumbnail can be.`);
+    bytes = readFileSync(fd);
+  } finally { closeSync(fd); }
+  if (bytes.length > MAX_BYTES) throw new Error(`${project.thumbnail} is over 1 MB, the most a thumbnail can be.`);
+  const type = typeOf(bytes);
+  if (!type) throw new Error(`${project.thumbnail} isn't a PNG, JPEG or WebP image.`);
+  return {bytes, type, file: `${createHash('sha256').update(bytes).digest('hex')}.${type}`};
+}
+// Uploads the project's thumbnail unless the game already shows it; answers whether it uploaded.
+export async function syncThumbnail(project, client, game, signal) {
+  const thumbnail = readThumbnail(project);
+  if (game.urls.thumbnail?.split('/').at(-1) === thumbnail.file) return false;
+  await client.thumbnail(project.game, thumbnail.bytes, TYPES[thumbnail.type], signal);
+  return true;
+}

package/src/watch.js

@@ -0,0 +1,58 @@
+// Poll the project's files across edits, deletions and atomic saves; only one build and activation runs at a time.
+import {PART_BYTES} from './client.js';
+import {fingerprint,build,snapshot} from './project.js';
+import {devPlayUrl} from './play.js';
+import {RUN} from './command.js';
+
+// A byte count as a person reads it.
+export function size(bytes) {
+  if(bytes<1024)return `${bytes} B`;
+  const [value,unit]=bytes<1024**2?[bytes/1024,'KB']:bytes<1024**3?[bytes/1024**2,'MB']:[bytes/1024**3,'GB'];
+  return `${value<10?value.toFixed(1):Math.round(value)} ${unit}`;
+}
+// Claims the game before building, so a name someone else has or an ended sign-in is known at once; then builds,
+// uploads and plays the build as the dev version.
+export async function deploy(project,client,{signal,log=console.log}={}) {
+  await client.claim(project.game,signal);
+  const before=fingerprint(project);
+  log('Building…');
+  await build(project,signal);
+  if(fingerprint(project)!==before)return {changed:true};
+  const bundle=snapshot(project);
+  const parts=Math.max(1,Math.ceil(bundle.body.length/PART_BYTES));
+  log(`Uploading ${bundle.files} file${bundle.files===1?'':'s'} (${size(bundle.bytes)})${parts>1?` in ${parts} parts`:''}…`);
+  await client.upload(project.game,bundle,signal);
+  const game=await client.activate(project.game,bundle.id,signal);
+  log(`Playing ${bundle.id.slice(0,12)} at ${devPlayUrl(game)}`);
+  return {changed:false};
+}
+
+// Rebuilds on every save. `reread` gives the project as dewdrop.json says it now, so an edit to it applies to the next
+// build; a dewdrop.json that no longer reads waits, like a failed build, for the next save.
+export async function watch(project,client,{signal,log=console.log,deployGame=deploy,readFingerprint=fingerprint,reread=()=>project,pollMs=200,debounceMs=500}={}) {
+  let observed=readFingerprint(project),changedAt=Date.now()-debounceMs,dirty=true;
+  let running=null;
+  log(`Watching ${project.game} for changes. Ctrl-C stops.`);
+  while(!signal?.aborted) {
+    try {
+      const next=readFingerprint(project);
+      if(next!==observed){observed=next;changedAt=Date.now();dirty=true;}
+      if(dirty&&!running&&Date.now()-changedAt>=debounceMs) {
+        dirty=false;
+        project=reread();
+        running=deployGame(project,client,{signal,log}).then(result=>{
+          if(result.changed)dirty=true;
+        }).catch(error=>{
+          if(signal?.aborted)return;
+          log(`dewctl: ${error.message}`);
+          if(error.status===401)log(`Paused until you sign in: run ${RUN} login in another terminal, then save a file.`);
+          else if(error.transient){log('Trying again in a moment.');dirty=true;changedAt=Date.now()+2000;}
+          else log('Fix it and save to try again.');
+        }).finally(()=>{running=null;});
+      }
+    }catch(error){log(`dewctl: ${error.message}`);log('Fix it and save to try again.');}
+    await new Promise(resolve=>setTimeout(resolve,pollMs));
+  }
+  await running;
+  log('Stopped watching. The dev version keeps running.');
+}