castle-web-cli 0.4.106 → 0.4.108

package/dist/byo-auth.js

@@ -4,51 +4,121 @@
 // terminal has to answer the same question for the `claude` a user runs by
 // hand -- and must answer it the SAME way, or the terminal quietly spends
 // Castle's budget while the agent panel spends the user's.
+//
+// The claude-CLI behaviors this file leans on (AUTH_TOKEN outranks a login,
+// apiKeyHelper works headless, an env key alone does not) are measured, not
+// documented, and the agent-qa battery fakes `claude` so it cannot notice them
+// drifting -- scripts/tests/real-claude-smoke.mjs re-verifies them against a
+// real binary; run it when the sandbox image's claude version bumps.
 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)
-// can't clobber them. Same shape as keys.json (env-var-name keys); the user (or
-// a future editor UI) writes this file, nothing in-process does. When a key is
+// can't clobber them. Same shape as keys.json (env-var-name keys). When a key is
 // present the run goes DIRECT to that provider on the user's own credential and
 // is NOT metered -- deleting the key reverts to Castle's proxy on the next run.
 // The path override mirrors CASTLE_KEYS_PATH so the QA battery stays isolated
 // from a developer's real ~/.castle. No env fallback on read: the file is the
 // only source, so a delete fully reverts.
+//
+// Written by hand, or by the editor's Accounts rows -- byo-accounts.ts is the
+// only writer in this process, and it merges rather than replaces so a key it
+// has no descriptor for still survives an edit.
 export const CASTLE_USER_KEYS_PATH = process.env.CASTLE_USER_KEYS_PATH ??
     path.join(os.homedir(), ".castle", "user-keys.json");
-function userKeys() {
+// Exported for byo-accounts.ts, whose writes must preserve entries this file
+// has no name for; every other reader wants userKey() instead.
+//
+// The file is hand-editable, so its shape is user input: a top-level primitive
+// would make every `stored[k]` assignment downstream a strict-mode TypeError
+// inside the serve's WS handler, where nothing catches it. VALUES are not
+// validated -- a non-string entry survives a merge untouched -- so anything
+// that uses one must typeof-check it first.
+export function readUserKeys() {
     try {
-        return JSON.parse(fs.readFileSync(CASTLE_USER_KEYS_PATH, "utf8"));
+        const parsed = JSON.parse(fs.readFileSync(CASTLE_USER_KEYS_PATH, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
     }
     catch {
         return {};
     }
 }
 export function userKey(envName) {
-    const v = userKeys()[envName]?.trim();
-    return v ? v : null;
+    const v = readUserKeys()[envName];
+    if (typeof v !== "string")
+        return null;
+    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
+// 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).
+export function cursorAuthPath(home) {
+    return path.join(home, ".config", "cursor", "auth.json");
+}
+export function cursorHasUserLogin(home) {
+    try {
+        const auth = JSON.parse(fs.readFileSync(cursorAuthPath(home), "utf8"));
+        return !auth.apiKey && !!auth.accessToken;
+    }
+    catch {
+        return false;
+    }
 }
 export function resolveAnthropicAuth() {
     const k = userKey("ANTHROPIC_API_KEY");
@@ -100,13 +170,25 @@ function shellQuote(value) {
 export function anthropicKeyHelperCommand() {
     return `${shellQuote(process.execPath)} ${shellQuote(path.join(DIST_DIR, "anthropic-key-helper.js"))}`;
 }
+// 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
 // a claude.ai login -- so without this a user who ran `claude /login` in the
 // terminal still gets "claude.ai connectors are disabled because
 // ANTHROPIC_API_KEY or another auth source is set", their login unused and
-// their session billed to Castle. Resolved at shell start, so a login taken in
-// an open terminal applies to the next one.
+// their session billed to Castle.
+//
+// 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.
 //
 // A user KEY goes in as ANTHROPIC_API_KEY here, unlike the agent path's
 // apiKeyHelper (see above): an interactive claude CAN show the one-time
@@ -114,13 +196,26 @@ export function anthropicKeyHelperCommand() {
 // 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)
-            delete env[name];
+            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;
@@ -128,3 +223,224 @@ export function envForUserShell(base) {
     }
     return env;
 }
+// --- the terminal's per-run credential decision ------------------------------
+//
+// A process's environment is fixed at spawn, and the editor keeps ONE shell per
+// serve -- closing the terminal panel drops the socket, not the shell (see
+// ide.ts ensureSession), so envForUserShell's answer is the answer that shell
+// keeps for as long as the serve lives. That made `claude /login` in the
+// terminal a no-op for the terminal itself: the login lands, the agent panel
+// (which resolves per run) starts using it, and every later `claude` in that
+// same shell still finds the inherited ANTHROPIC_AUTH_TOKEN outranking it and
+// 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 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
+// /usr/local/bin) or replace it outright (Debian's /etc/profile does, for root
+// -- though only bash reads it; the sandbox's `zsh -l` keeps our entry first).
+// When the shim loses, the credential is simply the one envForUserShell picked
+// at shell start -- the old behavior, not a broken one.
+function realpath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+// 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 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, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            if (fs.statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            /* not this entry */
+        }
+    }
+    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, args = []) {
+    const lines = [];
+    const auth = resolveAnthropicAuth();
+    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) {
+                lines.push(`${name}=${shellQuote(stashed)}; export ${name}`);
+            }
+        }
+    }
+    else {
+        for (const name of ANTHROPIC_PROXY_ENV)
+            lines.push(`unset ${name}`);
+        // 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`);
+        }
+    }
+    return lines.join("\n");
+}
+// 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, "cli-shim-env.js")),
+        shellQuote(shimDir),
+        shellQuote(cli),
+    ].join(" ");
+    return [
+        "#!/bin/sh",
+        "# 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_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 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 installCliShims(deckDir) {
+    if (process.platform === "win32")
+        return null;
+    const dir = path.join(deckDir, ".castle", "shims");
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        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 {
+        return null;
+    }
+}

package/dist/byo-login.d.ts

@@ -0,0 +1,14 @@
+export type LoginProvider = "claude" | "cursor";
+export type LoginPhase = "starting" | "awaiting-user" | "awaiting-code" | "verifying" | "error";
+export interface LoginState {
+    provider: LoginProvider;
+    phase: LoginPhase;
+    url?: string;
+    message?: string;
+}
+export declare function activeLogin(): LoginState | null;
+export declare function providerHasLogin(provider: LoginProvider): boolean;
+export declare function startLogin(provider: LoginProvider, onChange: () => void): void;
+export declare function submitLoginCode(code: string): void;
+export declare function logout(provider: LoginProvider, onChange: () => void): void;
+export declare function cancelLogin(): void;

package/dist/byo-login.js

@@ -0,0 +1,196 @@
+// Driving `claude auth login` / `cursor-agent login` from the editor, so a user
+// can put a run on their own subscription without knowing the terminal exists.
+//
+// Both CLIs are usable HEADLESS -- measured, not documented (probed 2026-07-30
+// against claude 2.1.220 and the current cursor-agent):
+//
+//   claude auth login   with no TTY and stdin from a pipe, prints
+//                       "Opening browser to sign in…" then the OAuth URL, then
+//                       blocks reading a pasted code from STDIN. The URL is
+//                       wrapped in an OSC-8 hyperlink, so it appears TWICE in
+//                       the raw bytes.
+//   cursor-agent login  with NO_OPEN_BROWSER=1, prints
+//                       "Open a browser and navigate to this link: <url>" and
+//                       then POLLS the challenge itself -- no code to paste.
+//
+// Neither uses a localhost callback, which is what makes this work at all in a
+// sandbox: the browser is on the user's machine and the CLI is in a container,
+// so a loopback redirect would have nowhere to land.
+//
+// `claude setup-token` is NOT usable here: with no TTY it prints nothing, and
+// under one it launches the full Claude Code TUI.
+import { spawn } from "child_process";
+import * as os from "os";
+import { ANTHROPIC_PROXY_ENV, claudeHasSavedLogin, cursorHasUserLogin, } from "./byo-auth.js";
+// A login is a singleton: two at once would race for the same credential file,
+// and the UI only ever offers one. A second start replaces the first.
+let active = null;
+export function activeLogin() {
+    return active ? active.state : null;
+}
+export function providerHasLogin(provider) {
+    return provider === "claude"
+        ? claudeHasSavedLogin()
+        : cursorHasUserLogin(os.homedir());
+}
+// Long enough for a real sign-in (find the browser, log in, maybe sign up),
+// short enough that an abandoned flow doesn't leave a child running forever.
+// The env override is a QA seam, like CASTLE_USER_KEYS_PATH: ten minutes is
+// unwaitable in a test.
+const LOGIN_TIMEOUT_MS = Number(process.env.CASTLE_LOGIN_TIMEOUT_MS ?? "") || 10 * 60 * 1000;
+// OSC-8 hyperlinks and colour codes come through on both CLIs; strip them
+// before matching so a URL isn't cut short at an escape byte.
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*[A-Za-z]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?/g;
+const URL_PATTERN = {
+    claude: /https:\/\/claude\.com\/\S*oauth\S*/,
+    cursor: /https:\/\/cursor\.com\/\S*/,
+};
+function commandFor(provider) {
+    const env = { ...process.env, NO_OPEN_BROWSER: "1" };
+    if (provider === "cursor") {
+        // Castle's key would let cursor-agent consider itself authenticated and
+        // skip the OAuth it was just asked for.
+        delete env.CURSOR_API_KEY;
+        return { file: "cursor-agent", args: ["login"], env };
+    }
+    // Castle's proxy pair outranks a claude.ai login (see byo-auth), and the
+    // sandbox always has it set -- leaving it in place would have claude decide
+    // it is already authenticated and skip the flow entirely.
+    for (const name of ANTHROPIC_PROXY_ENV)
+        delete env[name];
+    // Nothing here should open a browser on the SERVE's machine: in a sandbox
+    // that is the container, where it would silently fail; locally it would
+    // steal focus from the person who clicked.
+    env.BROWSER = "true";
+    return { file: "claude", args: ["auth", "login"], env };
+}
+function publish(next) {
+    if (!active)
+        return;
+    active.state = { ...active.state, ...next };
+    active.onChange();
+}
+function finish(message) {
+    if (!active)
+        return;
+    clearTimeout(active.timer);
+    const { onChange } = active;
+    if (message === null) {
+        active = null;
+    }
+    else {
+        // The flow is over, so nothing will read from the child again -- without
+        // this kill a timed-out `claude auth login` sits blocked on stdin forever,
+        // the very leak LOGIN_TIMEOUT_MS exists to prevent. A no-op on the paths
+        // where the child already exited.
+        active.child?.kill();
+        active.state = { ...active.state, phase: "error", message };
+        // Kept, not cleared: the phase IS the error surface, and a cleared state
+        // would read to the client as "no flow ran" -- indistinguishable from a
+        // button that did nothing. cancelLogin / the next start clears it.
+    }
+    onChange();
+}
+function handleOutput(text) {
+    if (!active)
+        return;
+    const clean = text.replace(ANSI, "");
+    // A mistyped code does NOT end the process -- claude prints this and prompts
+    // again (measured: "Invalid code. Please make sure the full code was
+    // copied."). Without catching it the flow sits in `verifying` until the
+    // timeout, looking like a hang, and the user has no way to retry short of
+    // cancelling. Put them back on the code step with the CLI's own wording.
+    const invalid = /Invalid code[^\n]*/.exec(clean);
+    if (invalid) {
+        publish({ phase: "awaiting-code", message: invalid[0].trim() });
+        return;
+    }
+    if (!active.state.url) {
+        const match = URL_PATTERN[active.provider].exec(clean);
+        if (match) {
+            publish({
+                url: match[0],
+                // claude will ask for a pasted code next; cursor polls on its own.
+                phase: active.provider === "claude" ? "awaiting-code" : "awaiting-user",
+            });
+        }
+    }
+}
+export function startLogin(provider, onChange) {
+    cancelLogin();
+    const { file, args, env } = commandFor(provider);
+    let child;
+    try {
+        child = spawn(file, args, { env, stdio: ["pipe", "pipe", "pipe"] });
+    }
+    catch {
+        active = {
+            provider,
+            child: null,
+            state: { provider, phase: "error", message: `could not run ${file}` },
+            timer: setTimeout(() => undefined, 0),
+            onChange,
+        };
+        onChange();
+        return;
+    }
+    active = {
+        provider,
+        child,
+        state: { provider, phase: "starting" },
+        timer: setTimeout(() => finish("Timed out waiting for sign-in."), LOGIN_TIMEOUT_MS),
+        onChange,
+    };
+    child.stdout?.on("data", (b) => handleOutput(b.toString()));
+    child.stderr?.on("data", (b) => handleOutput(b.toString()));
+    child.on("error", () => finish(`could not run ${file}`));
+    child.on("close", () => {
+        if (!active || active.child !== child)
+            return;
+        // Already settled as an error: this close is finish()'s own kill landing
+        // (the timeout path), and evaluating it as a fresh outcome would overwrite
+        // the message that explains what happened.
+        if (active.state.phase === "error")
+            return;
+        publish({ phase: "verifying" });
+        // The RESOLVER decides, never the exit code: what matters is whether the
+        // credential this process routes on is now there. A CLI that exits 0
+        // without leaving one behind must not read as success.
+        if (providerHasLogin(provider))
+            finish(null);
+        else
+            finish("Sign-in did not complete.");
+    });
+    onChange();
+}
+export function submitLoginCode(code) {
+    if (!active || active.state.phase !== "awaiting-code")
+        return;
+    const trimmed = code.trim();
+    if (!trimmed)
+        return;
+    active.child.stdin?.write(trimmed + "\n");
+    publish({ phase: "verifying" });
+}
+// Sign out, so the modal isn't a one-way door. Fire-and-forget by shape but
+// awaited for its close, because the snapshot is only right once the CLI has
+// actually dropped the credential -- the resolver, again, not the exit code.
+export function logout(provider, onChange) {
+    cancelLogin();
+    const { file, args, env } = provider === "cursor"
+        ? { file: "cursor-agent", args: ["logout"], env: process.env }
+        : { file: "claude", args: ["auth", "logout"], env: commandFor("claude").env };
+    const child = spawn(file, args, { env, stdio: "ignore" });
+    child.on("error", onChange);
+    child.on("close", onChange);
+}
+export function cancelLogin() {
+    if (!active)
+        return;
+    clearTimeout(active.timer);
+    active.child?.kill();
+    const { onChange } = active;
+    active = null;
+    onChange();
+}

package/dist/castleJson.d.ts

@@ -0,0 +1,15 @@
+export interface DeckImport {
+    deckId?: string;
+    source?: 'builtin';
+    kit?: string;
+    via?: string;
+    version: string;
+}
+export interface CastleJson {
+    deckId?: string;
+    cardId?: string;
+    imports?: Record<string, DeckImport>;
+    [key: string]: unknown;
+}
+export declare function readCastleJson(dir: string): CastleJson | null;
+export declare function readCastleJsonOrThrow(dir: string): CastleJson | null;

package/dist/castleJson.js

@@ -0,0 +1,24 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// A missing castle.json is normal (a deck has none until its first save), so it
+// reads as `null` rather than an error. An unparseable one is not -- `onInvalid`
+// is how a caller says whether that should be fatal here or just another `null`.
+function readCastleJsonFile(dir, onInvalid) {
+    const file = path.join(dir, 'castle.json');
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    }
+    catch (e) {
+        return onInvalid(file, e);
+    }
+}
+export function readCastleJson(dir) {
+    return readCastleJsonFile(dir, () => null);
+}
+export function readCastleJsonOrThrow(dir) {
+    return readCastleJsonFile(dir, (file, e) => {
+        throw new Error(`Could not read ${file}: ${e instanceof Error ? e.message : String(e)}`);
+    });
+}