castle-web-cli 0.3.0 → 0.4.1

package/AGENTS.md

@@ -3,11 +3,11 @@
 ## Commands
 
 - `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 serve [dir] [--port PORT] [--open]` — local dev server with Vite (default port 3737, WS on 3738). Writes `.castle/serve.json` with active ports. No auto-reload — use `restart` to reload.
+- `npx castle-web-cli restart [dir] [--port PORT]` — reload the game in the browser. Reads WS port from `.castle/serve.json` if no `--port` given.
+- `npx castle-web-cli screenshot [dir] [--out FILE] [--port PORT]` — capture a screenshot from the running game (default: screenshot.png). Reads WS port from `.castle/serve.json` if no `--port` given.
+- `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 (reads WS port from `.castle/serve.json`).
+- `npx castle-web-cli save-preview-image [dir] [--port PORT] [--no-restart]` — restarts the deck, takes a screenshot, uploads it as the deck's preview image. Requires `serve` running and `castle.json` to exist (push first). Reads WS port from `.castle/serve.json` if no `--port` given.
 - `npx castle-web-cli login` — authenticate with Castle (saves token to ~/.castle/config.json)
 
 ## Project Structure
@@ -18,7 +18,8 @@ my-game/
   game.js         # game code
   package.json    # dependencies (castle-web-sdk)
   castle.json     # deck/card IDs (created by first push)
-  .castle/        # runtime state (logs, screenshots)
+  .castle/        # runtime state (logs, screenshots, serve port)
+    serve.json    # active serve ports (written by serve, cleaned up on exit)
     logs.txt      # forwarded console.log/warn/error
     screenshots/  # captured screenshots
 ```

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import * as fs from 'fs';
+import * as path from 'path';
 import { login } from './login.js';
 import { serve } from './serve.js';
 import { push } from './push.js';
@@ -7,13 +8,47 @@ import { init } from './init.js';
 import { savePreviewImage, savePreviewIfNeeded } from './preview.js';
 const args = process.argv.slice(2);
 const command = args[0];
+const FLAGS_WITH_VALUES = new Set(['--port', '--out']);
+function findPositionalDir() {
+    for (let i = 1; i < args.length; i++) {
+        if (args[i].startsWith('--')) {
+            if (FLAGS_WITH_VALUES.has(args[i]))
+                i++;
+            continue;
+        }
+        return args[i];
+    }
+    return '.';
+}
+function getFlagValue(flag) {
+    const idx = args.indexOf(flag);
+    return idx >= 0 ? args[idx + 1] : undefined;
+}
+function readServeWsPort(dir) {
+    try {
+        const serveJson = JSON.parse(fs.readFileSync(path.join(path.resolve(dir), '.castle', 'serve.json'), 'utf-8'));
+        return serveJson.wsPort;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getWsPort(dir) {
+    const explicit = getFlagValue('--port');
+    if (explicit)
+        return parseInt(explicit, 10);
+    const fromServe = readServeWsPort(dir);
+    if (fromServe)
+        return fromServe;
+    return 3738;
+}
 function usage() {
     console.log(`Usage:
   castle-web init <dir>
   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 save-preview-image [dir] [--port PORT] [--no-restart]
   castle-web push [dir]
   castle-web login`);
     process.exit(1);
@@ -30,24 +65,22 @@ async function main() {
             break;
         }
         case 'serve': {
-            const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
-            const portIdx = args.indexOf('--port');
-            const port = portIdx >= 0 ? args[portIdx + 1] : undefined;
+            const dir = findPositionalDir();
+            const port = getFlagValue('--port');
             const open = args.includes('--open');
             await serve(dir, { port, open });
             break;
         }
         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);
+            const dir = findPositionalDir();
             await push(dir);
+            const wsPort = getWsPort(dir);
             await savePreviewIfNeeded(dir, wsPort);
             break;
         }
         case 'restart': {
-            const portIdx = args.indexOf('--port');
-            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+            const dir = findPositionalDir();
+            const wsPort = getWsPort(dir);
             const { default: WS } = await import('ws');
             const ws = new WS(`ws://localhost:${wsPort}`);
             ws.on('open', () => {
@@ -58,10 +91,9 @@ async function main() {
             break;
         }
         case 'screenshot': {
-            const outIdx = args.indexOf('--out');
-            const outFile = outIdx >= 0 ? args[outIdx + 1] : 'screenshot.png';
-            const portIdx = args.indexOf('--port');
-            const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+            const dir = findPositionalDir();
+            const outFile = getFlagValue('--out') ?? 'screenshot.png';
+            const wsPort = getWsPort(dir);
             const requestId = Math.random().toString(36).slice(2);
             const { default: WS } = await import('ws');
             const ws = new WS(`ws://localhost:${wsPort}`);
@@ -90,10 +122,10 @@ 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);
+            const dir = findPositionalDir();
+            const wsPort = getWsPort(dir);
+            const noRestart = args.includes('--no-restart');
+            await savePreviewImage(dir, wsPort, noRestart);
             process.exit(0);
         }
         case 'login':

package/dist/preview.d.ts

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

package/dist/preview.js

@@ -15,7 +15,7 @@ function takeScreenshot(ws) {
         const requestId = Math.random().toString(36).slice(2);
         const timeout = setTimeout(() => {
             reject(new Error('Screenshot timed out.'));
-        }, 5000);
+        }, 10000);
         ws.on('message', (raw) => {
             try {
                 const msg = JSON.parse(raw.toString());
@@ -31,12 +31,11 @@ function takeScreenshot(ws) {
 }
 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);
+        setTimeout(resolve, 2000);
     });
 }
-export async function savePreviewImage(dir, wsPort) {
+export async function savePreviewImage(dir, wsPort, noRestart = false) {
     const projectDir = path.resolve(dir);
     const castleJsonPath = path.join(projectDir, 'castle.json');
     if (!fs.existsSync(castleJsonPath)) {
@@ -49,7 +48,8 @@ export async function savePreviewImage(dir, wsPort) {
         process.exit(1);
     }
     const ws = await connectWS(wsPort);
-    await waitForRestart(ws);
+    if (!noRestart)
+        await waitForRestart(ws);
     const base64 = await takeScreenshot(ws);
     ws.close();
     fs.writeFileSync(path.join(projectDir, 'preview.png'), Buffer.from(base64, 'base64'));
@@ -63,8 +63,9 @@ export async function savePreviewIfNeeded(dir, wsPort) {
     if (fs.existsSync(path.join(projectDir, 'preview.png'))) {
         return;
     }
+    let ws;
     try {
-        const ws = await connectWS(wsPort);
+        ws = await connectWS(wsPort);
         await waitForRestart(ws);
         const base64 = await takeScreenshot(ws);
         ws.close();
@@ -78,7 +79,9 @@ export async function savePreviewIfNeeded(dir, wsPort) {
         await api.updateCardCustomBackgroundImage(castleJson.cardId, file.fileId);
         console.log('Set deck preview image.');
     }
-    catch {
-        // serve not running, skip preview
+    catch (e) {
+        if (ws)
+            ws.close();
+        console.log(`Preview skipped: ${e?.message ?? e}`);
     }
 }

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,14 +43,24 @@ 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))
         fs.mkdirSync(castleDir, { recursive: true });
     const logFile = path.join(castleDir, 'logs.txt');
     const screenshotsDir = path.join(castleDir, 'screenshots');
+    const serveJsonPath = path.join(castleDir, 'serve.json');
+    fs.writeFileSync(serveJsonPath, JSON.stringify({ port, wsPort }) + '\n');
+    process.on('exit', () => { try {
+        fs.unlinkSync(serveJsonPath);
+    }
+    catch { } });
+    process.on('SIGINT', () => process.exit());
+    process.on('SIGTERM', () => process.exit());
     startWSServer(wsPort, logFile, screenshotsDir);
     const vite = await createServer({
         root: projectDir,

package/package.json

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

package/src/index.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import * as fs from 'fs';
+import * as path from 'path';
 import { login } from './login.js';
 import { serve } from './serve.js';
 import { push } from './push.js';
@@ -10,13 +11,48 @@ import { savePreviewImage, savePreviewIfNeeded } from './preview.js';
 const args = process.argv.slice(2);
 const command = args[0];
 
+const FLAGS_WITH_VALUES = new Set(['--port', '--out']);
+
+function findPositionalDir(): string {
+  for (let i = 1; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      if (FLAGS_WITH_VALUES.has(args[i])) i++;
+      continue;
+    }
+    return args[i];
+  }
+  return '.';
+}
+
+function getFlagValue(flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  return idx >= 0 ? args[idx + 1] : undefined;
+}
+
+function readServeWsPort(dir: string): number | undefined {
+  try {
+    const serveJson = JSON.parse(fs.readFileSync(path.join(path.resolve(dir), '.castle', 'serve.json'), 'utf-8'));
+    return serveJson.wsPort;
+  } catch {
+    return undefined;
+  }
+}
+
+function getWsPort(dir: string): number {
+  const explicit = getFlagValue('--port');
+  if (explicit) return parseInt(explicit, 10);
+  const fromServe = readServeWsPort(dir);
+  if (fromServe) return fromServe;
+  return 3738;
+}
+
 function usage() {
   console.log(`Usage:
   castle-web init <dir>
   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 save-preview-image [dir] [--port PORT] [--no-restart]
   castle-web push [dir]
   castle-web login`);
   process.exit(1);
@@ -31,24 +67,22 @@ async function main() {
       break;
     }
     case 'serve': {
-      const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
-      const portIdx = args.indexOf('--port');
-      const port = portIdx >= 0 ? args[portIdx + 1] : undefined;
+      const dir = findPositionalDir();
+      const port = getFlagValue('--port');
       const open = args.includes('--open');
       await serve(dir, { port, open });
       break;
     }
     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);
+      const dir = findPositionalDir();
       await push(dir);
+      const wsPort = getWsPort(dir);
       await savePreviewIfNeeded(dir, wsPort);
       break;
     }
     case 'restart': {
-      const portIdx = args.indexOf('--port');
-      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+      const dir = findPositionalDir();
+      const wsPort = getWsPort(dir);
       const { default: WS } = await import('ws');
       const ws = new WS(`ws://localhost:${wsPort}`);
       ws.on('open', () => {
@@ -59,10 +93,9 @@ async function main() {
       break;
     }
     case 'screenshot': {
-      const outIdx = args.indexOf('--out');
-      const outFile = outIdx >= 0 ? args[outIdx + 1] : 'screenshot.png';
-      const portIdx = args.indexOf('--port');
-      const wsPort = parseInt(portIdx >= 0 ? args[portIdx + 1] : '3738', 10);
+      const dir = findPositionalDir();
+      const outFile = getFlagValue('--out') ?? 'screenshot.png';
+      const wsPort = getWsPort(dir);
       const requestId = Math.random().toString(36).slice(2);
       const { default: WS } = await import('ws');
       const ws = new WS(`ws://localhost:${wsPort}`);
@@ -90,10 +123,10 @@ 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);
+      const dir = findPositionalDir();
+      const wsPort = getWsPort(dir);
+      const noRestart = args.includes('--no-restart');
+      await savePreviewImage(dir, wsPort, noRestart);
       process.exit(0);
     }
     case 'login':

package/src/preview.ts

@@ -17,7 +17,7 @@ function takeScreenshot(ws: any): Promise<string> {
     const requestId = Math.random().toString(36).slice(2);
     const timeout = setTimeout(() => {
       reject(new Error('Screenshot timed out.'));
-    }, 5000);
+    }, 10000);
     ws.on('message', (raw: Buffer) => {
       try {
         const msg = JSON.parse(raw.toString());
@@ -33,13 +33,12 @@ function takeScreenshot(ws: any): Promise<string> {
 
 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);
+    setTimeout(resolve, 2000);
   });
 }
 
-export async function savePreviewImage(dir: string, wsPort: number): Promise<void> {
+export async function savePreviewImage(dir: string, wsPort: number, noRestart = false): Promise<void> {
   const projectDir = path.resolve(dir);
   const castleJsonPath = path.join(projectDir, 'castle.json');
   if (!fs.existsSync(castleJsonPath)) {
@@ -54,7 +53,7 @@ export async function savePreviewImage(dir: string, wsPort: number): Promise<voi
   }
 
   const ws = await connectWS(wsPort);
-  await waitForRestart(ws);
+  if (!noRestart) await waitForRestart(ws);
   const base64 = await takeScreenshot(ws);
   ws.close();
 
@@ -71,8 +70,9 @@ export async function savePreviewIfNeeded(dir: string, wsPort: number): Promise<
   if (fs.existsSync(path.join(projectDir, 'preview.png'))) {
     return;
   }
+  let ws: any;
   try {
-    const ws = await connectWS(wsPort);
+    ws = await connectWS(wsPort);
     await waitForRestart(ws);
     const base64 = await takeScreenshot(ws);
     ws.close();
@@ -87,7 +87,8 @@ export async function savePreviewIfNeeded(dir: string, wsPort: number): Promise<
     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
+  } catch (e: any) {
+    if (ws) ws.close();
+    console.log(`Preview skipped: ${e?.message ?? e}`);
   }
 }

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');
@@ -42,6 +62,12 @@ export async function serve(
   const logFile = path.join(castleDir, 'logs.txt');
   const screenshotsDir = path.join(castleDir, 'screenshots');
 
+  const serveJsonPath = path.join(castleDir, 'serve.json');
+  fs.writeFileSync(serveJsonPath, JSON.stringify({ port, wsPort }) + '\n');
+  process.on('exit', () => { try { fs.unlinkSync(serveJsonPath); } catch {} });
+  process.on('SIGINT', () => process.exit());
+  process.on('SIGTERM', () => process.exit());
+
   startWSServer(wsPort, logFile, screenshotsDir);
 
   const vite = await createServer({