castle-web-cli 0.4.122 → 0.4.124

package/dist/index.js

@@ -9,7 +9,8 @@ import { addImport, updateImport } from './imports.js';
 import { listDecks } from './list-decks.js';
 import { getCliVersion, init } from './init.js';
 import { install } from './install.js';
-import { connectWS, savePreviewImage, takeScreenshot } from './preview.js';
+import { connectWS, takeScreenshot } from './preview.js';
+import { listVersions, restoreVersion, saveVersion, showVersion } from './versions.js';
 const args = process.argv.slice(2);
 const command = args[0];
 const FLAGS_WITH_VALUES = new Set([
@@ -23,10 +24,19 @@ const FLAGS_WITH_VALUES = new Set([
     '--visibility',
     '--as',
     '--kind',
+    '--dir',
+    '--message',
+    '-m',
 ]);
+// `--foo` is always a flag; a single dash only when it is one we know (`-m`).
+// Anything else starting with `-` is a positional -- a path can begin with one,
+// and so can an opaque version id.
+function isFlag(arg) {
+    return arg.startsWith('--') || FLAGS_WITH_VALUES.has(arg);
+}
 function findPositionalDir() {
     for (let i = 1; i < args.length; i++) {
-        if (args[i].startsWith('--')) {
+        if (isFlag(args[i])) {
             if (FLAGS_WITH_VALUES.has(args[i]))
                 i++;
             continue;
@@ -41,7 +51,7 @@ function findPositionalDir() {
 function readPositionals() {
     const out = [];
     for (let i = 1; i < args.length; i++) {
-        if (args[i].startsWith('--')) {
+        if (isFlag(args[i])) {
             if (FLAGS_WITH_VALUES.has(args[i]))
                 i++;
             continue;
@@ -81,13 +91,16 @@ function usage() {
   castle-web serve [dir] [--port PORT] [--host HOST] [--open] [--detach]
   castle-web restart [--port PORT]
   castle-web screenshot [--out FILE] [--port PORT]
-  castle-web save-preview-image [dir] [--port PORT] [--no-restart]
   castle-web save-deck [dir] [--title TITLE] [--caption TEXT] [--visibility unlisted|private]
   castle-web get-deck [dir] [--deck-id ID] [--force]   (replaces the source if the deck is already there)
   castle-web list-decks [dir] [--kind mine|saved|kits]   (decks this one could import; ids are what add-import takes)
   castle-web add-import <deckId|url> [dir] [--as ALIAS]   (adds another deck as a read-only dependency in imports/)
   castle-web update-import [alias] [dir] [--check] [--revert]   (re-fetches imports; no alias means all)
   castle-web install [dir]
+  castle-web save-version [-m MESSAGE] [paths...] [--dir DIR]   (no paths saves the whole deck)
+  castle-web list-versions [version] [--dir DIR]   (defaults to the latest version)
+  castle-web show-version <version> [--dir DIR]   (diffs of the files that version changed)
+  castle-web restore-version <version> [--force] [--dir DIR]
   castle-web login
   castle-web --version
 
@@ -173,6 +186,38 @@ async function main() {
             await install(findPositionalDir());
             break;
         }
+        // The version commands spend their positionals on their own arguments --
+        // paths to save, a version to list from or restore to -- so the deck dir is
+        // `--dir`, defaulting to the cwd.
+        case 'save-version': {
+            saveVersion(getFlagValue('--dir') ?? '.', {
+                message: getFlagValue('-m') ?? getFlagValue('--message'),
+                paths: readPositionals(),
+            });
+            break;
+        }
+        case 'list-versions': {
+            listVersions(getFlagValue('--dir') ?? '.', readPositionals()[0]);
+            break;
+        }
+        case 'show-version': {
+            const target = readPositionals()[0];
+            if (!target) {
+                console.error('Usage: castle-web show-version <version>');
+                process.exit(1);
+            }
+            showVersion(getFlagValue('--dir') ?? '.', target);
+            break;
+        }
+        case 'restore-version': {
+            const target = readPositionals()[0];
+            if (!target) {
+                console.error('Usage: castle-web restore-version <version> [--force]');
+                process.exit(1);
+            }
+            restoreVersion(getFlagValue('--dir') ?? '.', target, { force: hasFlag('--force') });
+            break;
+        }
         case 'restart': {
             const dir = findPositionalDir();
             const wsPort = getWsPort(dir);
@@ -196,13 +241,6 @@ async function main() {
             console.log(`Saved ${outFile}`);
             return;
         }
-        case 'save-preview-image': {
-            const dir = findPositionalDir();
-            const wsPort = getWsPort(dir);
-            const noRestart = args.includes('--no-restart');
-            await savePreviewImage(dir, wsPort, noRestart);
-            return;
-        }
         case 'login':
             await login();
             break;

package/dist/init.d.ts

@@ -9,6 +9,7 @@ export declare function isPristineBareDeck(dir: string): boolean;
 export declare function adoptImportEntry(deckDir: string, alias: string, mainFile: string): void;
 export declare function getCliVersion(): string;
 export declare function writeStarterScene(projectDir: string, kitDir: string, alias: string): void;
+export declare function writeStarterTheme(projectDir: string, kitDir: string): void;
 export declare function init(dir: string, opts?: {
     kit?: string;
     serve?: boolean;

package/dist/init.js

@@ -6,6 +6,7 @@ import { deckMainFile, deckStarterScene } from './castleJson.js';
 import { IMPORTS_DIR, lockImportTree } from './imports.js';
 import { getCliEntryPath, getKitsDir, getRepoRoot, getSdkPackagePath, toPosixPath, } from './localPaths.js';
 import { serve } from './serve.js';
+import { createVersion } from './versions.js';
 const INDEX_HTML = `<!DOCTYPE html>
 <html>
 <head>
@@ -37,7 +38,7 @@ const DEFAULT_KIT = 'physics-2d';
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = '0.4.13';
+const PUBLISHED_SDK_VERSION = '0.4.14';
 // The account the first-party kits are (to be) published under, so a kit
 // imported from the CLI's copy is named the same as one fetched from the server.
 const KIT_AUTHOR = 'castle';
@@ -280,6 +281,19 @@ export function writeStarterScene(projectDir, kitDir, alias) {
     fs.mkdirSync(path.join(projectDir, 'scenes'), { recursive: true });
     writeJsonFile(path.join(projectDir, 'scenes', 'main.scene'), scene ? rewrite(scene) : { name: 'Main', actors: [] });
 }
+// A kit may ship a starter `theme.style` (deck-level styling, e.g. the color
+// palette). Like the starter scene, it is deck content: the engine reads it
+// from the DECK root, and it is the creator's to edit -- so it gets seeded once
+// at scaffold time rather than living read-only in the import. Copied verbatim
+// (its values are palette ids/hexes, never kit file paths, so no ref
+// rewriting). Exported for the same two scaffold paths as writeStarterScene.
+export function writeStarterTheme(projectDir, kitDir) {
+    const src = path.join(kitDir, 'theme.style');
+    const dest = path.join(projectDir, 'theme.style');
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return;
+    fs.copyFileSync(src, dest);
+}
 function makeImportedKitClaudeMd(alias) {
     return `# Castle deck
 
@@ -353,6 +367,7 @@ function scaffoldFromKitImport(kit, projectDir) {
     const title = typeof kitConfig.title === 'string' ? kitConfig.title : kit;
     writeDeckIndexHtml(projectDir, alias, title, deckMainFile(kitDir));
     writeStarterScene(projectDir, kitDir, alias);
+    writeStarterTheme(projectDir, kitDir);
     // The deck's own castle.json: the kit's editor config (panel layout, file
     // filters) as a starting point -- it is the deck's to edit from here -- plus
     // the import pin.
@@ -386,6 +401,34 @@ function scaffoldFromKitImport(kit, projectDir) {
     appendCommonInstructions(projectDir);
     lockImportTree(importDir);
 }
+// The scaffold as version 1, so a creator can always get back to the pristine
+// deck. AFTER the install: it rewrites package.json and writes a lockfile, so a
+// version taken before it describes a tree that never existed on disk, and a
+// later restore would fight the package manager.
+//
+// This is the ordinary save path with no parent -- `parentId: null` and every
+// file as an addition -- so the store has no special case for it. It composes
+// with the no-op rule for free: `save-version` straight after init records
+// nothing, so a fresh deck has exactly one version.
+//
+// The message is the only place a deck's kit lineage is recorded at all.
+// Existing decks get none of this: their history starts at their first save,
+// because a baseline synthesized from mid-work content would be labelled
+// pristine while being nothing of the sort.
+function saveInitialVersion(projectDir, kit) {
+    try {
+        const { version } = createVersion(projectDir, {
+            message: kit ? `New deck from ${kit}` : 'New deck',
+        });
+        if (version)
+            console.log(`Saved version ${version.id} — the deck as scaffolded.`);
+    }
+    catch (e) {
+        // A deck that scaffolded but failed to record its first version is still a
+        // deck. Losing the scaffold over it would be the wrong trade.
+        console.log(`Could not save the initial version: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
 export async function init(dir, opts = {}) {
     const projectDir = path.resolve(dir);
     if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {
@@ -423,6 +466,7 @@ export async function init(dir, opts = {}) {
     catch {
         console.error('dependency install failed; re-run `pnpm install` (or `npm install`) in the deck.');
     }
+    saveInitialVersion(projectDir, bare ? null : kit);
     const autoServe = opts.serve !== false;
     if (autoServe && installed) {
         // Call serve() with detach so init returns once the server is up. serve()

package/dist/localPaths.d.ts

@@ -3,4 +3,5 @@ export declare function getRepoRoot(): string;
 export declare function getCliEntryPath(): string;
 export declare function getSdkPackagePath(): string;
 export declare function getKitsDir(): string;
+export declare const COVER_FILE = "preview.png";
 export declare function toPosixPath(filepath: string): string;

package/dist/localPaths.js

@@ -28,6 +28,11 @@ export function getKitsDir() {
         return bundled;
     return path.join(getRepoRoot(), 'kits');
 }
+// The deck's local cover image, deck-relative. Lives here rather than in the
+// serve that writes it, because the version code needs to know about it too and
+// `ide.ts` already imports that -- naming it here keeps the two from importing
+// each other.
+export const COVER_FILE = 'preview.png';
 export function toPosixPath(filepath) {
     return filepath.split(path.sep).join('/');
 }

package/dist/preview.d.ts

@@ -1,4 +1,3 @@
 import type { WebSocket as WSClient } from 'ws';
 export declare function connectWS(wsPort: number): Promise<WSClient>;
 export declare function takeScreenshot(ws: WSClient): Promise<string>;
-export declare function savePreviewImage(dir: string, wsPort: number, noRestart?: boolean): Promise<void>;

package/dist/preview.js

@@ -1,7 +1,3 @@
-import * as fs from 'fs';
-import * as path from 'path';
-import * as api from './api.js';
-import * as config from './config.js';
 export async function connectWS(wsPort) {
     const { default: WS } = await import('ws');
     return new Promise((resolve, reject) => {
@@ -45,57 +41,3 @@ export function takeScreenshot(ws) {
         ws.send(JSON.stringify({ type: 'screenshot_request', requestId }));
     });
 }
-function waitForRestart(ws) {
-    return new Promise((resolve) => {
-        ws.send(JSON.stringify({ type: 'restart' }));
-        setTimeout(resolve, 2000);
-    });
-}
-// The shared declaration (castleJson.ts) rather than a local copy of the two
-// fields this file reads, so it can't drift from what the rest of the CLI
-// believes castle.json contains.
-function readCastleJson(projectDir) {
-    const castleJsonPath = path.join(projectDir, 'castle.json');
-    if (!fs.existsSync(castleJsonPath))
-        return null;
-    return JSON.parse(fs.readFileSync(castleJsonPath, 'utf-8'));
-}
-async function captureAndUpload(projectDir, ws, castleJson) {
-    // A deck has no cardId until its first save, and the cover IS that card's
-    // background -- so there is nothing to set it on yet. Both callers reach here
-    // right after a save, so this is the never-saved edge, not the normal path.
-    // Reported back so a caller doesn't record a cover that was never set.
-    const { cardId } = castleJson;
-    if (!cardId) {
-        ws.close();
-        console.log('Preview skipped: save the deck first.');
-        return false;
-    }
-    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(cardId, file.fileId);
-    console.log('Set deck preview image.');
-    return true;
-}
-export async function savePreviewImage(dir, wsPort, noRestart = false) {
-    const projectDir = path.resolve(dir);
-    const castleJson = readCastleJson(projectDir);
-    if (!castleJson) {
-        console.error('No castle.json found. Save the deck first.');
-        process.exit(1);
-    }
-    if (!config.getToken()) {
-        console.error('Not logged in. Run `castle-web login` first.');
-        process.exit(1);
-    }
-    const ws = await connectWS(wsPort);
-    if (!noRestart)
-        await waitForRestart(ws);
-    // Asking for this by name is choosing a cover, so it goes to the card's
-    // CUSTOM slot -- the one that takes precedence over the cover a save
-    // publishes. Clearing it is an editor action (Deck settings -> Clear cover).
-    await captureAndUpload(projectDir, ws, castleJson);
-}

package/dist/save-deck.js

@@ -79,8 +79,59 @@ async function uploadSource(projectDir, deckId) {
 //
 // Never fatal: a deck that saves but whose cover upload failed is a deck that
 // saved. Losing the push over a thumbnail would be the wrong trade.
+// The deck's own serve, if one is running -- the URL a headless cover capture
+// loads. No serve means no deck to photograph, which is a normal state (a save
+// from a script), not an error.
+function runningServeUrl(projectDir) {
+    try {
+        const raw = fs.readFileSync(path.join(projectDir, '.castle', 'serve.json'), 'utf8');
+        const port = JSON.parse(raw).port;
+        return typeof port === 'number' ? `http://localhost:${port}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+// Photograph the running deck with a real browser, into a scratch file.
+//
+// This OUTRANKS the editor's `preview.png`, and deliberately: both are the
+// AUTOMATIC cover (a creator's hand-picked one lives in the card's custom slot
+// and outranks both), so the question is only which automatic capture is better
+// -- and the in-page one silently drops a WebGL canvas that lacks
+// `preserveDrawingBuffer`, plus anything using `filter`/`clip-path`/`mask`. A
+// browser compositing its own frame has no such list.
+//
+// `preview.png` does have one real advantage -- it is whatever the creator last
+// had on screen, where this is a cold load -- so it stays the fallback. But a
+// cover that is missing the game beats a cover of the opening seconds only if
+// you never look at it, and nobody looks at an unattended capture. Writing to a
+// scratch file rather than over `preview.png` keeps that fallback intact.
+async function captureAutomaticCover(projectDir) {
+    const serveUrl = runningServeUrl(projectDir);
+    if (!serveUrl)
+        return null;
+    const outPath = path.join(projectDir, '.castle', 'headless-cover.png');
+    const { captureCoverHeadless } = await import('./headlessCover.js');
+    const result = await captureCoverHeadless({
+        serveUrl,
+        outPath,
+        onProgress: (message) => console.log(message),
+    });
+    if (!result.ok) {
+        // Never fatal, same as the upload below: a deck that saved without a cover
+        // is a deck that saved.
+        console.log(`Cover capture skipped: ${result.error}`);
+        return null;
+    }
+    return outPath;
+}
 async function uploadLocalCover(projectDir) {
-    const coverPath = path.join(projectDir, COVER_FILE);
+    const captured = await captureAutomaticCover(projectDir);
+    const coverPath = captured ?? path.join(projectDir, COVER_FILE);
+    if (captured)
+        console.log('Captured a cover from the running deck.');
+    else if (fs.existsSync(coverPath))
+        console.log('Using the cover captured in the editor.');
     if (!fs.existsSync(coverPath))
         return null;
     try {

package/dist/serve.js

@@ -239,6 +239,22 @@ export async function serve(dir, options = {}) {
             console.warn(`auto-update: skipped -- ${e instanceof Error ? e.message : String(e)}`);
         });
     }
+    // Start pulling the headless browser now, in the background.
+    //
+    // `save-deck` photographs the deck with it to make the deck's cover, and the
+    // binary is a ~250MB one-time download. Left lazy, that download lands inside
+    // the creator's first "Push to Castle" -- the one moment they are watching a
+    // spinner and least want an unexplained wait. A serve means someone is editing
+    // a deck they will probably push, so this is the cheapest place to get ahead
+    // of it.
+    //
+    // Fire-and-forget and single-flight: it shares one download with the agent's
+    // playtest tool, so this is free when that already pulled it, and every
+    // failure is swallowed -- the capture re-detects and reports properly at the
+    // point it actually matters.
+    void import('./native/playtest-browser.js')
+        .then((m) => m.createPlaytestBrowserManager().prewarm())
+        .catch(() => undefined);
     // Close stdin when not attached to a TTY so the process can be cleanly
     // backgrounded with `&` (otherwise stdin reads can block or hold the parent).
     if (!process.stdin.isTTY) {