castle-web-cli 0.2.0 → 0.4.0

package/AGENTS.md

@@ -2,12 +2,13 @@
 
 ## Commands
 
-- `castle-web init <dir>` — scaffold a new project (index.html, game.js, package.json with castle-web-sdk)
-- `castle-web serve [dir] [--port PORT] [--open]` — local dev server with Vite (default port 3737, WS on 3738). No auto-reload — use `restart` to reload.
-- `castle-web restart [--port PORT]` — reload the game in the browser (default WS port 3738)
-- `castle-web screenshot [--out FILE] [--port PORT]` — capture a screenshot from the running game (default: screenshot.png)
-- `castle-web push [dir]` — bundle with Vite and publish to Castle. Creates a new deck if no castle.json exists.
-- `castle-web login` — authenticate with Castle (saves token to ~/.castle/config.json)
+- `npx castle-web-cli init <dir>` — scaffold a new project (index.html, game.js, package.json with castle-web-sdk)
+- `npx castle-web-cli serve [dir] [--port PORT] [--open]` — local dev server with Vite (default port 3737, WS on 3738). No auto-reload — use `restart` to reload.
+- `npx castle-web-cli restart [--port PORT]` — reload the game in the browser (default WS port 3738)
+- `npx castle-web-cli screenshot [--out FILE] [--port PORT]` — capture a screenshot from the running game (default: screenshot.png)
+- `npx castle-web-cli push [dir]` — bundle with Vite and publish to Castle. Creates a new deck if no castle.json exists. Automatically saves a preview image on first push if `serve` is running.
+- `npx castle-web-cli save-preview-image [dir] [--port PORT]` — restarts the deck, takes a screenshot, uploads it as the deck's preview image. Requires `serve` running and `castle.json` to exist (push first).
+- `npx castle-web-cli login` — authenticate with Castle (saves token to ~/.castle/config.json)
 
 ## Project Structure
 
@@ -21,23 +22,3 @@ my-game/
     logs.txt      # forwarded console.log/warn/error
     screenshots/  # captured screenshots
 ```
-
-## SDK
-
-Games import and call `setup()` + `initCard()`:
-
-```js
-import { setup, initCard } from 'castle-web-sdk';
-setup();
-const card = initCard();
-```
-
-`setup()` enables log forwarding, screenshot capture, and live reload via local WebSocket. `initCard()` creates a 5:7 card container.
-
-## Agent Workflow
-
-1. `castle-web serve` in a background tmux window
-2. Edit code
-3. `castle-web restart` to reload
-4. `castle-web screenshot --out shot.png` to see the result
-5. Read `.castle/logs.txt` for console output

package/dist/api.d.ts

@@ -18,3 +18,8 @@ export declare function uploadSceneData(cards: Array<{
     cardId: string;
     uploadId: string;
 }>): Promise<any[]>;
+export declare function uploadBase64(base64: string, filename: string): Promise<{
+    fileId: string;
+    url: string;
+}>;
+export declare function updateCardCustomBackgroundImage(cardId: string, backgroundImageFileId: string): Promise<void>;

package/dist/api.js

@@ -103,3 +103,18 @@ export async function uploadSceneData(cards) {
     handleAPIError(data);
     return data.data.uploadSceneData;
 }
+export async function uploadBase64(base64, filename) {
+    const data = await graphql(`mutation($data: String!, $filename: String, $mimetype: String) {
+       uploadBase64(data: $data, filename: $filename, mimetype: $mimetype) {
+         fileId url
+       }
+     }`, { data: base64, filename, mimetype: 'image/png' });
+    handleAPIError(data);
+    return data.data.uploadBase64;
+}
+export async function updateCardCustomBackgroundImage(cardId, backgroundImageFileId) {
+    const data = await graphql(`mutation($cardId: ID!, $backgroundImageFileId: ID) {
+       updateCardCustomBackgroundImage(cardId: $cardId, backgroundImageFileId: $backgroundImageFileId)
+     }`, { cardId, backgroundImageFileId });
+    handleAPIError(data);
+}

package/dist/index.js

@@ -4,6 +4,7 @@ import { login } from './login.js';
 import { serve } from './serve.js';
 import { push } from './push.js';
 import { init } from './init.js';
+import { savePreviewImage, savePreviewIfNeeded } from './preview.js';
 const args = process.argv.slice(2);
 const command = args[0];
 function usage() {
@@ -12,10 +13,9 @@ function usage() {
   castle-web serve [dir] [--port PORT] [--open]
   castle-web restart [--port PORT]
   castle-web screenshot [--out FILE] [--port PORT]
+  castle-web save-preview-image [dir] [--port PORT]
   castle-web push [dir]
-  castle-web login
-
-Install: cd castle-experimental-web/cli && npm install && npm run build && npm link`);
+  castle-web login`);
     process.exit(1);
 }
 async function main() {
@@ -39,7 +39,10 @@ async function main() {
         }
         case 'push': {
             const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+            const portIdx = args.indexOf('--port');
+            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
             await push(dir);
+            await savePreviewIfNeeded(dir, wsPort);
             break;
         }
         case 'restart': {
@@ -86,6 +89,13 @@ async function main() {
             });
             break;
         }
+        case 'save-preview-image': {
+            const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+            const portIdx = args.indexOf('--port');
+            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+            await savePreviewImage(dir, wsPort);
+            process.exit(0);
+        }
         case 'login':
             await login();
             break;

package/dist/init.js

@@ -25,6 +25,9 @@ el.style.cssText = \`
 el.textContent = 'Hello Castle!';
 card.appendChild(el);
 `;
+const CLAUDE_MD = `@node_modules/castle-web-cli/AGENTS.md
+@node_modules/castle-web-sdk/AGENTS.md
+`;
 export async function init(dir) {
     const projectDir = path.resolve(dir);
     if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
@@ -34,7 +37,7 @@ export async function init(dir) {
     fs.mkdirSync(projectDir, { recursive: true });
     fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
     fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
-    // Create package.json with SDK dependency
+    fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), CLAUDE_MD);
     const packageJson = {
         name: path.basename(projectDir),
         private: true,
@@ -42,16 +45,18 @@ export async function init(dir) {
         dependencies: {
             'castle-web-sdk': '*',
         },
+        devDependencies: {
+            'castle-web-cli': '*',
+        },
     };
     fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\n');
-    // Install dependencies (picks up npm-linked SDK)
     const { execSync } = await import('child_process');
     execSync('npm install', { cwd: projectDir, stdio: 'inherit' });
     console.log(`Created project in ${projectDir}/`);
     console.log('');
     console.log('Next steps:');
     console.log(`  cd ${dir}`);
-    console.log('  castle-web serve --open');
-    console.log('  castle-web login');
-    console.log('  castle-web push');
+    console.log('  npx castle-web-cli serve --open');
+    console.log('  npx castle-web-cli login');
+    console.log('  npx castle-web-cli push');
 }

package/dist/preview.d.ts

@@ -0,0 +1,2 @@
+export declare function savePreviewImage(dir: string, wsPort: number): Promise<void>;
+export declare function savePreviewIfNeeded(dir: string, wsPort: number): Promise<void>;

package/dist/preview.js

@@ -0,0 +1,84 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as api from './api.js';
+import * as config from './config.js';
+function connectWS(wsPort) {
+    return new Promise(async (resolve, reject) => {
+        const { default: WS } = await import('ws');
+        const ws = new WS(`ws://localhost:${wsPort}`);
+        ws.on('error', () => reject(new Error('Could not connect. Is castle-web serve running?')));
+        ws.on('open', () => resolve(ws));
+    });
+}
+function takeScreenshot(ws) {
+    return new Promise((resolve, reject) => {
+        const requestId = Math.random().toString(36).slice(2);
+        const timeout = setTimeout(() => {
+            reject(new Error('Screenshot timed out.'));
+        }, 5000);
+        ws.on('message', (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                if (msg.type === 'screenshot_response' && msg.requestId === requestId) {
+                    clearTimeout(timeout);
+                    resolve(msg.data.replace(/^data:image\/png;base64,/, ''));
+                }
+            }
+            catch { }
+        });
+        ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
+    });
+}
+function waitForRestart(ws) {
+    return new Promise((resolve) => {
+        // restart, wait a moment for the deck to render its first frame
+        ws.send(JSON.stringify({ type: 'restart' }));
+        setTimeout(resolve, 500);
+    });
+}
+export async function savePreviewImage(dir, wsPort) {
+    const projectDir = path.resolve(dir);
+    const castleJsonPath = path.join(projectDir, 'castle.json');
+    if (!fs.existsSync(castleJsonPath)) {
+        console.error('No castle.json found. Push the deck first.');
+        process.exit(1);
+    }
+    const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+    if (!config.getToken()) {
+        console.error('Not logged in. Run `castle-web login` first.');
+        process.exit(1);
+    }
+    const ws = await connectWS(wsPort);
+    await waitForRestart(ws);
+    const base64 = await takeScreenshot(ws);
+    ws.close();
+    fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+    console.log('Saved preview.png');
+    const file = await api.uploadBase64(base64, 'preview.png');
+    await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+    console.log('Set deck preview image.');
+}
+export async function savePreviewIfNeeded(dir, wsPort) {
+    const projectDir = path.resolve(dir);
+    if (fs.existsSync(path.join(projectDir, 'preview.png'))) {
+        return;
+    }
+    try {
+        const ws = await connectWS(wsPort);
+        await waitForRestart(ws);
+        const base64 = await takeScreenshot(ws);
+        ws.close();
+        const castleJsonPath = path.join(projectDir, 'castle.json');
+        if (!fs.existsSync(castleJsonPath))
+            return;
+        const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+        fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+        console.log('Saved preview.png');
+        const file = await api.uploadBase64(base64, 'preview.png');
+        await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+        console.log('Set deck preview image.');
+    }
+    catch {
+        // serve not running, skip preview
+    }
+}

package/dist/serve.js

@@ -1,7 +1,23 @@
 import * as fs from 'fs';
+import * as net from 'net';
 import * as path from 'path';
 import { createServer } from 'vite';
 import { WebSocketServer, WebSocket } from 'ws';
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once('error', () => resolve(false));
+        srv.listen(port, () => { srv.close(() => resolve(true)); });
+    });
+}
+async function findFreePorts(startPort) {
+    for (let p = startPort; p < startPort + 100; p += 2) {
+        if (await isPortFree(p) && await isPortFree(p + 1)) {
+            return { port: p, wsPort: p + 1 };
+        }
+    }
+    throw new Error(`No free port pair found starting from ${startPort}`);
+}
 function castlePlugin(wsPort) {
     return {
         name: 'castle-dev',
@@ -27,8 +43,10 @@ export async function serve(dir, options = {}) {
         console.error(`No index.html found in ${projectDir}`);
         process.exit(1);
     }
-    const port = parseInt(options.port ?? '3737', 10);
-    const wsPort = port + 1;
+    const startPort = parseInt(options.port ?? '3737', 10);
+    const { port, wsPort } = options.port
+        ? { port: startPort, wsPort: startPort + 1 }
+        : await findFreePorts(startPort);
     // Local WebSocket server for SDK communication
     const castleDir = path.join(projectDir, '.castle');
     if (!fs.existsSync(castleDir))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"

package/src/api.ts

@@ -135,3 +135,26 @@ export async function uploadSceneData(
   handleAPIError(data);
   return data.data.uploadSceneData;
 }
+
+export async function uploadBase64(base64: string, filename: string): Promise<{ fileId: string; url: string }> {
+  const data = await graphql(
+    `mutation($data: String!, $filename: String, $mimetype: String) {
+       uploadBase64(data: $data, filename: $filename, mimetype: $mimetype) {
+         fileId url
+       }
+     }`,
+    { data: base64, filename, mimetype: 'image/png' }
+  );
+  handleAPIError(data);
+  return data.data.uploadBase64;
+}
+
+export async function updateCardCustomBackgroundImage(cardId: string, backgroundImageFileId: string): Promise<void> {
+  const data = await graphql(
+    `mutation($cardId: ID!, $backgroundImageFileId: ID) {
+       updateCardCustomBackgroundImage(cardId: $cardId, backgroundImageFileId: $backgroundImageFileId)
+     }`,
+    { cardId, backgroundImageFileId }
+  );
+  handleAPIError(data);
+}

package/src/index.ts

@@ -5,6 +5,7 @@ import { login } from './login.js';
 import { serve } from './serve.js';
 import { push } from './push.js';
 import { init } from './init.js';
+import { savePreviewImage, savePreviewIfNeeded } from './preview.js';
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -15,10 +16,9 @@ function usage() {
   castle-web serve [dir] [--port PORT] [--open]
   castle-web restart [--port PORT]
   castle-web screenshot [--out FILE] [--port PORT]
+  castle-web save-preview-image [dir] [--port PORT]
   castle-web push [dir]
-  castle-web login
-
-Install: cd castle-experimental-web/cli && npm install && npm run build && npm link`);
+  castle-web login`);
   process.exit(1);
 }
 
@@ -40,7 +40,10 @@ async function main() {
     }
     case 'push': {
       const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+      const portIdx = args.indexOf('--port');
+      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
       await push(dir);
+      await savePreviewIfNeeded(dir, wsPort);
       break;
     }
     case 'restart': {
@@ -86,6 +89,13 @@ async function main() {
       });
       break;
     }
+    case 'save-preview-image': {
+      const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+      const portIdx = args.indexOf('--port');
+      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+      await savePreviewImage(dir, wsPort);
+      process.exit(0);
+    }
     case 'login':
       await login();
       break;

package/src/init.ts

@@ -28,6 +28,10 @@ el.textContent = 'Hello Castle!';
 card.appendChild(el);
 `;
 
+const CLAUDE_MD = `@node_modules/castle-web-cli/AGENTS.md
+@node_modules/castle-web-sdk/AGENTS.md
+`;
+
 export async function init(dir: string) {
   const projectDir = path.resolve(dir);
 
@@ -39,8 +43,8 @@ export async function init(dir: string) {
   fs.mkdirSync(projectDir, { recursive: true });
   fs.writeFileSync(path.join(projectDir, 'index.html'), INDEX_HTML);
   fs.writeFileSync(path.join(projectDir, 'game.js'), GAME_JS);
+  fs.writeFileSync(path.join(projectDir, 'CLAUDE.md'), CLAUDE_MD);
 
-  // Create package.json with SDK dependency
   const packageJson = {
     name: path.basename(projectDir),
     private: true,
@@ -48,10 +52,12 @@ export async function init(dir: string) {
     dependencies: {
       'castle-web-sdk': '*',
     },
+    devDependencies: {
+      'castle-web-cli': '*',
+    },
   };
   fs.writeFileSync(path.join(projectDir, 'package.json'), JSON.stringify(packageJson, null, 2) + '\n');
 
-  // Install dependencies (picks up npm-linked SDK)
   const { execSync } = await import('child_process');
   execSync('npm install', { cwd: projectDir, stdio: 'inherit' });
 
@@ -59,7 +65,7 @@ export async function init(dir: string) {
   console.log('');
   console.log('Next steps:');
   console.log(`  cd ${dir}`);
-  console.log('  castle-web serve --open');
-  console.log('  castle-web login');
-  console.log('  castle-web push');
+  console.log('  npx castle-web-cli serve --open');
+  console.log('  npx castle-web-cli login');
+  console.log('  npx castle-web-cli push');
 }

package/src/preview.ts

@@ -0,0 +1,93 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as api from './api.js';
+import * as config from './config.js';
+
+function connectWS(wsPort: number): Promise<any> {
+  return new Promise(async (resolve, reject) => {
+    const { default: WS } = await import('ws');
+    const ws = new WS(`ws://localhost:${wsPort}`);
+    ws.on('error', () => reject(new Error('Could not connect. Is castle-web serve running?')));
+    ws.on('open', () => resolve(ws));
+  });
+}
+
+function takeScreenshot(ws: any): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const requestId = Math.random().toString(36).slice(2);
+    const timeout = setTimeout(() => {
+      reject(new Error('Screenshot timed out.'));
+    }, 5000);
+    ws.on('message', (raw: Buffer) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === 'screenshot_response' && msg.requestId === requestId) {
+          clearTimeout(timeout);
+          resolve(msg.data.replace(/^data:image\/png;base64,/, ''));
+        }
+      } catch {}
+    });
+    ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
+  });
+}
+
+function waitForRestart(ws: any): Promise<void> {
+  return new Promise((resolve) => {
+    // restart, wait a moment for the deck to render its first frame
+    ws.send(JSON.stringify({ type: 'restart' }));
+    setTimeout(resolve, 500);
+  });
+}
+
+export async function savePreviewImage(dir: string, wsPort: number): Promise<void> {
+  const projectDir = path.resolve(dir);
+  const castleJsonPath = path.join(projectDir, 'castle.json');
+  if (!fs.existsSync(castleJsonPath)) {
+    console.error('No castle.json found. Push the deck first.');
+    process.exit(1);
+  }
+  const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+
+  if (!config.getToken()) {
+    console.error('Not logged in. Run `castle-web login` first.');
+    process.exit(1);
+  }
+
+  const ws = await connectWS(wsPort);
+  await waitForRestart(ws);
+  const base64 = await takeScreenshot(ws);
+  ws.close();
+
+  fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+  console.log('Saved preview.png');
+
+  const file = await api.uploadBase64(base64, 'preview.png');
+  await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+  console.log('Set deck preview image.');
+}
+
+export async function savePreviewIfNeeded(dir: string, wsPort: number): Promise<void> {
+  const projectDir = path.resolve(dir);
+  if (fs.existsSync(path.join(projectDir, 'preview.png'))) {
+    return;
+  }
+  try {
+    const ws = await connectWS(wsPort);
+    await waitForRestart(ws);
+    const base64 = await takeScreenshot(ws);
+    ws.close();
+
+    const castleJsonPath = path.join(projectDir, 'castle.json');
+    if (!fs.existsSync(castleJsonPath)) return;
+    const castleJson = JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
+
+    fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
+    console.log('Saved preview.png');
+
+    const file = await api.uploadBase64(base64, 'preview.png');
+    await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
+    console.log('Set deck preview image.');
+  } catch {
+    // serve not running, skip preview
+  }
+}

package/src/serve.ts

@@ -1,8 +1,26 @@
 import * as fs from 'fs';
+import * as net from 'net';
 import * as path from 'path';
 import { createServer, type Plugin } from 'vite';
 import { WebSocketServer, WebSocket } from 'ws';
 
+function isPortFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once('error', () => resolve(false));
+    srv.listen(port, () => { srv.close(() => resolve(true)); });
+  });
+}
+
+async function findFreePorts(startPort: number): Promise<{ port: number; wsPort: number }> {
+  for (let p = startPort; p < startPort + 100; p += 2) {
+    if (await isPortFree(p) && await isPortFree(p + 1)) {
+      return { port: p, wsPort: p + 1 };
+    }
+  }
+  throw new Error(`No free port pair found starting from ${startPort}`);
+}
+
 function castlePlugin(wsPort: number): Plugin {
   return {
     name: 'castle-dev',
@@ -33,8 +51,10 @@ export async function serve(
     process.exit(1);
   }
 
-  const port = parseInt(options.port ?? '3737', 10);
-  const wsPort = port + 1;
+  const startPort = parseInt(options.port ?? '3737', 10);
+  const { port, wsPort } = options.port
+    ? { port: startPort, wsPort: startPort + 1 }
+    : await findFreePorts(startPort);
 
   // Local WebSocket server for SDK communication
   const castleDir = path.join(projectDir, '.castle');