castle-web-cli 0.4.107 → 0.4.109

package/dist/byo-auth.js

@@ -14,6 +14,7 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { inCastleSandbox } from "./metering.js";
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
 // A user's OWN provider credentials, kept SEPARATE from Castle's keys.json so
 // castle-www's per-serve re-sync of keys.json (cloudSandbox.ts syncCastleKeys)
@@ -55,23 +56,43 @@ export function userKey(envName) {
     const trimmed = v.trim();
     return trimmed ? trimmed : null;
 }
+// CLAUDE_CONFIG_DIR moves BOTH of claude's own files, and the sandbox sets it
+// (castle-sandboxes points it at the directory it persists, so `.claude.json` --
+// which holds the account record and the onboarding state -- lands inside the
+// symlink alongside the credential rather than beside it). Reading os.homedir()
+// unconditionally would mean reading a path claude has been told not to use.
+function claudeConfigDir() {
+    const dir = process.env.CLAUDE_CONFIG_DIR?.trim();
+    return dir ? dir : null;
+}
+// CASTLE_CLAUDE_CREDENTIALS_PATH overrides the location so the QA battery can
+// isolate from a developer's REAL ~/.claude login -- which, since this gates
+// proxy-vs-direct routing, would otherwise flip every plain-claude scenario to
+// "direct" on a logged-in machine. Mirrors the CASTLE_KEYS_PATH seam.
+export function claudeCredentialsPath() {
+    const override = process.env.CASTLE_CLAUDE_CREDENTIALS_PATH;
+    if (override !== undefined)
+        return override;
+    const dir = claudeConfigDir();
+    return dir
+        ? path.join(dir, ".credentials.json")
+        : path.join(os.homedir(), ".claude", ".credentials.json");
+}
 // KNOWN GAP (macOS): a false negative for most logged-in users. `claude /login`
 // stores credentials in the KEYCHAIN there, not in ~/.claude/.credentials.json,
 // so this returns false and the run stays on Castle's proxy even though the
 // user has a perfectly good subscription login the CLI would have used. Left
-// alone deliberately -- reading the Keychain (`security find-generic-password`)
-// changes who pays for a run, which is a product decision, not a cleanup. In a
-// Linux sandbox (the case that matters for BYO routing) the file IS
-// authoritative, so the gap doesn't bite.
+// alone deliberately -- reading the Keychain changes who pays for a run, which
+// is a product decision, not a cleanup. In a Linux sandbox (the case that
+// matters for BYO routing) the file IS authoritative, so the gap doesn't bite.
 //
-// CASTLE_CLAUDE_CREDENTIALS_PATH overrides the location so the QA battery can
-// isolate from a developer's REAL ~/.claude login -- which, since this gates
-// proxy-vs-direct routing, would otherwise flip every plain-claude scenario to
-// "direct" on a logged-in machine. Mirrors the CASTLE_KEYS_PATH seam.
+// `claude auth status --json` would close it: it reads the Keychain and reports
+// `authMethod` ("claude.ai" for a real login, "oauth_token" for an env
+// ANTHROPIC_AUTH_TOKEN -- so it means nothing unless Castle's pair is stripped
+// first). It is a subprocess, and this is called per `claude` run and per
+// account snapshot, so taking it costs a spawn on both.
 export function claudeHasSavedLogin() {
-    const credPath = process.env.CASTLE_CLAUDE_CREDENTIALS_PATH ??
-        path.join(os.homedir(), ".claude", ".credentials.json");
-    return fs.existsSync(credPath);
+    return fs.existsSync(claudeCredentialsPath());
 }
 // 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
@@ -149,12 +170,12 @@ function shellQuote(value) {
 export function anthropicKeyHelperCommand() {
     return `${shellQuote(process.execPath)} ${shellQuote(path.join(DIST_DIR, "anthropic-key-helper.js"))}`;
 }
-// Where the shell's inherited proxy pair goes when a credential of the user's
-// own displaces it. envForUserShell answers "whose credential" once, but
-// claudeShellEnvScript re-answers it per `claude` run and may need to put
-// Castle's routing BACK (the user deleted their key mid-session) -- which it
-// can only do if the values survived somewhere. Nothing reads these names by
-// accident, so stashing doesn't weaken the guarantee below.
+// Where the shell's inherited Castle credential goes when one of the user's own
+// displaces it. envForUserShell answers "whose credential" once, but the shims
+// re-answer it per run and may need to put Castle's back (the user deleted their
+// key, or signed out, mid-session) -- which they can only do if the values
+// survived somewhere. Nothing reads these names by accident, so stashing doesn't
+// weaken the guarantee below.
 const PROXY_STASH_PREFIX = "CASTLE_PTY_";
 // Env for the editor's PTY terminal. The container env the serve inherits
 // carries the llm-proxy pair, and Claude Code ranks ANTHROPIC_AUTH_TOKEN ABOVE
@@ -163,8 +184,8 @@ const PROXY_STASH_PREFIX = "CASTLE_PTY_";
 // ANTHROPIC_API_KEY or another auth source is set", their login unused and
 // their session billed to Castle.
 //
-// This is the shell's STARTING state only; the per-run answer is the shim's
-// (see installClaudeShim). It still matters on its own, because anything else
+// This is the shell's STARTING state only; the per-run answer is the shims'
+// (see installCliShims). It still matters on its own, because anything else
 // the user runs in that terminal -- a script that calls claude by absolute
 // path, an SDK program reading ANTHROPIC_API_KEY -- must not find Castle's
 // token sitting in the environment while the user has a credential of their own.
@@ -175,17 +196,26 @@ const PROXY_STASH_PREFIX = "CASTLE_PTY_";
 // person is there to answer it.
 export function envForUserShell(base) {
     const env = { ...base };
+    const stash = (name) => {
+        const inherited = env[name];
+        if (inherited !== undefined)
+            env[PROXY_STASH_PREFIX + name] = inherited;
+        delete env[name];
+    };
     const anthropic = resolveAnthropicAuth();
     if (anthropic.mode !== "proxy") {
-        for (const name of ANTHROPIC_PROXY_ENV) {
-            const inherited = env[name];
-            if (inherited !== undefined)
-                env[PROXY_STASH_PREFIX + name] = inherited;
-            delete env[name];
-        }
+        for (const name of ANTHROPIC_PROXY_ENV)
+            stash(name);
         if (anthropic.mode === "user-key")
             env.ANTHROPIC_API_KEY = anthropic.key;
     }
+    // The same withholding envForAgentSpawn does for a cursor run: Castle's key
+    // would let cursor-agent consider itself authenticated and never look at the
+    // user's own OAuth session, so their terminal would keep spending Castle's
+    // budget after they signed in. Cursor has no key of its own to put back --
+    // user-keys.json's CURSOR_API_KEY is described but not yet injected anywhere.
+    if (cursorHasUserLogin(os.homedir()))
+        stash("CURSOR_API_KEY");
     const openrouter = userKey("OPENROUTER_API_KEY");
     if (openrouter) {
         env.OPENROUTER_API_KEY = openrouter;
@@ -205,10 +235,10 @@ export function envForUserShell(base) {
 // still prints "claude.ai connectors are disabled...". Restarting claude, or
 // the panel, changed nothing -- only restarting the serve did.
 //
-// So the decision moves to a `claude` shim first on the terminal's PATH: it
-// resolves the credential at invocation time, fixes up the environment, and
-// execs the real binary. A login taken thirty seconds ago applies to the very
-// next run, in the same shell.
+// So the decision moves to a shim first on the terminal's PATH -- one per CLI
+// that has a credential to decide: it resolves at invocation time, fixes up the
+// environment, and execs the real binary. A login taken thirty seconds ago
+// applies to the very next run, in the same shell.
 //
 // Caveat: PATH ordering is not ours to guarantee. A login shell can reorder it
 // (macOS /etc/zprofile runs path_helper, which demotes an inherited entry below
@@ -224,15 +254,18 @@ function realpath(p) {
         return path.resolve(p);
     }
 }
-// The `claude` the shim should exec: the first executable one on `pathValue`
+// The CLIs a shim is installed for. Both take a credential from the environment
+// that Castle may be supplying, so both need the decision re-made per run.
+export const SHIMMED_CLIS = ["claude", "cursor-agent"];
+// The real binary the shim should exec: the first executable one on `pathValue`
 // that isn't the shim itself. Skipping by resolved directory (not by string) is
 // what keeps the shim from exec'ing itself forever.
-function findRealClaude(pathValue, shimDir) {
+function findRealBin(pathValue, shimDir, name) {
     const shimReal = realpath(shimDir);
     for (const entry of (pathValue ?? "").split(path.delimiter)) {
         if (!entry || realpath(entry) === shimReal)
             continue;
-        const candidate = path.join(entry, "claude");
+        const candidate = path.join(entry, name);
         try {
             fs.accessSync(candidate, fs.constants.X_OK);
             if (fs.statSync(candidate).isFile())
@@ -244,14 +277,30 @@ function findRealClaude(pathValue, shimDir) {
     }
     return null;
 }
+// `claude /login` -- the slash command as an ARGUMENT, which Claude Code runs at
+// startup. This run is about signing in, so it is given no credential of
+// Castle's at all: measured, an inherited ANTHROPIC_AUTH_TOKEN outranks whatever
+// the login stores, so the session that just signed in would still spend
+// Castle's budget and still print "claude.ai connectors are disabled" -- the
+// thing the user ran /login to stop. Stripped, the run opens "Not logged in",
+// the login lands with nothing above it, and that same session is on the user's
+// account.
+//
+// Only reachable for `claude X` typed as a command. A `/login` typed INSIDE a
+// running claude cannot be helped by anything out here: its environment was
+// fixed at exec and no one can change it from outside, so that session stays on
+// whatever it started with and the NEXT run picks the login up.
+function isLoginRun(args) {
+    return args.some((a) => a.trim() === "/login");
+}
 // Shell statements the shim evals before exec'ing claude: the environment that
 // makes THIS run use the credential resolveAnthropicAuth picks right now.
 // Emitting `unset` rather than an empty value matters -- Claude Code treats an
 // empty ANTHROPIC_BASE_URL as configured and fails to reach anything.
-export function claudeShellEnvScript(env, shimDir) {
+export function claudeShellEnvScript(env, args = []) {
     const lines = [];
     const auth = resolveAnthropicAuth();
-    if (auth.mode === "proxy") {
+    if (auth.mode === "proxy" && !isLoginRun(args)) {
         for (const name of ANTHROPIC_PROXY_ENV) {
             const stashed = env[PROXY_STASH_PREFIX + name];
             if (stashed !== undefined && env[name] === undefined) {
@@ -262,55 +311,133 @@ export function claudeShellEnvScript(env, shimDir) {
     else {
         for (const name of ANTHROPIC_PROXY_ENV)
             lines.push(`unset ${name}`);
-        if (auth.mode === "user-key") {
+        // Not on a login run: a key sitting in the environment is one more thing
+        // ranked above the login being made, and this run exists to make it.
+        if (auth.mode === "user-key" && !isLoginRun(args)) {
             lines.push(`ANTHROPIC_API_KEY=${shellQuote(auth.key)}; export ANTHROPIC_API_KEY`);
         }
     }
-    const real = findRealClaude(env.PATH, shimDir);
-    if (real)
-        lines.push(`CASTLE_REAL_CLAUDE=${shellQuote(real)}`);
-    return lines.length > 0 ? lines.join("\n") + "\n" : "";
+    return lines.join("\n");
 }
-// The baked CASTLE_REAL_CLAUDE is a fallback, not the answer: if the helper
-// runs, its own resolution (against the SHELL's PATH, which a login shell may
-// have rewritten) replaces it. It only survives when the helper failed to run
-// at all, and then it is the difference between the old static behavior and a
-// terminal where `claude` is suddenly missing.
-function shimScript(shimDir) {
+// The cursor half. Simpler, because there is one credential and no proxy pair:
+// Castle's CURSOR_API_KEY is either withheld (the user has their own OAuth
+// session, which cursor-agent would otherwise never look at) or put back from
+// the stash when they sign out again.
+export function cursorShellEnvScript(env) {
+    if (cursorHasUserLogin(os.homedir()))
+        return "unset CURSOR_API_KEY";
+    const stashed = env[PROXY_STASH_PREFIX + "CURSOR_API_KEY"];
+    if (stashed !== undefined && env.CURSOR_API_KEY === undefined) {
+        return `CURSOR_API_KEY=${shellQuote(stashed)}; export CURSOR_API_KEY`;
+    }
+    return "";
+}
+export function shimEnvScript(cli, env, shimDir, args = []) {
+    const lines = cli === "cursor-agent"
+        ? cursorShellEnvScript(env)
+        : claudeShellEnvScript(env, args);
+    const real = findRealBin(env.PATH, shimDir, cli);
+    const all = [lines, real ? `CASTLE_REAL_BIN=${shellQuote(real)}` : ""].filter((l) => l !== "");
+    return all.length > 0 ? all.join("\n") + "\n" : "";
+}
+// The baked CASTLE_REAL_BIN is a fallback, not the answer: if the helper runs,
+// its own resolution (against the SHELL's PATH, which a login shell may have
+// rewritten) replaces it. It only survives when the helper failed to run at all,
+// and then it is the difference between the old static behavior and a terminal
+// where the CLI is suddenly missing.
+//
+// "$@" reaches the helper so it can see arguments the decision turns on --
+// `claude /login` (see isLoginRun). The shell expands it into separate words
+// inside the substitution, so nothing in it is re-parsed.
+function shimScript(shimDir, cli) {
     const helper = [
         shellQuote(process.execPath),
-        shellQuote(path.join(DIST_DIR, "claude-shim-env.js")),
+        shellQuote(path.join(DIST_DIR, "cli-shim-env.js")),
         shellQuote(shimDir),
+        shellQuote(cli),
     ].join(" ");
     return [
         "#!/bin/sh",
-        "# Generated by `castle-web serve` -- see installClaudeShim in castle-web-cli.",
-        `CASTLE_REAL_CLAUDE=${shellQuote(findRealClaude(process.env.PATH, shimDir) ?? "")}`,
-        `eval "$(${helper})"`,
-        'if [ -z "$CASTLE_REAL_CLAUDE" ]; then',
-        '  echo "castle-web: claude is not installed on this PATH" >&2',
+        "# Generated by `castle-web serve` -- see installCliShims in castle-web-cli.",
+        `CASTLE_REAL_BIN=${shellQuote(findRealBin(process.env.PATH, shimDir, cli) ?? "")}`,
+        `eval "$(${helper} "$@")"`,
+        'if [ -z "$CASTLE_REAL_BIN" ]; then',
+        `  echo "castle-web: ${cli} is not installed on this PATH" >&2`,
         "  exit 127",
         "fi",
-        'exec "$CASTLE_REAL_CLAUDE" "$@"',
+        'exec "$CASTLE_REAL_BIN" "$@"',
         "",
     ].join("\n");
 }
+// Claude Code's first-run onboarding asks for a login even when one is already
+// stored. Measured against 2.1.220 through a real pty: with onboarding
+// incomplete, a `.credentials.json` -- with or without a matching `oauthAccount`
+// in `.claude.json` -- still lands on "Select login method", while the same
+// credential with onboarding complete goes straight through. What normally
+// carries a sandbox past that step is Castle's injected ANTHROPIC_AUTH_TOKEN, an
+// env credential, which is exactly what this shim takes away the moment the user
+// has one of their own. So a user who signs in from the editor BEFORE ever
+// opening the terminal is asked by their first `claude` to sign in again, and
+// pays a second OAuth round trip for a login they already completed.
+//
+// Marking onboarding done is what makes claude accept the stored login --
+// `hasCompletedOnboarding` alone is enough, measured, so no version flag is
+// written and there is nothing to drift. Kept narrow deliberately: only in a
+// sandbox, only once the user actually has a credential of their own, only when
+// onboarding has not already run. A developer's own machine is never touched,
+// and neither is claude's first-run experience for anyone on Castle's account.
+export function ensureClaudeOnboarded() {
+    if (!inCastleSandbox())
+        return;
+    if (resolveAnthropicAuth().mode === "proxy")
+        return;
+    const dir = claudeConfigDir();
+    const file = dir
+        ? path.join(dir, ".claude.json")
+        : path.join(os.homedir(), ".claude.json");
+    let config = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        // Not ours to repair: a file we can't read is one claude may still be able
+        // to, and replacing it wholesale would cost the user their project history.
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return;
+        config = parsed;
+    }
+    catch {
+        /* no file yet -- the normal case in a sandbox nobody has run claude in */
+    }
+    if (config.hasCompletedOnboarding === true)
+        return;
+    config.hasCompletedOnboarding = true;
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const staged = `${file}.castle-staged`;
+        fs.writeFileSync(staged, JSON.stringify(config, null, 2) + "\n");
+        fs.renameSync(staged, file);
+    }
+    catch {
+        /* claude asks again; nothing else depends on this */
+    }
+}
 // Returns the directory to put first on the terminal's PATH, or null when there
-// is no shim to install -- a failure here costs the per-run re-resolution, so it
+// is none to install -- a failure here costs the per-run re-resolution, so it
 // degrades to envForUserShell's spawn-time answer rather than breaking the shell.
-export function installClaudeShim(deckDir) {
+export function installCliShims(deckDir) {
     if (process.platform === "win32")
         return null;
     const dir = path.join(deckDir, ".castle", "shims");
     try {
         fs.mkdirSync(dir, { recursive: true });
-        // Write-then-rename, because /bin/sh reads a script incrementally: a second
-        // serve reinstalling over this deck while a claude is running through the
-        // shim would otherwise pull the file out from under that sh mid-read.
-        const staged = path.join(dir, "claude.staged");
-        fs.writeFileSync(staged, shimScript(dir));
-        fs.chmodSync(staged, 0o755);
-        fs.renameSync(staged, path.join(dir, "claude"));
+        for (const cli of SHIMMED_CLIS) {
+            // Write-then-rename, because /bin/sh reads a script incrementally: a
+            // second serve reinstalling over this deck while a run is going through
+            // the shim would otherwise pull the file out from under that sh mid-read.
+            const staged = path.join(dir, `${cli}.staged`);
+            fs.writeFileSync(staged, shimScript(dir, cli));
+            fs.chmodSync(staged, 0o755);
+            fs.renameSync(staged, path.join(dir, cli));
+        }
         return dir;
     }
     catch {

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/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, installClaudeShim } 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
@@ -651,7 +651,7 @@ export function createIdeServer(opts) {
     let session = null;
     function spawnSession() {
         const { command, args } = defaultShell();
-        const shimDir = installClaudeShim(deckDir);
+        const shimDir = installCliShims(deckDir);
         const screen = new HeadlessTerminal({
             allowProposedApi: true,
             cols: INITIAL_COLS,