castle-web-cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,22 @@
+# Castle Web CLI
+
+## Commands
+
+- `castle-web init <dir>` — scaffold a new project (index.html, game.js, castle.js SDK)
+- `castle-web serve [dir] [--port PORT] [--open]` — local dev server with hot reload (default port 3737)
+- `castle-web push [dir]` — bundle with esbuild 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)
+
+## Project Structure
+
+```
+my-game/
+  index.html      # entry point
+  game.js         # game code
+  castle.js       # SDK (copied by init)
+  castle.json     # deck/card IDs (created by first push)
+```
+
+## Bundling
+
+`push` uses esbuild to inline all `<script src="...">` tags into a single self-contained HTML string stored in the deck's scene data as `experimentalWeb.bundle`.

package/dist/api.d.ts

@@ -0,0 +1,20 @@
+export declare function startCLILogin(): Promise<{
+    pollToken: string;
+    url: string;
+}>;
+export declare function pollForCLILogin(pollToken: string): Promise<any>;
+export declare function me(): Promise<any>;
+export declare function myDecks(): Promise<any[]>;
+export declare function updateCardAndDeckV2(deck: Record<string, unknown>, card: Record<string, unknown>): Promise<{
+    deckId: string;
+    cardId: string;
+}>;
+export declare function createDeck(deck: Record<string, unknown>, card: Record<string, unknown>): Promise<{
+    deckId: string;
+    cardId: string;
+}>;
+export declare function createSceneDataUploadConfig(cardIds: string[]): Promise<any[]>;
+export declare function uploadSceneData(cards: Array<{
+    cardId: string;
+    uploadId: string;
+}>): Promise<any[]>;

package/dist/api.js

@@ -0,0 +1,105 @@
+import * as config from './config.js';
+const API_HOST = 'https://api.castle.xyz/graphql';
+async function graphql(query, variables) {
+    const token = config.getToken();
+    const headers = {
+        'X-OS': 'cli',
+        'X-CLI-API-Version': '2',
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+    };
+    if (token)
+        headers['X-Auth-Token'] = token;
+    const res = await fetch(API_HOST, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(variables ? { query, variables } : { query }),
+        signal: AbortSignal.timeout(10000),
+    });
+    return res.json();
+}
+function handleAPIError(data) {
+    if (data?.errors?.length) {
+        const err = new Error(data.errors[0]?.message ?? 'GraphQL error');
+        err.extensions = data.errors[0]?.extensions;
+        throw err;
+    }
+}
+export async function startCLILogin() {
+    const data = await graphql(`mutation { startCLILogin { pollToken url } }`);
+    handleAPIError(data);
+    return data.data.startCLILogin;
+}
+export async function pollForCLILogin(pollToken) {
+    const data = await graphql(`query($pollToken: String!) {
+       pollForCLILogin(pollToken: $pollToken) {
+         userId username token isAnonymous
+       }
+     }`, { pollToken });
+    handleAPIError(data);
+    return data.data?.pollForCLILogin ?? null;
+}
+export async function me() {
+    try {
+        const data = await graphql(`query { me { userId username isAnonymous } }`);
+        return data.data?.me ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function myDecks() {
+    const data = await graphql(`query {
+    me {
+      decks {
+        deckId
+        title
+        initialCard { cardId }
+      }
+    }
+  }`);
+    handleAPIError(data);
+    return data.data?.me?.decks ?? [];
+}
+export async function updateCardAndDeckV2(deck, card) {
+    const data = await graphql(`mutation($deck: DeckInput!, $card: CardInput!) {
+       updateCardAndDeckV2(deck: $deck, card: $card) {
+         deck { deckId }
+         card { cardId }
+       }
+     }`, { deck, card });
+    handleAPIError(data);
+    return {
+        deckId: data.data.updateCardAndDeckV2.deck.deckId,
+        cardId: data.data.updateCardAndDeckV2.card.cardId,
+    };
+}
+export async function createDeck(deck, card) {
+    const data = await graphql(`mutation($deck: DeckInput!, $card: CardInput!) {
+       createDeck(deck: $deck, card: $card) {
+         deckId
+         initialCard { cardId }
+       }
+     }`, { deck, card });
+    handleAPIError(data);
+    return {
+        deckId: data.data.createDeck.deckId,
+        cardId: data.data.createDeck.initialCard.cardId,
+    };
+}
+export async function createSceneDataUploadConfig(cardIds) {
+    const data = await graphql(`mutation($cardIds: [ID!]!) {
+       createSceneDataUploadConfig(cardIds: $cardIds) {
+         cardId uploadId postUrl postFields
+       }
+     }`, { cardIds });
+    handleAPIError(data);
+    return data.data.createSceneDataUploadConfig;
+}
+export async function uploadSceneData(cards) {
+    const data = await graphql(`mutation($cards: [CardSceneDataInput!]!) {
+       uploadSceneData(cards: $cards) { cardId sceneDataUrl }
+     }`, { cards });
+    handleAPIError(data);
+    return data.data.uploadSceneData;
+}

package/dist/bundle.d.ts

@@ -0,0 +1 @@
+export declare function bundleProject(dir: string): string;

package/dist/bundle.js

@@ -0,0 +1,27 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as esbuild from 'esbuild';
+export function bundleProject(dir) {
+    const indexPath = path.join(dir, 'index.html');
+    if (!fs.existsSync(indexPath)) {
+        throw new Error(`No index.html found in ${dir}`);
+    }
+    let html = fs.readFileSync(indexPath, 'utf-8');
+    // Find <script src="..."> tags, bundle each with esbuild, inline the result
+    html = html.replace(/<script\s+([^>]*?)src=["']([^"']+)["']([^>]*?)>\s*<\/script>/gi, (fullMatch, before, src, after) => {
+        const srcPath = path.resolve(dir, src);
+        if (!fs.existsSync(srcPath))
+            return fullMatch;
+        const result = esbuild.buildSync({
+            entryPoints: [srcPath],
+            bundle: true,
+            format: 'esm',
+            write: false,
+            minify: false,
+        });
+        const code = result.outputFiles[0].text;
+        const attrs = `${before}${after}`.trim();
+        return `<script type="module"${attrs ? ' ' + attrs : ''}>\n${code}</script>`;
+    });
+    return html;
+}

package/dist/config.d.ts

@@ -0,0 +1,2 @@
+export declare function getToken(): string | null;
+export declare function setToken(token: string | null): void;

package/dist/config.js

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+function getConfigDir() {
+    return path.join(os.homedir(), '.castle');
+}
+function readConfigFile(filename) {
+    const configDir = getConfigDir();
+    const configFilePath = path.join(configDir, filename);
+    try {
+        if (fs.existsSync(configFilePath)) {
+            return JSON.parse(fs.readFileSync(configFilePath, 'utf-8'));
+        }
+    }
+    catch { }
+    return null;
+}
+export function getToken() {
+    const config = readConfigFile('config.json');
+    return config ? config.token : null;
+}
+export function setToken(token) {
+    const configDir = getConfigDir();
+    fs.mkdirSync(configDir, { recursive: true });
+    const existing = readConfigFile('config.json') ?? {};
+    if (token === null) {
+        delete existing.token;
+    }
+    else {
+        existing.token = token;
+    }
+    const configFilePath = path.join(configDir, 'config.json');
+    fs.writeFileSync(configFilePath, JSON.stringify(existing, null, 2), 'utf-8');
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { login } from './login.js';
+import { serve } from './serve.js';
+import { push } from './push.js';
+import { init } from './init.js';
+const args = process.argv.slice(2);
+const command = args[0];
+function usage() {
+    console.log(`Usage:
+  castle-web init <dir>
+  castle-web serve [dir] [--port PORT] [--open]
+  castle-web push [dir]
+  castle-web login
+
+Install: cd castle-experimental-web/cli && npm install && npm run build && npm link`);
+    process.exit(1);
+}
+async function main() {
+    switch (command) {
+        case 'init': {
+            const dir = args[1];
+            if (!dir) {
+                console.error('Usage: castle-web init <dir>');
+                process.exit(1);
+            }
+            init(dir);
+            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 open = args.includes('--open');
+            await serve(dir, { port, open });
+            break;
+        }
+        case 'push': {
+            const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+            await push(dir);
+            break;
+        }
+        case 'login':
+            await login();
+            break;
+        default:
+            usage();
+    }
+}
+main().catch((e) => {
+    console.error(e.message ?? e);
+    process.exit(1);
+});

package/dist/init.d.ts

@@ -0,0 +1 @@
+export declare function init(dir: string): Promise<void>;

package/dist/init.js

@@ -0,0 +1,57 @@
+import * as fs from 'fs';
+import * as path from 'path';
+const INDEX_HTML = `<!DOCTYPE html>
+<html>
+<head>
+  <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+  <title>My Castle Game</title>
+</head>
+<body>
+  <script type="module" src="game.js"></script>
+</body>
+</html>
+`;
+const GAME_JS = `import * as castle from 'castle-web-sdk';
+
+castle.enableHotReload();
+const card = castle.initCard();
+
+const div = document.createElement('div');
+div.style.cssText = \`
+  width: 100%; height: 100%;
+  display: flex; align-items: center; justify-content: center;
+  font-family: system-ui; color: #fff; font-size: 24px;
+\`;
+div.textContent = 'Hello Castle!';
+card.appendChild(div);
+`;
+export async function init(dir) {
+    const projectDir = path.resolve(dir);
+    if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
+        console.error(`Directory "${dir}" is not empty.`);
+        process.exit(1);
+    }
+    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
+    const packageJson = {
+        name: path.basename(projectDir),
+        private: true,
+        type: 'module',
+        dependencies: {
+            'castle-web-sdk': '*',
+        },
+    };
+    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');
+}

package/dist/login.d.ts

@@ -0,0 +1 @@
+export declare function login(): Promise<void>;

package/dist/login.js

@@ -0,0 +1,21 @@
+import * as api from './api.js';
+import * as config from './config.js';
+export async function login() {
+    const { pollToken, url } = await api.startCLILogin();
+    console.log(`Opening browser to log in: ${url}`);
+    const { default: open } = await import('open');
+    await open(url);
+    console.log('Waiting for login...');
+    const MAX_POLLS = 600;
+    for (let i = 0; i < MAX_POLLS; i++) {
+        await new Promise((r) => setTimeout(r, 1000));
+        const user = await api.pollForCLILogin(pollToken);
+        if (user) {
+            config.setToken(user.token);
+            console.log(`Logged in as @${user.username}`);
+            return;
+        }
+    }
+    console.error('Login timed out.');
+    process.exit(1);
+}

package/dist/push.d.ts

@@ -0,0 +1 @@
+export declare function push(dir: string): Promise<void>;

package/dist/push.js

@@ -0,0 +1,95 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { nanoid } from 'nanoid';
+import * as api from './api.js';
+import * as config from './config.js';
+import { bundleProject } from './bundle.js';
+function readCastleJson(dir) {
+    const p = path.join(dir, 'castle.json');
+    if (!fs.existsSync(p))
+        return null;
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+}
+function buildSceneData(bundle) {
+    return {
+        experimentalWeb: {
+            enabled: true,
+            bundle,
+        },
+        snapshot: {
+            sceneProperties: {
+                backgroundColor: { r: 0, g: 0, b: 0, a: 1 },
+                coordinateSystemVersion: 2,
+            },
+            actors: [],
+            library: {},
+            linkTargetDeckIds: [],
+        },
+    };
+}
+export async function push(dir) {
+    if (!config.getToken()) {
+        console.error('Not logged in. Run `castle-web login` first.');
+        process.exit(1);
+    }
+    const projectDir = path.resolve(dir);
+    if (!fs.existsSync(path.join(projectDir, 'index.html'))) {
+        console.error(`No index.html found in ${projectDir}`);
+        process.exit(1);
+    }
+    let castleJson = readCastleJson(projectDir);
+    console.log('Bundling...');
+    const bundle = bundleProject(projectDir);
+    console.log(`Bundle size: ${(bundle.length / 1024).toFixed(1)}KB`);
+    const sceneData = buildSceneData(bundle);
+    const isNew = !castleJson;
+    const cardId = castleJson?.cardId ?? nanoid(12);
+    const deckId = castleJson?.deckId ?? nanoid(12);
+    // Upload scene data to S3
+    const configs = await api.createSceneDataUploadConfig([cardId]);
+    if (!configs?.length) {
+        console.error('Failed to get upload config.');
+        process.exit(1);
+    }
+    const uploadConfig = configs[0];
+    const formData = new FormData();
+    formData.append('Content-Type', 'application/json');
+    for (const [k, v] of Object.entries(uploadConfig.postFields)) {
+        formData.append(k, `${v}`);
+    }
+    formData.append('file', new Blob([JSON.stringify(sceneData)]));
+    const s3Res = await fetch(uploadConfig.postUrl, {
+        method: 'POST',
+        body: formData,
+        signal: AbortSignal.timeout(30000),
+    });
+    if (s3Res.status >= 300) {
+        throw new Error(`Upload failed: HTTP ${s3Res.status}`);
+    }
+    // Create or update via updateCardAndDeckV2
+    const title = path.basename(path.resolve(projectDir));
+    try {
+        const result = await api.updateCardAndDeckV2({ deckId, title }, { cardId, blocks: [], uploadId: uploadConfig.uploadId, makeInitialCard: true });
+        if (isNew) {
+            const newCastleJson = { deckId: result.deckId, cardId: result.cardId };
+            fs.writeFileSync(path.join(projectDir, 'castle.json'), JSON.stringify(newCastleJson, null, 2) + '\n', 'utf-8');
+            console.log(`Created deck "${title}" (${result.deckId}). Saved castle.json.`);
+        }
+        else {
+            console.log('Pushed to Castle.');
+        }
+    }
+    catch (e) {
+        const code = e?.extensions?.code ?? '';
+        if (code === 'LOGIN_REQUIRED') {
+            console.error('Not logged in. Run `castle-web login` first.');
+        }
+        else if (code === 'DECK_INVALID_PERMISSIONS') {
+            console.error('You do not have permission to push to this deck.');
+        }
+        else {
+            throw e;
+        }
+        process.exit(1);
+    }
+}

package/dist/serve.d.ts

@@ -0,0 +1,4 @@
+export declare function serve(dir: string, options?: {
+    port?: string;
+    open?: boolean;
+}): Promise<void>;

package/dist/serve.js

@@ -0,0 +1,120 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as http from 'http';
+const MIME_TYPES = {
+    '.html': 'text/html',
+    '.js': 'application/javascript',
+    '.mjs': 'application/javascript',
+    '.css': 'text/css',
+    '.json': 'application/json',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.wasm': 'application/wasm',
+    '.ico': 'image/x-icon',
+    '.mp3': 'audio/mpeg',
+    '.ogg': 'audio/ogg',
+    '.wav': 'audio/wav',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.ttf': 'font/ttf',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+export async function serve(dir, options = {}) {
+    const projectDir = path.resolve(dir);
+    if (!fs.existsSync(projectDir)) {
+        console.error(`Directory not found: ${projectDir}`);
+        process.exit(1);
+    }
+    const indexPath = path.join(projectDir, 'index.html');
+    if (!fs.existsSync(indexPath)) {
+        console.error(`No index.html found in ${projectDir}`);
+        process.exit(1);
+    }
+    const port = parseInt(options.port ?? '3737', 10);
+    let version = 0;
+    const pendingVersionPolls = [];
+    function flushVersionPolls() {
+        while (pendingVersionPolls.length > 0) {
+            const poll = pendingVersionPolls.shift();
+            poll.res.writeHead(200, { 'Content-Type': 'application/json' });
+            poll.res.end(JSON.stringify({ version }));
+        }
+    }
+    // Watch project dir for changes
+    fs.watch(projectDir, { recursive: true }, (event, filename) => {
+        if (filename && !filename.startsWith('.')) {
+            version++;
+            flushVersionPolls();
+        }
+    });
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+        const pathname = url.pathname;
+        // Version polling for hot reload
+        if (pathname === '/__version') {
+            const clientVersion = parseInt(url.searchParams.get('v') ?? '0', 10);
+            if (clientVersion < version) {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ version }));
+            }
+            else {
+                // Long poll — wait for next change
+                pendingVersionPolls.push({ clientVersion, res });
+                const timeout = setTimeout(() => {
+                    const idx = pendingVersionPolls.findIndex((p) => p.res === res);
+                    if (idx >= 0)
+                        pendingVersionPolls.splice(idx, 1);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ version }));
+                }, 30000);
+                res.on('close', () => {
+                    clearTimeout(timeout);
+                    const idx = pendingVersionPolls.findIndex((p) => p.res === res);
+                    if (idx >= 0)
+                        pendingVersionPolls.splice(idx, 1);
+                });
+            }
+            return;
+        }
+        // Serve static files
+        let filePath = path.join(projectDir, pathname === '/' ? 'index.html' : pathname);
+        filePath = path.normalize(filePath);
+        // Security: don't serve files outside project dir
+        if (!filePath.startsWith(projectDir)) {
+            res.writeHead(403);
+            res.end('Forbidden');
+            return;
+        }
+        if (!fs.existsSync(filePath)) {
+            res.writeHead(404);
+            res.end('Not found');
+            return;
+        }
+        const stat = fs.statSync(filePath);
+        if (stat.isDirectory()) {
+            filePath = path.join(filePath, 'index.html');
+            if (!fs.existsSync(filePath)) {
+                res.writeHead(404);
+                res.end('Not found');
+                return;
+            }
+        }
+        const ext = path.extname(filePath).toLowerCase();
+        const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
+        const data = fs.readFileSync(filePath);
+        res.writeHead(200, { 'Content-Type': contentType });
+        res.end(data);
+    });
+    server.listen(port, () => {
+        const url = `http://localhost:${port}`;
+        console.log(`Serving ${projectDir}`);
+        console.log(`  ${url}`);
+        console.log('Press Ctrl+C to stop.');
+        if (options.open) {
+            import('open').then(({ default: open }) => open(url));
+        }
+    });
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "castle-web-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "castle-web": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.0",
+    "nanoid": "^5.1.7",
+    "open": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,137 @@
+import * as config from './config.js';
+
+const API_HOST = 'https://api.castle.xyz/graphql';
+
+async function graphql(query: string, variables?: Record<string, unknown>): Promise<any> {
+  const token = config.getToken();
+  const headers: Record<string, string> = {
+    'X-OS': 'cli',
+    'X-CLI-API-Version': '2',
+    'Content-Type': 'application/json',
+    Accept: 'application/json',
+  };
+  if (token) headers['X-Auth-Token'] = token;
+  const res = await fetch(API_HOST, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(variables ? { query, variables } : { query }),
+    signal: AbortSignal.timeout(10000),
+  });
+  return res.json();
+}
+
+function handleAPIError(data: any): void {
+  if (data?.errors?.length) {
+    const err: any = new Error(data.errors[0]?.message ?? 'GraphQL error');
+    err.extensions = data.errors[0]?.extensions;
+    throw err;
+  }
+}
+
+export async function startCLILogin(): Promise<{ pollToken: string; url: string }> {
+  const data = await graphql(`mutation { startCLILogin { pollToken url } }`);
+  handleAPIError(data);
+  return data.data.startCLILogin;
+}
+
+export async function pollForCLILogin(pollToken: string): Promise<any> {
+  const data = await graphql(
+    `query($pollToken: String!) {
+       pollForCLILogin(pollToken: $pollToken) {
+         userId username token isAnonymous
+       }
+     }`,
+    { pollToken }
+  );
+  handleAPIError(data);
+  return data.data?.pollForCLILogin ?? null;
+}
+
+export async function me(): Promise<any> {
+  try {
+    const data = await graphql(`query { me { userId username isAnonymous } }`);
+    return data.data?.me ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export async function myDecks(): Promise<any[]> {
+  const data = await graphql(`query {
+    me {
+      decks {
+        deckId
+        title
+        initialCard { cardId }
+      }
+    }
+  }`);
+  handleAPIError(data);
+  return data.data?.me?.decks ?? [];
+}
+
+export async function updateCardAndDeckV2(
+  deck: Record<string, unknown>,
+  card: Record<string, unknown>,
+): Promise<{ deckId: string; cardId: string }> {
+  const data = await graphql(
+    `mutation($deck: DeckInput!, $card: CardInput!) {
+       updateCardAndDeckV2(deck: $deck, card: $card) {
+         deck { deckId }
+         card { cardId }
+       }
+     }`,
+    { deck, card }
+  );
+  handleAPIError(data);
+  return {
+    deckId: data.data.updateCardAndDeckV2.deck.deckId,
+    cardId: data.data.updateCardAndDeckV2.card.cardId,
+  };
+}
+
+export async function createDeck(
+  deck: Record<string, unknown>,
+  card: Record<string, unknown>
+): Promise<{ deckId: string; cardId: string }> {
+  const data = await graphql(
+    `mutation($deck: DeckInput!, $card: CardInput!) {
+       createDeck(deck: $deck, card: $card) {
+         deckId
+         initialCard { cardId }
+       }
+     }`,
+    { deck, card }
+  );
+  handleAPIError(data);
+  return {
+    deckId: data.data.createDeck.deckId,
+    cardId: data.data.createDeck.initialCard.cardId,
+  };
+}
+
+export async function createSceneDataUploadConfig(cardIds: string[]): Promise<any[]> {
+  const data = await graphql(
+    `mutation($cardIds: [ID!]!) {
+       createSceneDataUploadConfig(cardIds: $cardIds) {
+         cardId uploadId postUrl postFields
+       }
+     }`,
+    { cardIds }
+  );
+  handleAPIError(data);
+  return data.data.createSceneDataUploadConfig;
+}
+
+export async function uploadSceneData(
+  cards: Array<{ cardId: string; uploadId: string }>
+): Promise<any[]> {
+  const data = await graphql(
+    `mutation($cards: [CardSceneDataInput!]!) {
+       uploadSceneData(cards: $cards) { cardId sceneDataUrl }
+     }`,
+    { cards }
+  );
+  handleAPIError(data);
+  return data.data.uploadSceneData;
+}

package/src/bundle.ts

@@ -0,0 +1,35 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as esbuild from 'esbuild';
+
+export function bundleProject(dir: string): string {
+  const indexPath = path.join(dir, 'index.html');
+  if (!fs.existsSync(indexPath)) {
+    throw new Error(`No index.html found in ${dir}`);
+  }
+
+  let html = fs.readFileSync(indexPath, 'utf-8');
+
+  // Find <script src="..."> tags, bundle each with esbuild, inline the result
+  html = html.replace(
+    /<script\s+([^>]*?)src=["']([^"']+)["']([^>]*?)>\s*<\/script>/gi,
+    (fullMatch, before, src, after) => {
+      const srcPath = path.resolve(dir, src);
+      if (!fs.existsSync(srcPath)) return fullMatch;
+
+      const result = esbuild.buildSync({
+        entryPoints: [srcPath],
+        bundle: true,
+        format: 'esm',
+        write: false,
+        minify: false,
+      });
+
+      const code = result.outputFiles[0].text;
+      const attrs = `${before}${after}`.trim();
+      return `<script type="module"${attrs ? ' ' + attrs : ''}>\n${code}</script>`;
+    }
+  );
+
+  return html;
+}

package/src/config.ts

@@ -0,0 +1,36 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+function getConfigDir() {
+  return path.join(os.homedir(), '.castle');
+}
+
+function readConfigFile(filename: string): any {
+  const configDir = getConfigDir();
+  const configFilePath = path.join(configDir, filename);
+  try {
+    if (fs.existsSync(configFilePath)) {
+      return JSON.parse(fs.readFileSync(configFilePath, 'utf-8'));
+    }
+  } catch {}
+  return null;
+}
+
+export function getToken(): string | null {
+  const config = readConfigFile('config.json');
+  return config ? config.token : null;
+}
+
+export function setToken(token: string | null): void {
+  const configDir = getConfigDir();
+  fs.mkdirSync(configDir, { recursive: true });
+  const existing = readConfigFile('config.json') ?? {};
+  if (token === null) {
+    delete existing.token;
+  } else {
+    existing.token = token;
+  }
+  const configFilePath = path.join(configDir, 'config.json');
+  fs.writeFileSync(configFilePath, JSON.stringify(existing, null, 2), 'utf-8');
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { login } from './login.js';
+import { serve } from './serve.js';
+import { push } from './push.js';
+import { init } from './init.js';
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function usage() {
+  console.log(`Usage:
+  castle-web init <dir>
+  castle-web serve [dir] [--port PORT] [--open]
+  castle-web push [dir]
+  castle-web login
+
+Install: cd castle-experimental-web/cli && npm install && npm run build && npm link`);
+  process.exit(1);
+}
+
+async function main() {
+  switch (command) {
+    case 'init': {
+      const dir = args[1];
+      if (!dir) { console.error('Usage: castle-web init <dir>'); process.exit(1); }
+      init(dir);
+      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 open = args.includes('--open');
+      await serve(dir, { port, open });
+      break;
+    }
+    case 'push': {
+      const dir = args.find((a, i) => i > 0 && !a.startsWith('--')) ?? '.';
+      await push(dir);
+      break;
+    }
+    case 'login':
+      await login();
+      break;
+    default:
+      usage();
+  }
+}
+
+main().catch((e) => {
+  console.error(e.message ?? e);
+  process.exit(1);
+});

package/src/init.ts

@@ -0,0 +1,65 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+const INDEX_HTML = `<!DOCTYPE html>
+<html>
+<head>
+  <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
+  <title>My Castle Game</title>
+</head>
+<body>
+  <script type="module" src="game.js"></script>
+</body>
+</html>
+`;
+
+const GAME_JS = `import * as castle from 'castle-web-sdk';
+
+castle.enableHotReload();
+const card = castle.initCard();
+
+const div = document.createElement('div');
+div.style.cssText = \`
+  width: 100%; height: 100%;
+  display: flex; align-items: center; justify-content: center;
+  font-family: system-ui; color: #fff; font-size: 24px;
+\`;
+div.textContent = 'Hello Castle!';
+card.appendChild(div);
+`;
+
+export async function init(dir: string) {
+  const projectDir = path.resolve(dir);
+
+  if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
+    console.error(`Directory "${dir}" is not empty.`);
+    process.exit(1);
+  }
+
+  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
+  const packageJson = {
+    name: path.basename(projectDir),
+    private: true,
+    type: 'module',
+    dependencies: {
+      'castle-web-sdk': '*',
+    },
+  };
+  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');
+}

package/src/login.ts

@@ -0,0 +1,24 @@
+import * as api from './api.js';
+import * as config from './config.js';
+
+export async function login(): Promise<void> {
+  const { pollToken, url } = await api.startCLILogin();
+  console.log(`Opening browser to log in: ${url}`);
+  const { default: open } = await import('open');
+  await open(url);
+  console.log('Waiting for login...');
+
+  const MAX_POLLS = 600;
+  for (let i = 0; i < MAX_POLLS; i++) {
+    await new Promise((r) => setTimeout(r, 1000));
+    const user = await api.pollForCLILogin(pollToken);
+    if (user) {
+      config.setToken(user.token);
+      console.log(`Logged in as @${user.username}`);
+      return;
+    }
+  }
+
+  console.error('Login timed out.');
+  process.exit(1);
+}

package/src/push.ts

@@ -0,0 +1,114 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { nanoid } from 'nanoid';
+import * as api from './api.js';
+import * as config from './config.js';
+import { bundleProject } from './bundle.js';
+
+interface CastleJson {
+  deckId: string;
+  cardId: string;
+}
+
+function readCastleJson(dir: string): CastleJson | null {
+  const p = path.join(dir, 'castle.json');
+  if (!fs.existsSync(p)) return null;
+  return JSON.parse(fs.readFileSync(p, 'utf-8'));
+}
+
+function buildSceneData(bundle: string): any {
+  return {
+    experimentalWeb: {
+      enabled: true,
+      bundle,
+    },
+    snapshot: {
+      sceneProperties: {
+        backgroundColor: { r: 0, g: 0, b: 0, a: 1 },
+        coordinateSystemVersion: 2,
+      },
+      actors: [],
+      library: {},
+      linkTargetDeckIds: [],
+    },
+  };
+}
+
+export async function push(dir: string) {
+  if (!config.getToken()) {
+    console.error('Not logged in. Run `castle-web login` first.');
+    process.exit(1);
+  }
+
+  const projectDir = path.resolve(dir);
+  if (!fs.existsSync(path.join(projectDir, 'index.html'))) {
+    console.error(`No index.html found in ${projectDir}`);
+    process.exit(1);
+  }
+
+  let castleJson = readCastleJson(projectDir);
+
+  console.log('Bundling...');
+  const bundle = bundleProject(projectDir);
+  console.log(`Bundle size: ${(bundle.length / 1024).toFixed(1)}KB`);
+
+  const sceneData = buildSceneData(bundle);
+  const isNew = !castleJson;
+  const cardId = castleJson?.cardId ?? nanoid(12);
+  const deckId = castleJson?.deckId ?? nanoid(12);
+
+  // Upload scene data to S3
+  const configs = await api.createSceneDataUploadConfig([cardId]);
+  if (!configs?.length) {
+    console.error('Failed to get upload config.');
+    process.exit(1);
+  }
+
+  const uploadConfig = configs[0];
+  const formData = new FormData();
+  formData.append('Content-Type', 'application/json');
+  for (const [k, v] of Object.entries(uploadConfig.postFields)) {
+    formData.append(k, `${v}`);
+  }
+  formData.append('file', new Blob([JSON.stringify(sceneData)]));
+
+  const s3Res = await fetch(uploadConfig.postUrl, {
+    method: 'POST',
+    body: formData,
+    signal: AbortSignal.timeout(30000),
+  });
+  if (s3Res.status >= 300) {
+    throw new Error(`Upload failed: HTTP ${s3Res.status}`);
+  }
+
+  // Create or update via updateCardAndDeckV2
+  const title = path.basename(path.resolve(projectDir));
+  try {
+    const result = await api.updateCardAndDeckV2(
+      { deckId, title },
+      { cardId, blocks: [], uploadId: uploadConfig.uploadId, makeInitialCard: true }
+    );
+
+    if (isNew) {
+      const newCastleJson = { deckId: result.deckId, cardId: result.cardId };
+      fs.writeFileSync(
+        path.join(projectDir, 'castle.json'),
+        JSON.stringify(newCastleJson, null, 2) + '\n',
+        'utf-8'
+      );
+      console.log(`Created deck "${title}" (${result.deckId}). Saved castle.json.`);
+    } else {
+      console.log('Pushed to Castle.');
+    }
+  } catch (e: any) {
+    const code = e?.extensions?.code ?? '';
+    if (code === 'LOGIN_REQUIRED') {
+      console.error('Not logged in. Run `castle-web login` first.');
+    } else if (code === 'DECK_INVALID_PERMISSIONS') {
+      console.error('You do not have permission to push to this deck.');
+    } else {
+      throw e;
+    }
+    process.exit(1);
+  }
+}

package/src/serve.ts

@@ -0,0 +1,135 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as http from 'http';
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.wasm': 'application/wasm',
+  '.ico': 'image/x-icon',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.ttf': 'font/ttf',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+export async function serve(
+  dir: string,
+  options: { port?: string; open?: boolean } = {}
+) {
+  const projectDir = path.resolve(dir);
+  if (!fs.existsSync(projectDir)) {
+    console.error(`Directory not found: ${projectDir}`);
+    process.exit(1);
+  }
+
+  const indexPath = path.join(projectDir, 'index.html');
+  if (!fs.existsSync(indexPath)) {
+    console.error(`No index.html found in ${projectDir}`);
+    process.exit(1);
+  }
+
+  const port = parseInt(options.port ?? '3737', 10);
+  let version = 0;
+  const pendingVersionPolls: Array<{ clientVersion: number; res: http.ServerResponse }> = [];
+
+  function flushVersionPolls() {
+    while (pendingVersionPolls.length > 0) {
+      const poll = pendingVersionPolls.shift()!;
+      poll.res.writeHead(200, { 'Content-Type': 'application/json' });
+      poll.res.end(JSON.stringify({ version }));
+    }
+  }
+
+  // Watch project dir for changes
+  fs.watch(projectDir, { recursive: true }, (event, filename) => {
+    if (filename && !filename.startsWith('.')) {
+      version++;
+      flushVersionPolls();
+    }
+  });
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+    const pathname = url.pathname;
+
+    // Version polling for hot reload
+    if (pathname === '/__version') {
+      const clientVersion = parseInt(url.searchParams.get('v') ?? '0', 10);
+      if (clientVersion < version) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ version }));
+      } else {
+        // Long poll — wait for next change
+        pendingVersionPolls.push({ clientVersion, res });
+        const timeout = setTimeout(() => {
+          const idx = pendingVersionPolls.findIndex((p) => p.res === res);
+          if (idx >= 0) pendingVersionPolls.splice(idx, 1);
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ version }));
+        }, 30000);
+        res.on('close', () => {
+          clearTimeout(timeout);
+          const idx = pendingVersionPolls.findIndex((p) => p.res === res);
+          if (idx >= 0) pendingVersionPolls.splice(idx, 1);
+        });
+      }
+      return;
+    }
+
+    // Serve static files
+    let filePath = path.join(projectDir, pathname === '/' ? 'index.html' : pathname);
+    filePath = path.normalize(filePath);
+
+    // Security: don't serve files outside project dir
+    if (!filePath.startsWith(projectDir)) {
+      res.writeHead(403);
+      res.end('Forbidden');
+      return;
+    }
+
+    if (!fs.existsSync(filePath)) {
+      res.writeHead(404);
+      res.end('Not found');
+      return;
+    }
+
+    const stat = fs.statSync(filePath);
+    if (stat.isDirectory()) {
+      filePath = path.join(filePath, 'index.html');
+      if (!fs.existsSync(filePath)) {
+        res.writeHead(404);
+        res.end('Not found');
+        return;
+      }
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] ?? 'application/octet-stream';
+    const data = fs.readFileSync(filePath);
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(data);
+  });
+
+  server.listen(port, () => {
+    const url = `http://localhost:${port}`;
+    console.log(`Serving ${projectDir}`);
+    console.log(`  ${url}`);
+    console.log('Press Ctrl+C to stop.');
+
+    if (options.open) {
+      import('open').then(({ default: open }) => open(url));
+    }
+  });
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}