castle-web-cli 0.4.87 → 0.4.88

package/dist/agent.js

@@ -139,12 +139,19 @@ function normalizeProviderTier(value) {
         return null;
     return trimmed;
 }
-// OpenRouter's Anthropic-compatible endpoint (confirmed current, 2026: it
-// accepts the standard Anthropic Messages API shape -- text/tool-use/
-// extended-thinking -- for ANY OpenRouter model slug, not just Anthropic
-// ones). Using it directly means claude CLI's OWN stream-json + tool loop
-// talks to OpenRouter with zero translation layer -- no proxy needed.
-const OPENROUTER_BASE_URL = "https://openrouter.ai/api";
+// Base for OpenRouter's Anthropic-compatible endpoint (confirmed current, 2026: it
+// accepts the standard Anthropic Messages API shape -- text/tool-use/extended-thinking
+// -- for ANY OpenRouter model slug, not just Anthropic ones), which the claude CLI
+// appends /v1/messages to -- so its OWN stream-json + tool loop talks to OpenRouter with
+// zero translation layer.
+//
+// In a Castle sandbox the host injects OPENROUTER_BASE_URL (…/api/v1) pointing at the
+// per-host llm-proxy (which holds the real key and meters usage); use its origin, dropping
+// the /v1 the CLI re-adds. Otherwise openrouter.ai directly.
+function openrouterAnthropicBase() {
+    const injected = process.env.OPENROUTER_BASE_URL;
+    return injected ? injected.replace(/\/v1\/?$/, "") : "https://openrouter.ai/api";
+}
 // Anthropic credential sources the claude CLI will fall back to on its own.
 // This env points the CLI at a THIRD PARTY, so every one of these has to be
 // cleared or that third party receives the user's Anthropic credential. Note
@@ -192,7 +199,7 @@ function envForOpenrouterSpawn(apiKey) {
     const env = { ...process.env };
     for (const name of ANTHROPIC_CREDENTIAL_ENV)
         delete env[name];
-    env.ANTHROPIC_BASE_URL = OPENROUTER_BASE_URL;
+    env.ANTHROPIC_BASE_URL = openrouterAnthropicBase();
     env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1";
     env.ANTHROPIC_AUTH_TOKEN = apiKey;
     return env;
@@ -733,20 +740,48 @@ const BACKEND_KEY_ENV = {
 };
 // cursor-agent rewrites ~/.config/cursor/auth.json on every successful run,
 // including Castle's own CURSOR_API_KEY runs -- so the file existing does NOT
-// mean a user logged in. A real login (OAuth, or a tester's own key) overwrites
-// it and drops Castle's apiKey; a file whose apiKey is still Castle's key is just
-// our cache. Treating that cache as a login would suppress the injected key, and
-// once its ~60-min token expires cursor-agent (no headless refresh) fails auth.
+// mean a user logged in. Distinguish by the apiKey field: a real login is OAuth,
+// which drops apiKey and leaves only session tokens; any auth.json that still
+// carries an apiKey is an env-key cache cursor wrote from an injected key --
+// OURS, including a PREVIOUS key after a rotation. Treating that cache as a login
+// suppresses the injected key and drops cursor into the stale (dead) session.
+//
+// An earlier apiKey === castleKeys().CURSOR_API_KEY comparison misfired on a key
+// switch: the stale cache holds the OLD key, reads as "!= current" => "user
+// login" => key withheld => auth fails until auth.json is deleted by hand.
+// Deferring only on OAuth is rotation-proof. The cost: a tester's own-API-key
+// login is no longer distinguishable from our stale cache, so it is not deferred
+// to -- OAuth login still is (the common bypass path).
+function cursorAuthPath(home) {
+    return path.join(home, ".config", "cursor", "auth.json");
+}
 function cursorHasUserLogin(home) {
-    const authPath = path.join(home, ".config", "cursor", "auth.json");
     try {
-        const auth = JSON.parse(fs.readFileSync(authPath, "utf8"));
-        return auth.apiKey !== castleKeys().CURSOR_API_KEY;
+        const auth = JSON.parse(fs.readFileSync(cursorAuthPath(home), "utf8"));
+        return !auth.apiKey && !!auth.accessToken;
     }
     catch {
         return false;
     }
 }
+// When we inject Castle's key, any auth.json cursor cached from a DIFFERENT key
+// -- a rotated-out old key, or a tester's own key we've chosen to override -- is
+// dead weight: cursor re-auths from the injected env key and ignores it. Leaving
+// it means a stale API key sits on the sandbox fs, so drop it and keep only the
+// live key cached. Best-effort; an absent file is the normal case. An OAuth login
+// (no apiKey field) is never reached here -- that path withholds the key instead.
+function purgeStaleCursorAuth(home, injectedKey) {
+    try {
+        const authPath = cursorAuthPath(home);
+        const auth = JSON.parse(fs.readFileSync(authPath, "utf8"));
+        if (auth.apiKey && auth.apiKey !== injectedKey) {
+            fs.rmSync(authPath, { force: true });
+        }
+    }
+    catch {
+        // no auth.json, or unreadable/unparseable -- nothing to purge
+    }
+}
 // True when the user has their OWN saved auth for this backend -- a login that we
 // should defer to (and bill to them) instead of injecting Castle's key.
 //
@@ -782,10 +817,14 @@ function envForAgentSpawn(backend) {
     }
     else {
         const val = castleKeys()[keyName] ?? process.env[keyName];
-        if (val)
+        if (val) {
             env[keyName] = val;
-        else
+            if (backend === "cursor")
+                purgeStaleCursorAuth(os.homedir(), val);
+        }
+        else {
             delete env[keyName];
+        }
     }
     return env;
 }

package/dist/get-deck.d.ts

@@ -1,3 +1,4 @@
+export declare function extractTarball(archivePath: string, targetDir: string): Promise<void>;
 export declare function getDeck(dir: string, options?: {
     deckId?: string;
 }): Promise<void>;

package/dist/get-deck.js

@@ -10,7 +10,7 @@ function readCastleJson(dir) {
         return null;
     return JSON.parse(fs.readFileSync(p, 'utf-8'));
 }
-function extractTarball(archivePath, targetDir) {
+export function extractTarball(archivePath, targetDir) {
     return new Promise((resolve, reject) => {
         const child = spawn('tar', ['-xzf', archivePath, '-C', targetDir], {
             stdio: ['ignore', 'inherit', 'pipe'],

package/dist/index.js

@@ -6,6 +6,8 @@ import { serve } from './serve.js';
 import { saveDeck } from './save-deck.js';
 import { getDeck } from './get-deck.js';
 import { init } from './init.js';
+import { install } from './install.js';
+import { pull } from './pull.js';
 import { connectWS, savePreviewImage, savePreviewIfNeeded, takeScreenshot } from './preview.js';
 const args = process.argv.slice(2);
 const command = args[0];
@@ -64,6 +66,8 @@ function usage() {
   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]
+  castle-web pull [dir] [--deck-id ID] [--force]
+  castle-web install [dir]
   castle-web login
 
 Kits:
@@ -117,6 +121,17 @@ async function main() {
             await getDeck(dir, { deckId });
             break;
         }
+        case 'pull': {
+            await pull(findPositionalDir(), {
+                deckId: getFlagValue('--deck-id'),
+                force: hasFlag('--force'),
+            });
+            break;
+        }
+        case 'install': {
+            install(findPositionalDir());
+            break;
+        }
         case 'restart': {
             const dir = findPositionalDir();
             const wsPort = getWsPort(dir);

package/dist/init.js

@@ -1,7 +1,7 @@
-import { execSync } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
 import { COMMON_INSTRUCTIONS } from "./commonInstructions.js";
+import { installDeps } from "./install.js";
 import { getCliEntryPath, getKitsDir, getRepoRoot, getSdkPackagePath, toPosixPath, } from "./localPaths.js";
 import { serve } from "./serve.js";
 const INDEX_HTML = `<!DOCTYPE html>
@@ -266,56 +266,6 @@ function scaffoldFromKit(kit, projectDir) {
     appendCommonInstructions(projectDir);
     ensureAgentsSymlink(projectDir);
 }
-function hasPnpm() {
-    try {
-        execSync("pnpm --version", { stdio: "ignore" });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-// Install the scaffolded deck's deps. Prefer pnpm -- in the e2b template a pnpm
-// store is baked in, so this is near-instant (hardlinks from the store, no
-// download). Fall back to npm when pnpm isn't on PATH (e.g. a laptop that never
-// installed it). --prefer-offline uses the store/cache first; --ignore-scripts
-// skips dep build scripts (pnpm 10+ gates them and exits non-zero otherwise,
-// and the deck's deps are all prebuilt pure JS that don't need them). `frozen`
-// installs straight from the shipped lockfile (skips resolution -> no network,
-// fast + deterministic); used in published mode where the kit lockfile matches.
-function installDeps(projectDir, frozen) {
-    if (hasPnpm()) {
-        console.log("Installing deps (pnpm)...");
-        const frozenFlag = frozen ? "--frozen-lockfile " : "";
-        try {
-            execSync(`pnpm install ${frozenFlag}--prefer-offline --ignore-scripts`, {
-                cwd: projectDir,
-                stdio: "inherit",
-            });
-        }
-        catch (err) {
-            if (!frozen)
-                throw err;
-            // A frozen install hard-fails when the shipped kit lockfile has drifted
-            // from the scaffold's package.json (e.g. the sdk version bumped but the
-            // kit's pnpm-lock.yaml wasn't regenerated). Rather than leave the deck
-            // with no node_modules, retry with resolution allowed -- a little slower
-            // (re-resolves + may fetch), but self-heals the drift instead of breaking.
-            console.warn("Frozen install failed; retrying with resolution (kit lockfile drift?)...");
-            execSync("pnpm install --prefer-offline --ignore-scripts", {
-                cwd: projectDir,
-                stdio: "inherit",
-            });
-        }
-    }
-    else {
-        console.log("Installing deps (npm)...");
-        execSync("npm install --no-audit --no-fund --loglevel=error", {
-            cwd: projectDir,
-            stdio: "inherit",
-        });
-    }
-}
 export async function init(dir, opts = {}) {
     const projectDir = path.resolve(dir);
     if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {

package/dist/install.d.ts

@@ -0,0 +1,2 @@
+export declare function installDeps(projectDir: string, frozen: boolean): void;
+export declare function install(dir: string): void;

package/dist/install.js

@@ -0,0 +1,64 @@
+import { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+function hasPnpm() {
+    try {
+        execSync("pnpm --version", { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Install a deck's deps. Prefer pnpm -- in the e2b template a pnpm store is baked
+// in, so this is near-instant (hardlinks from the store, no download). Fall back to
+// npm when pnpm isn't on PATH (e.g. a laptop that never installed it).
+// --prefer-offline uses the store/cache first; --ignore-scripts skips dep build
+// scripts (pnpm 10+ gates them and exits non-zero otherwise, and the deck's deps are
+// all prebuilt pure JS that don't need them). `frozen` installs straight from the
+// shipped lockfile (skips resolution -> no network, fast + deterministic).
+export function installDeps(projectDir, frozen) {
+    if (hasPnpm()) {
+        console.log("Installing deps (pnpm)...");
+        const frozenFlag = frozen ? "--frozen-lockfile " : "";
+        try {
+            execSync(`pnpm install ${frozenFlag}--prefer-offline --ignore-scripts`, {
+                cwd: projectDir,
+                stdio: "inherit",
+            });
+        }
+        catch (err) {
+            if (!frozen)
+                throw err;
+            // A frozen install hard-fails when the lockfile has drifted from
+            // package.json (e.g. the sdk version bumped but the kit's pnpm-lock.yaml
+            // wasn't regenerated). Rather than leave the deck with no node_modules,
+            // retry with resolution allowed -- a little slower (re-resolves + may
+            // fetch), but self-heals the drift instead of breaking.
+            console.warn("Frozen install failed; retrying with resolution (lockfile drift?)...");
+            execSync("pnpm install --prefer-offline --ignore-scripts", {
+                cwd: projectDir,
+                stdio: "inherit",
+            });
+        }
+    }
+    else {
+        console.log("Installing deps (npm)...");
+        execSync("npm install --no-audit --no-fund --loglevel=error", {
+            cwd: projectDir,
+            stdio: "inherit",
+        });
+    }
+}
+// `castle-web install <dir>`: put node_modules in place for a deck that already has
+// its source -- one fetched with `get-deck`, or one whose node_modules was dropped
+// (the cloud hosts treat it as regenerable and don't snapshot it).
+export function install(dir) {
+    const projectDir = path.resolve(dir);
+    if (!fs.existsSync(path.join(projectDir, "package.json"))) {
+        console.error(`No package.json in ${projectDir}.`);
+        process.exit(1);
+    }
+    installDeps(projectDir, fs.existsSync(path.join(projectDir, "pnpm-lock.yaml")));
+    console.log(`Installed deps in ${projectDir}`);
+}

package/dist/native/openrouter.js

@@ -20,7 +20,10 @@ import { failureForStatus } from "../agent-failures.js";
 // to a module-level const) so a test process that imports this module once
 // can still point successive runAgentNative calls at different fake servers.
 function openrouterUrl() {
-    return process.env.CASTLE_OPENROUTER_URL || "https://openrouter.ai/api/v1/chat/completions";
+    // In a Castle sandbox the host injects OPENROUTER_BASE_URL pointing at the per-host
+    // llm-proxy (holds the real key, meters usage); otherwise talk to openrouter.ai directly.
+    return (process.env.CASTLE_OPENROUTER_URL ||
+        `${process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1"}/chat/completions`);
 }
 const DEFAULT_MAX_RETRIES = 2; // -> 3 total connect attempts
 const RETRY_BASE_MS = 500;

package/dist/openrouter-catalog.js

@@ -28,8 +28,12 @@ function modelsUrl() {
     return (process.env.CASTLE_OPENROUTER_MODELS_URL ??
         "https://openrouter.ai/api/v1/models");
 }
+// The key check sends the credential, so in a Castle sandbox it goes through the llm-proxy
+// (OPENROUTER_BASE_URL) — validating the real key the proxy swaps in. modelsUrl above is a
+// public GET and stays on openrouter.ai (the proxy requires a token).
 function keyUrl() {
-    return process.env.CASTLE_OPENROUTER_KEY_URL ?? "https://openrouter.ai/api/v1/key";
+    return (process.env.CASTLE_OPENROUTER_KEY_URL ??
+        `${process.env.OPENROUTER_BASE_URL || "https://openrouter.ai/api/v1"}/key`);
 }
 function cachePath() {
     return (process.env.CASTLE_OPENROUTER_CATALOG_CACHE ??

package/dist/pull.d.ts

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

package/dist/pull.js

@@ -0,0 +1,115 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { nanoid } from 'nanoid';
+import * as api from './api.js';
+import { extractTarball } from './get-deck.js';
+import { installDeps } from './install.js';
+import { archiveSource } from './save-deck.js';
+// Everything else in the deck dir is source and gets replaced wholesale, so that a
+// file deleted upstream actually disappears here -- untarring over the old tree
+// would leave it behind. These three survive: node_modules is expensive and gets
+// reinstalled against the new lockfile anyway, .castle is this machine's runtime
+// state (serve ports, logs, the agent's ledger), and .git is the user's own history.
+const KEEP = ['node_modules', '.castle', '.git'];
+function readCastleJson(dir) {
+    const p = path.join(dir, 'castle.json');
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Newest mtime across the deck's source, i.e. when this copy was last edited.
+function newestSourceMtime(dir) {
+    let newest = 0;
+    const walk = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            if (current === dir && KEEP.includes(entry.name))
+                continue;
+            const full = path.join(current, entry.name);
+            let stat;
+            try {
+                stat = fs.statSync(full);
+            }
+            catch {
+                continue; // raced deletion / broken symlink
+            }
+            newest = Math.max(newest, stat.mtimeMs);
+            if (entry.isDirectory())
+                walk(full);
+        }
+    };
+    walk(dir);
+    return newest;
+}
+function backupSource(projectDir, archive) {
+    const file = path.join(os.tmpdir(), `castle-pull-backup-${nanoid(8)}.tar.gz`);
+    fs.writeFileSync(file, archive);
+    return file;
+}
+// Replace a deck's source with the latest saved on the server. Where `get-deck`
+// fetches a deck into a directory, this refreshes one that's already there --
+// e.g. after edits made on another machine (or another sandbox host) that this
+// copy predates.
+export async function pull(dir, options = {}) {
+    const projectDir = path.resolve(dir);
+    if (!fs.existsSync(projectDir)) {
+        console.error(`No deck at ${projectDir}. Use \`castle-web get-deck\` to fetch a new one.`);
+        process.exit(1);
+    }
+    const deckId = options.deckId ?? readCastleJson(projectDir)?.deckId;
+    if (!deckId) {
+        console.error(`No deckId. Either pass --deck-id <id> or run against a directory whose castle.json has one.`);
+        process.exit(1);
+    }
+    const source = await api.webDeckSource(deckId);
+    if (!source) {
+        console.error(`No source archive on server for deck ${deckId}. Run \`castle-web save-deck\` first.`);
+        process.exit(1);
+    }
+    // Local edits newer than what's on the server would be destroyed by the replace,
+    // and they're the copy worth keeping -- stop rather than guess. (A pull leaves
+    // the archive's own mtimes in place, so pulling twice doesn't trip this.)
+    const serverMs = Date.parse(source.updatedAt);
+    const localMs = newestSourceMtime(projectDir);
+    if (!options.force && Number.isFinite(serverMs) && localMs > serverMs) {
+        console.error(`This copy has changes newer than the saved deck (local ${new Date(localMs).toISOString()} > server ${source.updatedAt}).`);
+        console.error(`Run \`castle-web save-deck\` to keep them, or \`--force\` to discard them.`);
+        process.exit(1);
+    }
+    // Everything that can fail over the network happens before anything is deleted.
+    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 backup = backupSource(projectDir, await archiveSource(projectDir));
+    console.log(`Backed up the current source to ${backup}`);
+    for (const entry of fs.readdirSync(projectDir)) {
+        if (KEEP.includes(entry))
+            continue;
+        fs.rmSync(path.join(projectDir, entry), { recursive: true, force: true });
+    }
+    const tmpFile = path.join(os.tmpdir(), `castle-pull-${nanoid(8)}.tar.gz`);
+    fs.writeFileSync(tmpFile, buf);
+    try {
+        await extractTarball(tmpFile, projectDir);
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            /* nothing to clean */
+        }
+    }
+    console.log(`Updated ${projectDir}`);
+    // The pulled tree can want different deps than the one just deleted.
+    installDeps(projectDir, fs.existsSync(path.join(projectDir, 'pnpm-lock.yaml')));
+}

package/package.json

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