castle-web-cli 0.4.106 → 0.4.108

package/dist/cli-shim-env.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli-shim-env.js

@@ -0,0 +1,13 @@
+// Printed for the editor terminal's shims to eval: the environment this
+// particular run of this particular CLI should have, plus the real binary to
+// exec (see installCliShims in byo-auth.ts for why the decision can't live in
+// the shell's own environment).
+//
+// argv is `<shimDir> <cli> [the run's own arguments...]`.
+import { ensureClaudeOnboarded, shimEnvScript } from "./byo-auth.js";
+const [shimDir = "", cli = "", ...args] = process.argv.slice(2);
+// Its own call rather than a side effect of building the script: this WRITES,
+// and shimEnvScript is read-only by contract.
+if (cli === "claude")
+    ensureClaudeOnboarded();
+process.stdout.write(shimEnvScript(cli, process.env, shimDir, args));

package/dist/get-deck.js

@@ -5,6 +5,7 @@ import { nanoid } from 'nanoid';
 import * as api from './api.js';
 import { normalizeDeckPackageJson } from './normalize.js';
 import { archiveSource, runTar, SOURCE_ARCHIVE_EXCLUDES } from './save-deck.js';
+import { readCastleJson } from './castleJson.js';
 // Refreshing a deck already in the target replaces its source, so a file deleted
 // upstream actually disappears here -- untarring over the old tree would leave it
 // behind. What survives is exactly what the source archive doesn't carry, and it
@@ -12,17 +13,6 @@ import { archiveSource, runTar, SOURCE_ARCHIVE_EXCLUDES } from './save-deck.js';
 // below (which is that same archive), so deleting one destroys it outright. They're
 // all machine-local anyway -- deps, build output, .castle runtime state, .git.
 const KEEP = SOURCE_ARCHIVE_EXCLUDES;
-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;
-    }
-}
 // Whether the target already holds a deck, as opposed to being new, empty, or
 // holding only the dirs a refresh preserves.
 function hasSource(dir) {

package/dist/ide.js

@@ -15,7 +15,7 @@ import headlessPkg from "@xterm/headless";
 import { SerializeAddon } from "@xterm/addon-serialize";
 import { WebSocketServer } from "ws";
 import { IMPORTS_DIR, importStatuses, updateImport } from "./imports.js";
-import { envForUserShell } from "./byo-auth.js";
+import { envForUserShell, installCliShims } from "./byo-auth.js";
 const HeadlessTerminal = headlessPkg.Terminal;
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
 // The bundled shell app (vite build output). `/` serves its index.html and
@@ -315,7 +315,7 @@ function readRequestBody(req) {
         req.on("error", reject);
     });
 }
-function handleFilesWrite(deckDir, req, res) {
+function withJsonBody(req, res, handler) {
     void (async () => {
         let body;
         try {
@@ -324,24 +324,37 @@ function handleFilesWrite(deckDir, req, res) {
         catch {
             return sendJson(res, 400, { error: "Invalid JSON body." });
         }
+        handler(body);
+    })();
+}
+// The shape every single-path mutation handler starts with: parse the body,
+// resolve `path` against the deck, and reject anything outside it.
+function withMutationPath(deckDir, req, res, handler) {
+    withJsonBody(req, res, (body) => {
         const resolved = resolveDeckPath(deckDir, body.path, { mutation: true });
         if (!resolved.ok)
             return sendJson(res, 400, { error: resolved.error });
+        handler(resolved, body);
+    });
+}
+function sendFailure(res, action, rel, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    sendJson(res, 500, { error: `Could not ${action} ${rel}: ${message}` });
+}
+function handleFilesWrite(deckDir, req, res) {
+    withMutationPath(deckDir, req, res, (target, body) => {
         if (typeof body.contents !== "string") {
             return sendJson(res, 400, { error: "File contents must be a string." });
         }
         try {
-            fs.mkdirSync(path.dirname(resolved.abs), { recursive: true });
-            fs.writeFileSync(resolved.abs, body.contents, "utf8");
-            sendJson(res, 200, { ok: true, path: resolved.rel });
+            fs.mkdirSync(path.dirname(target.abs), { recursive: true });
+            fs.writeFileSync(target.abs, body.contents, "utf8");
+            sendJson(res, 200, { ok: true, path: target.rel });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            sendJson(res, 500, {
-                error: `Could not write ${resolved.rel}: ${message}`,
-            });
+            sendFailure(res, "write", target.rel, err);
         }
-    })();
+    });
 }
 // Add `<rel>/**` to the deck's editor.visiblePaths so files created in a
 // newly-made folder show in the curated Files tree. Only touches a deck that is
@@ -378,29 +391,16 @@ function ensureVisiblePath(deckDir, rel) {
     }
 }
 function handleFilesMkdir(deckDir, req, res) {
-    void (async () => {
-        let body;
+    withMutationPath(deckDir, req, res, (target) => {
         try {
-            body = JSON.parse(await readRequestBody(req));
-        }
-        catch {
-            return sendJson(res, 400, { error: "Invalid JSON body." });
-        }
-        const resolved = resolveDeckPath(deckDir, body.path, { mutation: true });
-        if (!resolved.ok)
-            return sendJson(res, 400, { error: resolved.error });
-        try {
-            fs.mkdirSync(resolved.abs, { recursive: true });
+            fs.mkdirSync(target.abs, { recursive: true });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return sendJson(res, 500, {
-                error: `Could not create folder ${resolved.rel}: ${message}`,
-            });
+            return sendFailure(res, "create folder", target.rel, err);
         }
-        const visiblePathAdded = ensureVisiblePath(deckDir, resolved.rel);
-        sendJson(res, 200, { ok: true, path: resolved.rel, visiblePathAdded });
-    })();
+        const visiblePathAdded = ensureVisiblePath(deckDir, target.rel);
+        sendJson(res, 200, { ok: true, path: target.rel, visiblePathAdded });
+    });
 }
 // True when two paths resolve to the same underlying file (same inode+device) --
 // e.g. the source and target of a case-only rename on a case-insensitive FS.
@@ -415,14 +415,7 @@ function isSameFile(a, b) {
     }
 }
 function handleFilesRename(deckDir, req, res) {
-    void (async () => {
-        let body;
-        try {
-            body = JSON.parse(await readRequestBody(req));
-        }
-        catch {
-            return sendJson(res, 400, { error: "Invalid JSON body." });
-        }
+    withJsonBody(req, res, (body) => {
         const from = resolveDeckPath(deckDir, body.from, { mutation: true });
         if (!from.ok)
             return sendJson(res, 400, { error: from.error });
@@ -447,37 +440,23 @@ function handleFilesRename(deckDir, req, res) {
             sendJson(res, 200, { ok: true, path: to.rel });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            sendJson(res, 500, { error: `Could not rename ${from.rel}: ${message}` });
+            sendFailure(res, "rename", from.rel, err);
         }
-    })();
+    });
 }
 function handleFilesDelete(deckDir, req, res) {
-    void (async () => {
-        let body;
-        try {
-            body = JSON.parse(await readRequestBody(req));
-        }
-        catch {
-            return sendJson(res, 400, { error: "Invalid JSON body." });
-        }
-        const resolved = resolveDeckPath(deckDir, body.path, { mutation: true });
-        if (!resolved.ok)
-            return sendJson(res, 400, { error: resolved.error });
-        if (!fs.existsSync(resolved.abs)) {
-            return sendJson(res, 404, { error: `Not found: ${resolved.rel}` });
+    withMutationPath(deckDir, req, res, (target) => {
+        if (!fs.existsSync(target.abs)) {
+            return sendJson(res, 404, { error: `Not found: ${target.rel}` });
         }
         try {
-            fs.rmSync(resolved.abs, { recursive: true, force: true });
-            sendJson(res, 200, { ok: true, path: resolved.rel });
+            fs.rmSync(target.abs, { recursive: true, force: true });
+            sendJson(res, 200, { ok: true, path: target.rel });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            sendJson(res, 500, {
-                error: `Could not delete ${resolved.rel}: ${message}`,
-            });
+            sendFailure(res, "delete", target.rel, err);
         }
-    })();
+    });
 }
 // The builtin Files + code-editor backend: list / read / write deck files and
 // report kit-owned editor extensions. Paths are deck-relative; resolveDeckPath
@@ -611,7 +590,7 @@ function defaultShell() {
     }) ?? "/bin/sh";
     return { command, args: ["-l"] };
 }
-function ptyEnv() {
+function ptyEnv(shimDir) {
     const env = {
         ...envForUserShell(process.env),
         TERM: PTY_TERM,
@@ -623,6 +602,9 @@ function ptyEnv() {
     };
     delete env.NO_COLOR;
     delete env.NODE_DISABLE_COLORS;
+    if (shimDir) {
+        env.PATH = env.PATH ? `${shimDir}${path.delimiter}${env.PATH}` : shimDir;
+    }
     return env;
 }
 function clampSize(value, fallback) {
@@ -669,6 +651,7 @@ export function createIdeServer(opts) {
     let session = null;
     function spawnSession() {
         const { command, args } = defaultShell();
+        const shimDir = installCliShims(deckDir);
         const screen = new HeadlessTerminal({
             allowProposedApi: true,
             cols: INITIAL_COLS,
@@ -683,7 +666,7 @@ export function createIdeServer(opts) {
             cols: INITIAL_COLS,
             rows: INITIAL_ROWS,
             cwd: deckDir,
-            env: ptyEnv(),
+            env: ptyEnv(shimDir),
         });
         const s = {
             pty,

package/dist/imports.js

@@ -5,6 +5,7 @@ import * as api from './api.js';
 import { runTar } from './save-deck.js';
 import { normalizeDeckPackageJson } from './normalize.js';
 import { getKitsDir } from './localPaths.js';
+import { readCastleJsonOrThrow as readCastleJson, } from './castleJson.js';
 // Adding another deck as a dependency (`castle-web add-import`; removing one is a
 // later command). Deliberately NOT `get-deck`: that one
 // replaces THIS deck's own source from the server (and carries guards for the
@@ -24,17 +25,6 @@ import { getKitsDir } from './localPaths.js';
 // node_modules gets. That also means `get-deck` leaves an existing `imports/`
 // alone when it refreshes a deck.
 export const IMPORTS_DIR = 'imports';
-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 (e) {
-        throw new Error(`Could not read ${p}: ${e instanceof Error ? e.message : String(e)}`);
-    }
-}
 // Only the `imports` key is ours; everything else in castle.json (deck identity,
 // editor config) is preserved as-is.
 function writeImportPin(dir, alias, pin) {
@@ -88,47 +78,24 @@ function qualifiedAlias(meta, deckId) {
 //
 // The cost is that `imports/<alias>` can't be deleted until it's unlocked, which
 // is why every path in this file that replaces a dependency unlocks it first.
-function chmodTree(dir, fileMode, dirMode) {
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
-        return;
-    }
-    for (const entry of entries) {
-        const child = path.join(dir, entry.name);
-        if (entry.isDirectory())
-            chmodTree(child, fileMode, dirMode);
-        else {
-            try {
-                fs.chmodSync(child, fileMode);
-            }
-            catch {
-                /* a file we can't chmod is not worth failing the import over */
-            }
-        }
-    }
-    // The directory goes last: its contents have to be reachable while we walk it.
+// A file we can't chmod is not worth failing the import over, so every chmod
+// here is best-effort.
+function chmod(target, mode) {
     try {
-        fs.chmodSync(dir, dirMode);
+        fs.chmodSync(target, mode);
+        return true;
     }
     catch {
-        /* as above */
+        return false;
     }
 }
-export function lockImportTree(dir) {
-    chmodTree(dir, 0o444, 0o555);
-}
-// Restore write permission so the tree can be replaced or removed. Directories
-// first, or their contents are unreachable.
-function unlockImportTree(dir) {
-    try {
-        fs.chmodSync(dir, 0o755);
-    }
-    catch {
+// `dirFirst` is the one thing that differs between locking and unlocking, and it
+// has to: locking chmods a directory AFTER its contents (they must stay
+// reachable while we walk it), unlocking chmods it BEFORE (or the walk can't get
+// in at all -- so a failure there aborts this subtree).
+function chmodTree(dir, modes) {
+    if (modes.dirFirst && !chmod(dir, modes.dir))
         return;
-    }
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -139,16 +106,19 @@ function unlockImportTree(dir) {
     for (const entry of entries) {
         const child = path.join(dir, entry.name);
         if (entry.isDirectory())
-            unlockImportTree(child);
-        else {
-            try {
-                fs.chmodSync(child, 0o644);
-            }
-            catch {
-                /* best effort */
-            }
-        }
+            chmodTree(child, modes);
+        else
+            chmod(child, modes.file);
     }
+    if (!modes.dirFirst)
+        chmod(dir, modes.dir);
+}
+export function lockImportTree(dir) {
+    chmodTree(dir, { file: 0o444, dir: 0o555, dirFirst: false });
+}
+// Restore write permission so the tree can be replaced or removed.
+function unlockImportTree(dir) {
+    chmodTree(dir, { file: 0o644, dir: 0o755, dirFirst: true });
 }
 // An import's code runs from the IMPORTING deck's node_modules -- there is one
 // install at the deck root, and a dependency's own node_modules is neither
@@ -209,7 +179,7 @@ export function syncImportDependencies(deckDir) {
 // won't run until they are back. Rebuilding them from the pins is `install`'s
 // job, alongside node_modules.
 export async function restoreMissingImports(deckDir) {
-    const pins = (readCastleJson(deckDir)?.imports ?? {});
+    const pins = readCastleJson(deckDir)?.imports ?? {};
     const restored = [];
     for (const [alias, pin] of Object.entries(pins)) {
         const destDir = path.join(deckDir, IMPORTS_DIR, alias);
@@ -298,7 +268,7 @@ export async function importStatuses(deckDir) {
     const cached = statusCache.get(deckDir);
     if (cached && Date.now() - cached.at < STATUS_TTL_MS)
         return cached.value;
-    const pins = (readCastleJson(deckDir)?.imports ?? {});
+    const pins = readCastleJson(deckDir)?.imports ?? {};
     const value = await Promise.all(Object.entries(pins).map(async ([alias, pin]) => {
         const base = {
             alias,
@@ -386,12 +356,12 @@ async function placeImport(deckDir, alias, deckId, source, via) {
 // silently renamed, since renaming would break the refs of whoever named it.
 async function addTransitiveImports(deckDir, viaAlias, seen) {
     const viaDir = path.join(deckDir, IMPORTS_DIR, viaAlias);
-    const pins = (readCastleJson(viaDir)?.imports ?? {});
+    const pins = readCastleJson(viaDir)?.imports ?? {};
     const added = [];
     for (const [alias, pin] of Object.entries(pins)) {
         if (!pin?.deckId || seen.has(pin.deckId))
             continue;
-        const existing = (readCastleJson(deckDir)?.imports ?? {});
+        const existing = readCastleJson(deckDir)?.imports ?? {};
         const holder = existing[alias];
         if (holder && holder.deckId !== pin.deckId) {
             console.warn(`"${viaAlias}" wants ${pin.deckId} as "${alias}", which is already ${holder.deckId} here -- skipping; ` +
@@ -417,7 +387,7 @@ async function addTransitiveImports(deckDir, viaAlias, seen) {
 // Every deckId this deck already has, so a transitive walk doesn't refetch or
 // loop on a cycle.
 function importedDeckIds(deckDir) {
-    const pins = (readCastleJson(deckDir)?.imports ?? {});
+    const pins = readCastleJson(deckDir)?.imports ?? {};
     return new Set(Object.values(pins).map((p) => p?.deckId).filter((id) => !!id));
 }
 export async function addImport(dir, options = {}) {
@@ -468,7 +438,7 @@ export async function addImport(dir, options = {}) {
 // wasn't.
 export async function updateImport(dir, options = {}) {
     const deckDir = path.resolve(dir);
-    const pins = (readCastleJson(deckDir)?.imports ?? {});
+    const pins = readCastleJson(deckDir)?.imports ?? {};
     const aliases = options.alias ? [options.alias] : Object.keys(pins);
     if (aliases.length === 0) {
         console.log('This deck has no imports.');

package/dist/init.js

@@ -37,29 +37,16 @@ const DEFAULT_KIT = "physics-2d";
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
 const PUBLISHED_SDK_VERSION = "0.4.11";
-// Never copied into a fresh deck: build/dependency junk. castle.json IS copied
-// (the kit ships a config-only one with the editor layout / file filters), but
-// `scaffoldFromKit` strips any identity fields off it first -- a fresh deck has
-// no deckId until its first save-deck, which owns those fields.
 // 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";
+// Never copied into a deck's import: build/dependency junk.
 const KIT_COPY_EXCLUDE = new Set([
     "node_modules",
     ".castle",
     "dist",
     ".git",
 ]);
-// Identity fields owned by save-deck, never shipped in a kit's config-only
-// castle.json. Stripped from a copied castle.json (and absent from the bare
-// default) so a fresh deck has no deckId until its first save.
-const CASTLE_JSON_IDENTITY_FIELDS = [
-    "deckId",
-    "cardId",
-    "title",
-    "caption",
-    "visibility",
-];
 // The bare (`--kit none`) deck's default editor config: just the Files panel and
 // a Play panel. No file filtering -- a bare deck is hand-rolled, so the author
 // knows what's there; show everything for now.
@@ -70,22 +57,6 @@ const BARE_CASTLE_JSON = {
         visiblePaths: [],
     },
 };
-// Strip save-deck-owned identity fields from a copied kit castle.json, leaving
-// only its config (the editor block). No-op if the kit shipped no castle.json.
-function stripCastleJsonIdentity(projectDir) {
-    const castlePath = path.join(projectDir, "castle.json");
-    if (!fs.existsSync(castlePath))
-        return;
-    try {
-        const data = JSON.parse(fs.readFileSync(castlePath, "utf8"));
-        for (const field of CASTLE_JSON_IDENTITY_FIELDS)
-            delete data[field];
-        fs.writeFileSync(castlePath, JSON.stringify(data, null, 2) + "\n");
-    }
-    catch {
-        // kit shipped an unparseable castle.json -- leave it for the user to fix
-    }
-}
 // Resolve how a scaffolded deck should reference the sdk + cli. Both the bare
 // and kit scaffold paths go through here so they stay in sync.
 //   workspace mode (sdk/ sits next to cli/, i.e. running from a checkout):
@@ -354,7 +325,8 @@ function scaffoldFromKitImport(kit, projectDir) {
     });
     const kitConfig = readJsonFile(path.join(kitDir, "castle.json")) ?? {};
     const kitPkg = readJsonFile(path.join(kitDir, "package.json")) ?? {};
-    writeDeckIndexHtml(projectDir, alias, String(kitConfig.title ?? kit));
+    const title = typeof kitConfig.title === "string" ? kitConfig.title : kit;
+    writeDeckIndexHtml(projectDir, alias, title);
     writeStarterScene(projectDir, kitDir, alias);
     // 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
@@ -385,91 +357,6 @@ function scaffoldFromKitImport(kit, projectDir) {
     appendCommonInstructions(projectDir);
     lockImportTree(importDir);
 }
-function scaffoldFromKit(kit, projectDir) {
-    const kitDir = path.join(getKitsDir(), kit);
-    if (!fs.existsSync(kitDir) || !fs.statSync(kitDir).isDirectory()) {
-        console.error(`Kit "${kit}" not found at ${kitDir}.`);
-        console.error("Available kits:");
-        try {
-            const kits = fs
-                .readdirSync(getKitsDir())
-                .filter((name) => fs.statSync(path.join(getKitsDir(), name)).isDirectory());
-            if (kits.length)
-                for (const name of kits)
-                    console.error(`  ${name}`);
-            else
-                console.error("  (none)");
-        }
-        catch {
-            console.error("  (none — kits/ directory is missing)");
-        }
-        console.error("Or use `--kit none` for a bare code-only deck.");
-        process.exit(1);
-    }
-    fs.cpSync(kitDir, projectDir, {
-        recursive: true,
-        // Keep symlinks verbatim so the kit's AGENTS.md -> CLAUDE.md stays a link.
-        verbatimSymlinks: true,
-        filter: (src) => src === kitDir || !KIT_COPY_EXCLUDE.has(path.basename(src)),
-    });
-    // The kit ships a config-only castle.json (editor layout / file filters); keep
-    // its config but drop any identity fields so this fresh deck has no deckId
-    // until its first save-deck.
-    stripCastleJsonIdentity(projectDir);
-    // The kit's package.json carries the kit's name; rename it to the deck dir.
-    // Kit-relative refs to `../../sdk` and `../../cli/dist` only resolve when the
-    // deck lives at castle-experimental-web/decks/<name>/. Rewrite both to
-    // absolute paths so the scaffolded deck works anywhere -- including under
-    // /tmp where macOS's /tmp -> /private/tmp symlink breaks relative-path math.
-    const pkgPath = path.join(projectDir, "package.json");
-    if (fs.existsSync(pkgPath)) {
-        try {
-            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-            pkg.name = path.basename(projectDir);
-            // Local-dev paths (`file:../../sdk` / `node ../../cli/dist/index.js`) only
-            // work when the deck lives inside the castle-experimental-web workspace.
-            // For a deck scaffolded from a globally-installed castle-web, rewrite to
-            // the published packages instead. Same workspace-vs-published resolution
-            // the bare scaffold path uses.
-            const { workspaceMode, sdkRef, cliDistAbs, sdkPathPosix } = resolveScaffoldRefs();
-            if (pkg.dependencies &&
-                typeof pkg.dependencies["castle-web-sdk"] === "string" &&
-                pkg.dependencies["castle-web-sdk"].startsWith("file:")) {
-                pkg.dependencies["castle-web-sdk"] = sdkRef;
-            }
-            if (pkg.scripts) {
-                for (const k of Object.keys(pkg.scripts)) {
-                    if (typeof pkg.scripts[k] !== "string")
-                        continue;
-                    if (workspaceMode) {
-                        pkg.scripts[k] = pkg.scripts[k]
-                            .replace(/\.\.\/\.\.\/cli\/dist/g, cliDistAbs)
-                            .replace(/\.\.\/\.\.\/sdk/g, sdkPathPosix);
-                    }
-                    else {
-                        // Globally-installed: route through the `castle-web` binary on PATH.
-                        pkg.scripts[k] = pkg.scripts[k]
-                            .replace(/node\s+\.\.\/\.\.\/cli\/dist\/index\.js/g, "castle-web")
-                            .replace(/await import\((['"])\.\.\/\.\.\/cli\/dist\/bundle\.js\1\)/g, "await import('castle-web-cli/dist/bundle.js')")
-                            .replace(/\.\.\/\.\.\/sdk/g, "");
-                    }
-                }
-            }
-            fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-        }
-        catch {
-            // kit shipped an unparseable package.json — leave it for the user to fix
-        }
-    }
-    // Every deck needs a CLAUDE.md so coding agents know how castle-web works.
-    // Keep the kit's own if it ships one; otherwise generate from the upstream.
-    const claudePath = path.join(projectDir, "CLAUDE.md");
-    if (!fs.existsSync(claudePath)) {
-        fs.writeFileSync(claudePath, makeClaudeMd());
-    }
-    appendCommonInstructions(projectDir);
-    ensureAgentsSymlink(projectDir);
-}
 export async function init(dir, opts = {}) {
     const projectDir = path.resolve(dir);
     if (fs.existsSync(projectDir) && fs.readdirSync(projectDir).length > 0) {

package/dist/metering.d.ts

@@ -30,6 +30,13 @@ export declare function reportCursorRun(opts: {
     durationMs: number;
     ok: boolean;
 }): void;
+/**
+ * True when this serve runs inside a Castle sandbox -- i.e. the host injected the
+ * llm-proxy pair, which is what makes a run metered and limit-gated in the first
+ * place. Outside one there is no Castle budget being spent, so nothing to escape
+ * with a credential of your own; the CLIs just use whatever the host machine has.
+ */
+export declare function inCastleSandbox(): boolean;
 /** Mirrors `CastleBudgetResponse` in castle-sandboxes/shared. */
 export interface CastleBudget {
     usedMicros: number;

package/dist/metering.js

@@ -100,6 +100,15 @@ export function reportCursorRun(opts) {
         /* best-effort: metering must never surface in a finished run */
     });
 }
+/**
+ * True when this serve runs inside a Castle sandbox -- i.e. the host injected the
+ * llm-proxy pair, which is what makes a run metered and limit-gated in the first
+ * place. Outside one there is no Castle budget being spent, so nothing to escape
+ * with a credential of your own; the CLIs just use whatever the host machine has.
+ */
+export function inCastleSandbox() {
+    return Boolean(process.env.CASTLE_LLM_PROXY_URL && process.env.CASTLE_LLM_PROXY_TOKEN);
+}
 // Path on the proxy that reports this sandbox's daily budget. Must match
 // CASTLE_BUDGET_PATH in castle-sandboxes/shared/src/index.ts.
 const CASTLE_BUDGET_PATH = "/castle/budget";

package/dist/native/playtest-browser.js

@@ -79,7 +79,7 @@ function launchFailureMessage(err) {
     return `could not launch chromium: ${message}`;
 }
 async function loadPlaywrightReal() {
-    return (await import("playwright-core"));
+    return await import("playwright-core");
 }
 // playwright-core's exports map does NOT expose ./cli.js (verified against
 // 1.61: resolving it throws ERR_PACKAGE_PATH_NOT_EXPORTED), but it DOES

package/dist/native/tools.js

@@ -40,6 +40,18 @@ function resolveInDeck(deckDir, rawPath) {
         return null;
     return { abs, rel: rel.split(path.sep).join("/") };
 }
+function statFile(target) {
+    let stat;
+    try {
+        stat = fs.statSync(target.abs);
+    }
+    catch {
+        return { error: err(`no such file: ${target.rel}`) };
+    }
+    if (!stat.isFile())
+        return { error: err(`not a file: ${target.rel}`) };
+    return { stat };
+}
 // Sorted recursive file walk (deterministic order matters for grep/list_files
 // results and for tests), skipping IGNORED_DIRS at any depth. Capped as a
 // safety valve against pathological trees, not as a normal limit -- decks are
@@ -93,15 +105,10 @@ function readFileRun(args, ctx) {
     const resolved = resolveInDeck(ctx.deckDir, args.path);
     if (!resolved)
         return err(`path escapes the deck directory: ${String(args.path)}`);
-    let stat;
-    try {
-        stat = fs.statSync(resolved.abs);
-    }
-    catch {
-        return err(`no such file: ${resolved.rel}`);
-    }
-    if (!stat.isFile())
-        return err(`not a file: ${resolved.rel}`);
+    const statted = statFile(resolved);
+    if (statted.error)
+        return statted.error;
+    const stat = statted.stat;
     const ext = path.extname(resolved.rel).toLowerCase();
     if (BINARY_READ_EXTS.has(ext)) {
         return err(`${resolved.rel} is a binary/image file -- it cannot be read as text. Use the view_image tool to look at image files.`);
@@ -167,15 +174,10 @@ function viewImageRun(args, ctx) {
     if (!mime) {
         return err(`${resolved.rel} is not a viewable image -- view_image supports png/jpg/jpeg/gif/webp. SVG and other text formats can be read with read_file.`);
     }
-    let stat;
-    try {
-        stat = fs.statSync(resolved.abs);
-    }
-    catch {
-        return err(`no such file: ${resolved.rel}`);
-    }
-    if (!stat.isFile())
-        return err(`not a file: ${resolved.rel}`);
+    const statted = statFile(resolved);
+    if (statted.error)
+        return statted.error;
+    const stat = statted.stat;
     if (stat.size > VIEW_IMAGE_SIZE_CAP) {
         return err(`${resolved.rel} is too large to view (${(stat.size / (1024 * 1024)).toFixed(1)}MB > ${VIEW_IMAGE_SIZE_CAP / (1024 * 1024)}MB).`);
     }