castle-web-cli 0.4.169 → 0.4.170

package/dist/save-deck.js

@@ -7,7 +7,8 @@ import * as api from './api.js';
 import * as config from './config.js';
 import { bundleProject } from './bundle.js';
 import { resolveServerConfig } from './castleJson.js';
-import { COVER_FILE } from './ide.js';
+import { selectSaveCover } from './saveCover.js';
+import { COVER_FILE } from './localPaths.js';
 import { buildServerBundle } from './serverBundle.js';
 // `imports/` is derived state like node_modules: a dependency's files belong to
 // the deck that published them, and castle.json's import pins are enough to fetch
@@ -20,6 +21,7 @@ export const SOURCE_ARCHIVE_EXCLUDES = ['node_modules', 'dist', '.castle', '.git
 // adding machine output to interactive local saves. Old CLIs ignore the env, so releases remain
 // independently deployable.
 export const SAVE_STAGE_TELEMETRY_PREFIX = 'CASTLE_SAVE_TELEMETRY ';
+export const SAVE_COVER_SELECTION_TELEMETRY_PREFIX = 'CASTLE_SAVE_COVER_SELECTION ';
 function emitSaveStage(stage, outcome, startedAtMs, fields = {}) {
     if (process.env.CASTLE_SAVE_STAGE_TELEMETRY !== '1')
         return;
@@ -90,6 +92,21 @@ export async function archiveSource(projectDir) {
         }
     }
 }
+// Written to tmp and read or untarred out of there, never moved out: in a sandbox
+// the deck is on a different filesystem from tmp, and a rename across that is EXDEV.
+// The caller owns the file it gets back.
+export async function downloadSourceArchive(source, namePrefix) {
+    console.log(`Fetching ${source.archiveUrl}`);
+    const res = await fetch(source.archiveUrl, { signal: AbortSignal.timeout(60000) });
+    if (!res.ok) {
+        throw new Error(`Archive fetch failed: HTTP ${res.status}`);
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    console.log(`Archive: ${(buf.length / 1024).toFixed(1)}KB (updated ${source.updatedAt})`);
+    const file = path.join(os.tmpdir(), `${namePrefix}-${nanoid(8)}.tar.gz`);
+    fs.writeFileSync(file, buf);
+    return file;
+}
 async function uploadPresignedFile(uploadConfig, file, contentType, timeoutMs, label) {
     const formData = new FormData();
     formData.append('Content-Type', contentType);
@@ -166,83 +183,24 @@ async function publishServerBundle(projectDir, deckId) {
     writePublishedServerBundleState(projectDir, { deckId, sha256: bundle.sha256 });
     console.log(`Server bundle published${saved ? ` as ${saved.version}` : ''} (sha256 ${bundle.sha256}).`);
 }
-// Publish the deck's local cover, if it has one, and return the file id for the
-// card. The editor writes `preview.png` as you play (see the serve's cover
-// endpoint); this is the moment it becomes public.
-//
-// 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.
-async function runningServeUrl(projectDir) {
-    try {
-        const raw = fs.readFileSync(path.join(projectDir, '.castle', 'serve.json'), 'utf8');
-        const parsed = JSON.parse(raw);
-        const port = parsed.port;
-        if (process.env.CASTLE_SANDBOX_ID && typeof port === 'number') {
-            try {
-                const response = await fetch(`http://localhost:${port}/__castle/browser-content-grant`, { signal: AbortSignal.timeout(2_000) });
-                const body = (await response.json());
-                if (response.ok && typeof body.url === 'string')
-                    return body.url;
-            }
-            catch {
-                // Fall through to the existing best-effort local capture path.
-            }
-        }
-        if (typeof parsed.contentPlayUrl === 'string')
-            return parsed.contentPlayUrl;
-        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 = await 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) {
     try {
-        const captured = await captureAutomaticCover(projectDir);
-        const coverPath = captured ?? path.join(projectDir, COVER_FILE);
-        if (captured)
+        const selected = await selectSaveCover(projectDir, { onProgress: (message) => console.log(message) });
+        if (process.env.CASTLE_SAVE_STAGE_TELEMETRY === '1') {
+            console.log(`${SAVE_COVER_SELECTION_TELEMETRY_PREFIX}${JSON.stringify({
+                event: 'castle_web_save_cover_selected',
+                outcome: selected.outcome,
+                capture_outcome: selected.captureOutcome,
+                duration_ms: selected.durationMs,
+            })}`);
+        }
+        if (selected.outcome === 'remote' || selected.outcome === 'local_browser')
             console.log('Captured a cover from the running deck.');
-        else if (fs.existsSync(coverPath))
+        else if (selected.outcome === 'editor')
             console.log('Using the cover captured in the editor.');
-        if (!fs.existsSync(coverPath))
+        if (!selected.path)
             return null;
-        const base64 = fs.readFileSync(coverPath).toString('base64');
+        const base64 = fs.readFileSync(selected.path).toString('base64');
         const file = await api.uploadBase64(base64, COVER_FILE);
         return file?.fileId ?? null;
     }
@@ -411,6 +369,15 @@ export async function saveDeck(dir, opts = {}) {
         else if (code === 'DECK_INVALID_PERMISSIONS') {
             console.error('You do not have permission to save this deck.');
         }
+        else if (code === 'DECK_DELETED') {
+            // The deck this workspace points at was deleted somewhere else -- the app,
+            // the cloud editor, another machine. The server refuses the write rather
+            // than publishing into a deck nobody can reach, so say what happened and
+            // what recovers the code, which is still here and untouched.
+            console.error(`This deck was deleted (${castleJson?.deckId}), so it can no longer be saved to.\n` +
+                'Your files are unchanged. To publish them as a new deck, remove the ' +
+                '"deckId" and "cardId" fields from castle.json and save again.');
+        }
         else {
             throw e;
         }

package/dist/saveCover.d.ts

@@ -0,0 +1,18 @@
+export type SaveCoverOutcome = 'remote' | 'local_browser' | 'editor' | 'none';
+export interface SaveCoverSelection {
+    outcome: SaveCoverOutcome;
+    captureOutcome: 'succeeded' | 'timed_out' | 'capture_failed' | 'not_attempted';
+    path?: string;
+    durationMs: number;
+}
+export interface SaveCoverOptions {
+    totalBudgetMs?: number;
+    fetch?: typeof globalThis.fetch;
+    now?: () => number;
+    onProgress?: (message: string) => void;
+}
+export declare function runningServeUrl(projectDir: string, options?: Pick<SaveCoverOptions, 'fetch'> & {
+    signal?: AbortSignal;
+}): Promise<string | null>;
+/** Select exactly the automatic cover that save-deck would upload, without uploading it. */
+export declare function selectSaveCover(projectDir: string, options?: SaveCoverOptions): Promise<SaveCoverSelection>;

package/dist/saveCover.js

@@ -0,0 +1,61 @@
+import fs from 'fs';
+import path from 'path';
+import { COVER_FILE } from './localPaths.js';
+import { contentGrantFromBrowserUrl } from './native/playtest-remote.js';
+export async function runningServeUrl(projectDir, options = {}) {
+    try {
+        const raw = fs.readFileSync(path.join(projectDir, '.castle', 'serve.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        const port = parsed.port;
+        if (process.env.CASTLE_SANDBOX_ID && typeof port === 'number') {
+            try {
+                const response = await (options.fetch ?? globalThis.fetch)(`http://localhost:${port}/__castle/browser-content-grant`, { signal: options.signal ? AbortSignal.any([AbortSignal.timeout(2_000), options.signal]) : AbortSignal.timeout(2_000) });
+                const body = (await response.json());
+                if (response.ok && typeof body.url === 'string')
+                    return body.url;
+            }
+            catch {
+                // The serve metadata below remains a valid local fallback.
+            }
+        }
+        if (typeof parsed.contentPlayUrl === 'string')
+            return parsed.contentPlayUrl;
+        return typeof port === 'number' ? `http://localhost:${port}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Select exactly the automatic cover that save-deck would upload, without uploading it. */
+export async function selectSaveCover(projectDir, options = {}) {
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    const totalBudgetMs = options.totalBudgetMs ?? 15_000;
+    const deadlineMs = startedAt + totalBudgetMs;
+    const signal = AbortSignal.timeout(Math.max(1, totalBudgetMs));
+    const serveUrl = await runningServeUrl(projectDir, { ...options, signal });
+    const outPath = path.join(projectDir, '.castle', 'headless-cover.png');
+    const isRemote = Boolean(serveUrl && contentGrantFromBrowserUrl(serveUrl));
+    let captureOutcome = 'not_attempted';
+    // If cloud grant discovery consumed the caller budget, do not reinterpret its localhost
+    // metadata fallback as permission to start a new 60-second local-browser attempt.
+    if (serveUrl && !signal.aborted) {
+        const { captureCoverHeadless } = await import('./headlessCover.js');
+        const result = await captureCoverHeadless({
+            serveUrl,
+            outPath,
+            onProgress: options.onProgress,
+            ...(isRemote ? { remoteBudgetMs: Math.max(1, deadlineMs - now()), signal } : {}),
+        });
+        captureOutcome = result.outcome ?? (result.ok ? 'succeeded' : 'capture_failed');
+        if (result.ok && fs.existsSync(outPath)) {
+            return { outcome: isRemote ? 'remote' : 'local_browser', captureOutcome: 'succeeded', path: outPath, durationMs: Math.max(0, now() - startedAt) };
+        }
+    }
+    if (process.env.CASTLE_SANDBOX_ID && signal.aborted)
+        captureOutcome = 'timed_out';
+    const localPath = path.join(projectDir, COVER_FILE);
+    return fs.existsSync(localPath)
+        ? { outcome: 'editor', captureOutcome, path: localPath, durationMs: Math.max(0, now() - startedAt) }
+        : { outcome: 'none', captureOutcome, durationMs: Math.max(0, now() - startedAt) };
+}

package/dist/serve.js

@@ -762,16 +762,25 @@ export async function serve(dir, options = {}) {
             : options.host === '::'
                 ? '::1'
                 : options.host;
-    // Content origins follow --host: a serve bound to a tailnet/LAN address is
-    // being viewed from another device, where loopback is that device's own.
-    const contentBindHost = !options.host ||
+    // Content proxies must listen where a remote browser can reach them. Binding
+    // the shell to 0.0.0.0 / :: means a phone on LAN/tailnet opens the shell; its
+    // content iframes need those same interfaces — the phone's 127.0.0.1 is itself.
+    const contentListenHost = options.host === '0.0.0.0' || options.host === '::'
+        ? options.host
+        : !options.host || options.host === 'localhost'
+            ? '127.0.0.1'
+            : options.host;
+    // Playtest / serve.json still advertise loopback: Chromium on this machine
+    // cannot navigate to 0.0.0.0, and same-machine Safari keeps the prior origins.
+    // Remote browsers get the Host they used via ServeSecurity.contentOrigins.
+    const contentAdvertiseHost = !options.host ||
         options.host === 'localhost' ||
         options.host === '0.0.0.0' ||
         options.host === '::'
         ? '127.0.0.1'
         : options.host;
-    security.setLocalContentHost(contentBindHost);
-    const localContentServers = await startLocalContentServers(contentBindHost, upstreamHost, port, security, new Set([port]));
+    security.setLocalContentHost(contentAdvertiseHost);
+    const localContentServers = await startLocalContentServers(contentListenHost, upstreamHost, port, security, new Set([port]));
     process.on('exit', () => {
         for (const server of localContentServers)
             server.close();
@@ -1318,6 +1327,10 @@ function trustedBridgeContentOrigin(security, request, role, value) {
         return null;
     if (origin === security.localContentOrigin(role) || origin === request.headers.origin)
         return origin;
+    // Phone / LAN / tailnet: contentOrigins remints against the shell Host header.
+    const expected = security.contentOrigins(request)[role === 'edit' ? 'editOrigin' : 'playOrigin'];
+    if (origin === expected)
+        return origin;
     const url = new URL(origin);
     const synthetic = {
         headers: { ...request.headers, host: url.host },

package/dist/serveSecurity.d.ts

@@ -50,7 +50,17 @@ export declare class ServeSecurity {
         editOrigin: string;
         playOrigin: string;
     };
-    localContentOrigin(role: ContentRole): string;
+    /**
+     * Origin a browser should use for a local content role.
+     *
+     * When the shell was opened via a LAN / tailnet hostname (or any non-loopback
+     * Host the serve already accepted), content iframes must use that same host —
+     * `127.0.0.1` is the *phone's* loopback, not the machine running the serve.
+     * Loopback / wildcard request hosts keep the advertised localContentHost
+     * (playtest and same-machine Safari).
+     */
+    localContentOrigin(role: ContentRole, requestHost?: string): string;
+    private contentHostForBrowser;
     /** A short-lived play URL for one shared-browser admission attempt. */
     browserContentOrigin(role?: ContentRole): string | null;
     localContentProxyHeaders(role: ContentRole): Record<string, string>;

package/dist/serveSecurity.js

@@ -41,6 +41,20 @@ function hostWithoutPort(host) {
         return host.slice(0, host.indexOf(']') + 1).toLowerCase();
     return host.split(':')[0].toLowerCase();
 }
+/** Strip brackets so callers can compare / classify the bare hostname. */
+function bareHostname(host) {
+    const h = hostWithoutPort(host).toLowerCase();
+    return h.startsWith('[') && h.endsWith(']') ? h.slice(1, -1) : h;
+}
+/** IPv6 literals need brackets in an origin URL. */
+function formatHostForOrigin(host) {
+    const bare = bareHostname(host);
+    return bare.includes(':') ? `[${bare}]` : bare;
+}
+function isLoopbackHostname(host) {
+    const bare = bareHostname(host);
+    return bare === 'localhost' || bare === '127.0.0.1' || bare === '::1';
+}
 function requestOrigin(req) {
     const forwarded = req.headers['x-forwarded-proto'];
     const protocol = typeof forwarded === 'string' ? forwarded.split(',')[0] : 'http';
@@ -80,7 +94,8 @@ export class ServeSecurity {
             throw new Error('edit and play content ports must be distinct');
         this.localContentPorts = ports;
     }
-    // The host a browser should use to reach deck content; see contentBindHost.
+    // Loopback host advertised to same-machine consumers (playtest, serve.json).
+    // Remote browsers get the Host they used; see localContentOrigin(role, host).
     setLocalContentHost(host) {
         this.localContentHost = host;
     }
@@ -276,17 +291,36 @@ window.fetch=function(input,init){
             // Safari on macOS 15 asks DNS to resolve `*.localhost`, where it fails.
             // Dedicated loopback ports are still distinct browser origins and need no DNS.
             if (!cloud || !contentDomain)
-                return this.localContentOrigin(role);
+                return this.localContentOrigin(role, host);
             const label = this.mintContentLabel(role, sandboxId, expiresAtSeconds);
             return `https://${label}.${contentDomain}`;
         };
         return { editOrigin: originFor('edit'), playOrigin: originFor('play') };
     }
-    localContentOrigin(role) {
+    /**
+     * Origin a browser should use for a local content role.
+     *
+     * When the shell was opened via a LAN / tailnet hostname (or any non-loopback
+     * Host the serve already accepted), content iframes must use that same host —
+     * `127.0.0.1` is the *phone's* loopback, not the machine running the serve.
+     * Loopback / wildcard request hosts keep the advertised localContentHost
+     * (playtest and same-machine Safari).
+     */
+    localContentOrigin(role, requestHost) {
         const port = this.localContentPorts?.[role];
         if (!port)
             throw new Error('local content ports are not configured');
-        return `http://${this.localContentHost}:${port}`;
+        const host = this.contentHostForBrowser(requestHost);
+        return `http://${formatHostForOrigin(host)}:${port}`;
+    }
+    contentHostForBrowser(requestHost) {
+        if (!requestHost)
+            return this.localContentHost;
+        const bare = bareHostname(requestHost);
+        if (!bare || bare === '0.0.0.0' || bare === '::' || isLoopbackHostname(bare)) {
+            return this.localContentHost;
+        }
+        return bare;
     }
     /** A short-lived play URL for one shared-browser admission attempt. */
     browserContentOrigin(role = 'play') {