@catalyst-cloud/cli 0.16.23 → 0.16.24

package/dist/env/scan-claude-mcp.js

@@ -0,0 +1,274 @@
+// scan-claude-mcp.ts — Claude Code's HTTP MCP servers (`~/.claude.json`), turned into
+// `[[environment.mcp_servers]]` declarations whose every header is a `$NAME` reference.
+//
+// Two sources are read, in Claude Code's own precedence: the top-level `mcpServers` (its user scope)
+// and `projects[<this repository's path>].mcpServers` (its default local scope), the local entry
+// winning a name clash. No server is contacted and no `claude` command runs.
+//
+// ⛔ `scanClaudeMcp` RETURNS NO HEADER VALUE. A header that references `${NAME}` keeps the name; a
+// header that holds a literal becomes a new secret variable (`<SERVER>_MCP_TOKEN` and friends) and
+// the literal is dropped with the parsed object. `claudeHeaderLiterals` is the one export that hands
+// a literal back, and only the import's value resolver (`machine-values.ts`) calls it.
+import { validateFullSettings } from "../../vendor/settings/index.js";
+const HEADER_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9-_]{0,127}$/;
+const REF_RE = /^\$(?:\{([A-Za-z_][A-Za-z0-9_]*)(?::-[^}]*)?\}|([A-Za-z_][A-Za-z0-9_]*))$/;
+const UPPER_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+const MAX_SERVERS = 64;
+const MAX_HEADERS = 32;
+/** A Catalyst server name: lowercase, `[a-z0-9_-]`, starting with a letter, at most 64 characters. */
+function toServerName(configName) {
+    const name = configName.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^[-_]+|[-_]+$/g, "").slice(0, 64);
+    return /^[a-z][a-z0-9_-]{0,63}$/.test(name) ? name : null;
+}
+/** An upper-case variable stem from a server or header name: `my-server` → `MY_SERVER`. */
+function toVariableName(text) {
+    return text.toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function derivedVariable(serverName, header, bearer) {
+    const stem = toVariableName(serverName);
+    const prefix = /^[A-Z]/.test(stem) ? stem : `MCP_${stem}`;
+    if (header.toLowerCase() === "authorization")
+        return `${prefix}_MCP_${bearer ? "TOKEN" : "AUTHORIZATION"}`;
+    return `${prefix}_MCP_${toVariableName(header)}`;
+}
+export function scanClaudeMcp(text, repoRoots, declared) {
+    if (text === undefined)
+        return { servers: [], notDrafted: [], note: "~/.claude.json was not found" };
+    const entries = readEntries(text, repoRoots);
+    if (typeof entries === "string")
+        return { servers: [], notDrafted: [], note: entries };
+    const servers = [];
+    const notDrafted = [];
+    const taken = new Set(declared);
+    // Reserve explicit references before deriving names, including later servers and headers.
+    // Use the effective entries after project overrides, just as the import lookup does.
+    for (const entry of entries) {
+        const name = toServerName(entry.configName);
+        if (name === null || !isRecord(entry.raw) || !isRecord(entry.raw.headers))
+            continue;
+        for (const [header, value] of Object.entries(entry.raw.headers)) {
+            if (!HEADER_NAME_RE.test(header) || typeof value !== "string")
+                continue;
+            const read = readHeader(name, header, value);
+            if (read.kind === "reference")
+                taken.add(read.name);
+        }
+    }
+    const names = new Set();
+    for (const entry of entries) {
+        const outcome = draftServer(entry, taken);
+        if ("reason" in outcome) {
+            notDrafted.push({ name: entry.configName, reason: outcome.reason });
+            continue;
+        }
+        if (names.has(outcome.name)) {
+            notDrafted.push({ name: entry.configName, reason: `its name becomes ${outcome.name}, which another server already uses` });
+            continue;
+        }
+        if (servers.length >= MAX_SERVERS) {
+            notDrafted.push({ name: entry.configName, reason: `more than ${MAX_SERVERS} servers; add it by hand` });
+            continue;
+        }
+        if (!passesSettingsCheck(outcome)) {
+            notDrafted.push({ name: entry.configName, reason: "Catalyst's settings check refused it; add it by hand" });
+            continue;
+        }
+        names.add(outcome.name);
+        for (const { variable } of outcome.derived)
+            taken.add(variable);
+        servers.push(outcome);
+    }
+    return { servers, notDrafted };
+}
+/** Import only. The literal (without `Bearer `) behind each requested variable the draft derives. Only
+ *  servers the draft itself drafts count, given the same `declared` names it saw (the `.envrc` exports):
+ *  a server it refused, or one whose derived name clashed, never supplies a value. */
+export function claudeHeaderLiterals(text, repoRoots, wanted, declared = new Set()) {
+    const values = new Map();
+    const entries = readEntries(text, repoRoots);
+    if (typeof entries === "string")
+        return values;
+    const drafted = new Map(scanClaudeMcp(text, repoRoots, declared).servers.map((server) => [server.configName, server]));
+    for (const entry of entries) {
+        const server = drafted.get(entry.configName);
+        if (server === undefined || !isRecord(entry.raw) || !isRecord(entry.raw.headers))
+            continue;
+        const derived = new Set(server.derived.map(({ variable }) => variable));
+        for (const [header, value] of Object.entries(entry.raw.headers)) {
+            if (typeof value !== "string")
+                continue;
+            const read = readHeader(server.name, header, value);
+            if (read.kind === "literal" && derived.has(read.variable) && wanted.has(read.variable))
+                values.set(read.variable, read.literal);
+        }
+    }
+    return values;
+}
+/** One `[[environment.mcp_servers]]` block. Header keys are JSON-quoted. */
+export function mcpServerToml(server) {
+    const headers = Object.entries(server.headers).map(([name, value]) => `${JSON.stringify(name)} = ${JSON.stringify(value)}`);
+    return [
+        "[[environment.mcp_servers]]",
+        `name = ${JSON.stringify(server.name)}`,
+        'transport = "http"',
+        `url = ${JSON.stringify(server.url)}`,
+        `headers = { ${headers.join(", ")} }`,
+        "",
+    ].join("\n");
+}
+function readEntries(text, repoRoots) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return "~/.claude.json is not valid JSON; no MCP server was drafted";
+    }
+    if (!isRecord(parsed))
+        return "~/.claude.json does not hold a JSON object; no MCP server was drafted";
+    const byName = new Map();
+    if (isRecord(parsed.mcpServers)) {
+        for (const [configName, raw] of Object.entries(parsed.mcpServers))
+            byName.set(configName, { configName, scope: "user", raw });
+    }
+    const projects = isRecord(parsed.projects) ? parsed.projects : {};
+    // Claude Code keys projects by path as it saw it: on Windows `C:/Users/…` while Node gives
+    // `C:\Users\…`. Compare the two spellings, not the exact key.
+    const projectKeys = new Map(Object.keys(projects).map((key) => [projectPathKey(key), key]));
+    for (const root of new Set(repoRoots.map(projectPathKey))) {
+        const key = projectKeys.get(root);
+        const project = key === undefined ? undefined : projects[key];
+        if (!isRecord(project) || !isRecord(project.mcpServers))
+            continue;
+        for (const [configName, raw] of Object.entries(project.mcpServers)) {
+            byName.delete(configName);
+            byName.set(configName, { configName, scope: "project", raw });
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.configName.localeCompare(b.configName, "en"));
+}
+function draftServer(entry, taken) {
+    const raw = entry.raw;
+    if (!isRecord(raw))
+        return { reason: "its entry is not an object" };
+    const type = typeof raw.type === "string" ? raw.type : raw.command !== undefined ? "stdio" : raw.url !== undefined ? "http" : "unknown";
+    if (type === "stdio" || raw.command !== undefined)
+        return { reason: "a stdio server runs a command on this computer" };
+    if (type === "sse")
+        return { reason: "SSE servers are not drafted" };
+    if (type !== "http")
+        return { reason: `${type} servers are not drafted` };
+    const urlCheck = checkUrl(raw.url);
+    if (urlCheck !== null)
+        return { reason: urlCheck };
+    const url = String(raw.url).trim();
+    const name = toServerName(entry.configName);
+    if (name === null)
+        return { reason: "its name cannot become a Catalyst server name (letters, digits, - and _)" };
+    if (!isRecord(raw.headers) || Object.keys(raw.headers).length === 0) {
+        return { reason: "no header auth; it likely signs in with OAuth, which phases cannot reuse" };
+    }
+    const rawHeaders = Object.entries(raw.headers);
+    if (rawHeaders.length > MAX_HEADERS)
+        return { reason: `it has more than ${MAX_HEADERS} headers` };
+    const headers = {};
+    const references = new Set();
+    const derived = [];
+    for (const [header, value] of rawHeaders) {
+        if (!HEADER_NAME_RE.test(header))
+            return { reason: "a header name Catalyst cannot carry" };
+        if (typeof value !== "string")
+            return { reason: "a header value is not text" };
+        const read = readHeader(name, header, value);
+        if (read.kind === "refused")
+            return { reason: read.reason };
+        const variable = read.kind === "reference" ? read.name : read.variable;
+        if (read.kind === "literal") {
+            if (taken.has(variable) || references.has(variable)) {
+                return { reason: `its ${header} header held a value, and the name it would get, ${variable}, is already declared; add it by hand` };
+            }
+            derived.push({ variable, header, bearer: read.bearer });
+        }
+        references.add(variable);
+        headers[header] = read.bearer ? `Bearer $${variable}` : `$${variable}`;
+    }
+    return {
+        name,
+        configName: entry.configName,
+        scope: entry.scope,
+        url,
+        headers,
+        references: [...references].sort((a, b) => a.localeCompare(b, "en")),
+        derived,
+    };
+}
+function readHeader(serverName, header, value) {
+    const isAuthorization = header.toLowerCase() === "authorization";
+    const bearerMatch = isAuthorization ? /^Bearer\s+(.*)$/i.exec(value) : null;
+    const bearer = bearerMatch !== null;
+    const body = bearerMatch ? bearerMatch[1] : value;
+    const ref = REF_RE.exec(body);
+    if (ref) {
+        const name = ref[1] ?? ref[2];
+        if (!UPPER_NAME_RE.test(name))
+            return { kind: "refused", reason: "a header references a variable whose name is not upper-case" };
+        return { kind: "reference", name, bearer };
+    }
+    if (body.includes("$"))
+        return { kind: "refused", reason: "a header mixes text and a variable" };
+    return { kind: "literal", variable: derivedVariable(serverName, header, bearer), bearer, literal: body };
+}
+function checkUrl(raw) {
+    if (typeof raw !== "string")
+        return "it has no URL";
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        return "its URL could not be read";
+    }
+    if (url.username || url.password || url.search || url.hash || raw.includes("?") || raw.includes("#")) {
+        return "its URL carries a query string or sign-in details; add it by hand";
+    }
+    if (isPrivateHost(url.hostname))
+        return "it points at this computer or a private network";
+    if (url.protocol !== "https:")
+        return "its URL does not use https";
+    if (url.pathname.split("/").some(looksLikeKey))
+        return "its URL path looks like it carries a key; add it by hand";
+    if (url.hostname.split(".").some(looksLikeKey))
+        return "its URL host looks like it carries a key; add it by hand";
+    return null;
+}
+/** A path segment or host label shaped like a key: long, and mixing letters with digits, including
+ *  base64's `+` and `=` and percent-escapes. `mcp`, `v1` and `sse` are not. */
+function looksLikeKey(segment) {
+    return segment.length >= 20 && /^[A-Za-z0-9_.~+=%-]+$/.test(segment) && /[A-Za-z]/.test(segment) && /[0-9]/.test(segment);
+}
+/** One spelling of a project path: forward slashes, a lower-case drive letter, no trailing slash. */
+function projectPathKey(path) {
+    const slashed = path.replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_, drive) => `${drive.toLowerCase()}:`);
+    return slashed.length > 1 ? slashed.replace(/\/+$/, "") : slashed;
+}
+function isPrivateHost(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host === "0.0.0.0")
+        return true;
+    const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (v4) {
+        const [a, b] = [Number(v4[1]), Number(v4[2])];
+        return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) || a === 0;
+    }
+    if (host.includes(":"))
+        return host === "::1" || host === "::" || /^f[cd]/.test(host) || /^fe[89ab]/.test(host) || host.startsWith("::ffff:");
+    return false;
+}
+function passesSettingsCheck(server) {
+    const variables = server.references.map((name) => `[[environment.variables]]\nname = ${JSON.stringify(name)}\nsecret = true\nrequired = false\n`);
+    const doc = `[project]\nlinear_team = "DRAFT"\n\n[environment]\n${variables.join("\n")}\n${mcpServerToml(server)}`;
+    return validateFullSettings(doc).ok;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/env/scan-envrc.js

@@ -0,0 +1,271 @@
+// scan-envrc.ts — the names a repository's `.envrc` exports, read as text and never run. direnv
+// would run the file as shell; this reader only looks at `export` statements, so a name whose value
+// a command computes is still listed, and nothing on the line executes.
+//
+// ⛔ `scanEnvrc` RETURNS NO VALUE. The value half of a line is looked at for two purposes only:
+// deciding whether later lines continue it (a quote, a PEM block, a heredoc or a trailing
+// backslash, the same idiom as `scan-env-example.ts`), and deciding whether it is a static literal.
+// `envrcLiteralValues` is the one export that hands a value back, and only the import's value
+// resolver (`machine-values.ts`) calls it.
+//
+// direnv's own commands (`dotenv`, `source_env`, `PATH_add`, `use`, `layout` and the rest) load
+// names from other files or run tools. They are not followed: each is reported as a line not read.
+const NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const EXPORT_RE = /^\s*export\s+(.*)$/;
+const ASSIGN_RE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+const BARE_ASSIGN_RE = /^\s*([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+const NAMES_ONLY_RE = /^([A-Za-z_][A-Za-z0-9_]*(?:\s+[A-Za-z_][A-Za-z0-9_]*)*)\s*(?:#.*)?$/;
+const HEREDOC_RE = /^<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_]*)['"]?/;
+// `#` only starts a comment at the start of a word, so `foo#bar` is one literal.
+const UNQUOTED_LITERAL_RE = /^[A-Za-z0-9_./:@%+,=#-]+$/;
+// An `export` that is not the line's first word: `[ -n x ] && export D=1`, `A=1; export A`.
+const INNER_EXPORT_RE = /(?:^|[\s;&|(){}])export\s/;
+const DECLARE_EXPORT_RE = /^\s*(?:declare|typeset)\s+-[A-Za-z]*x/;
+const PEM_BEGIN = "-----BEGIN";
+const PEM_END = "-----END";
+const DIRENV_COMMANDS = new Set([
+    "dotenv", "dotenv_if_exists", "source_env", "source_env_if_exists", "source_up", "source_up_if_exists",
+    "source_url", "PATH_add", "path_add", "MANPATH_add", "PATH_rm", "path_rm", "use", "layout", "watch_file",
+    "watch_dir", "env_vars_required", "load_prefix", "fetchurl", "on_git_branch", "strict_env", "unstrict_env",
+]);
+/** Settings that describe this computer, not the repository. Exported by many `.envrc` files, never drafted. */
+const MACHINE_NAMES = new Set(["PATH", "MANPATH", "HOME", "SHELL", "PWD", "OLDPWD", "TMPDIR", "LANG", "VIRTUAL_ENV"]);
+const MACHINE_PREFIXES = ["LC_", "DIRENV_", "DYLD_", "OTEL_"];
+function isMachineSetting(name) {
+    return MACHINE_NAMES.has(name) || MACHINE_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/** The names an `.envrc` exports, sorted, with the line each was last exported on. Never a value. */
+export function scanEnvrc(text) {
+    const parsed = parseEnvrc(text);
+    return {
+        exported: parsed.exported.map(({ name, line, computed, inherited }) => ({ name, line, computed, inherited })),
+        skippedNames: parsed.skippedNames,
+        notRead: parsed.notRead,
+    };
+}
+/** Import only. The static literal each requested name is exported with; a computed value is absent. */
+export function envrcLiteralValues(text, names) {
+    const values = new Map();
+    for (const entry of parseEnvrc(text).exported) {
+        if (names.has(entry.name) && entry.literal !== undefined && entry.literal !== "")
+            values.set(entry.name, entry.literal);
+    }
+    return values;
+}
+function parseEnvrc(text) {
+    const lines = text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+    const exported = new Map();
+    const bare = new Map();
+    const skipped = new Set();
+    const notRead = [];
+    // Non-null while a value opened on an earlier line is still open; those lines are value material.
+    let open = null;
+    let openedOn = 0;
+    const record = (name, line, value) => {
+        if (isMachineSetting(name)) {
+            skipped.add(name);
+            return;
+        }
+        const literal = value === null ? bare.get(name) : value.literal;
+        const computed = value === null ? literal === undefined : value.literal === undefined && !value.empty;
+        const inherited = value === null && !bare.has(name);
+        exported.delete(name);
+        exported.set(name, { name, line, computed, inherited, literal });
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNo = i + 1;
+        if (open !== null) {
+            if (open.kind === "pem") {
+                if (line.includes(PEM_END))
+                    open = null;
+            }
+            else if (open.kind === "heredoc") {
+                if (line.trim() === open.word)
+                    open = null;
+            }
+            else if (open.kind === "quote") {
+                const close = closingIndex(line, open.quote, 0);
+                if (close >= 0) {
+                    open = null;
+                    // `"…\n…" ; export B=2`: the words after the closing quote are a command this reader skips.
+                    if (!isTrailingComment(line.slice(close + 1)))
+                        notRead.push({ line: lineNo, reason: "a command after a multi-line value" });
+                }
+            }
+            else if (!line.endsWith("\\"))
+                open = null;
+            continue;
+        }
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const heredoc = heredocMatch(line);
+        const exportMatch = EXPORT_RE.exec(line);
+        if (exportMatch) {
+            const rest = exportMatch[1].trim();
+            const assign = ASSIGN_RE.exec(rest);
+            if (assign) {
+                const value = readValue(assign[2]);
+                if (value.extra) {
+                    notRead.push({ line: lineNo, reason: "an export this reader does not follow" });
+                }
+                else {
+                    record(assign[1], lineNo, value);
+                }
+                open = heredoc ? { kind: "heredoc", word: heredoc[1] } : value.open;
+                if (open !== null)
+                    openedOn = lineNo;
+                continue;
+            }
+            const namesOnly = NAMES_ONLY_RE.exec(rest);
+            if (namesOnly) {
+                for (const name of namesOnly[1].split(/\s+/))
+                    record(name, lineNo, null);
+                continue;
+            }
+            notRead.push({ line: lineNo, reason: "an export this reader does not follow" });
+            if (heredoc)
+                open = { kind: "heredoc", word: heredoc[1] };
+            else if (line.endsWith("\\"))
+                open = { kind: "backslash" };
+            if (open !== null)
+                openedOn = lineNo;
+            continue;
+        }
+        const command = trimmed.split(/\s+/)[0];
+        if (DIRENV_COMMANDS.has(command)) {
+            notRead.push({ line: lineNo, reason: command });
+            continue;
+        }
+        if (DECLARE_EXPORT_RE.test(line)) {
+            notRead.push({ line: lineNo, reason: `${command} -x, which this reader does not follow` });
+            continue;
+        }
+        const bareAssign = BARE_ASSIGN_RE.exec(line);
+        if (bareAssign) {
+            const value = readValue(bareAssign[2]);
+            bare.set(bareAssign[1], value.extra ? undefined : value.literal);
+            if (value.extra && INNER_EXPORT_RE.test(line))
+                notRead.push({ line: lineNo, reason: "an export this reader does not follow" });
+            open = heredoc ? { kind: "heredoc", word: heredoc[1] } : value.open;
+            if (open !== null)
+                openedOn = lineNo;
+            continue;
+        }
+        if (INNER_EXPORT_RE.test(line))
+            notRead.push({ line: lineNo, reason: "an export this reader does not follow" });
+        if (heredoc)
+            open = { kind: "heredoc", word: heredoc[1] };
+        else if (line.endsWith("\\"))
+            open = { kind: "backslash" };
+        if (open !== null)
+            openedOn = lineNo;
+    }
+    if (open !== null && open.kind !== "backslash") {
+        // An unclosed quote, PEM block or heredoc swallowed every later line; say so instead of a short list.
+        notRead.push({ line: openedOn, reason: "a value that never closes; the lines after it were not read" });
+    }
+    return {
+        exported: [...exported.values()].filter((entry) => NAME_RE.test(entry.name)).sort((a, b) => a.name.localeCompare(b.name, "en")),
+        skippedNames: [...skipped].sort((a, b) => a.localeCompare(b, "en")),
+        notRead,
+    };
+}
+/** Find a heredoc operator outside quotes and comments. Substitutions have their own quote state. */
+function heredocMatch(line) {
+    const stack = [{ quote: null, end: null }];
+    for (let i = 0; i < line.length; i++) {
+        const state = stack.at(-1);
+        if (state === undefined)
+            return null;
+        const char = line[i];
+        if (state.quote === "'") {
+            if (char === "'")
+                state.quote = null;
+            continue;
+        }
+        if (char === "\\") {
+            i++;
+            continue;
+        }
+        if (char === '"') {
+            state.quote = state.quote === '"' ? null : '"';
+            continue;
+        }
+        if (char === "$" && line[i + 1] === "(") {
+            stack.push({ quote: null, end: ")" });
+            i++;
+            continue;
+        }
+        if (char === "`") {
+            if (state.end === "`" && state.quote === null)
+                stack.pop();
+            else
+                stack.push({ quote: null, end: "`" });
+            continue;
+        }
+        if (state.quote !== null)
+            continue;
+        if (char === "'")
+            state.quote = "'";
+        else if (char === "#" && (i === 0 || /[\s;|&()<>]/.test(line[i - 1] ?? "")))
+            return null;
+        else if (char === "(" && state.end === ")")
+            stack.push({ quote: null, end: ")" });
+        else if (char === ")" && state.end === ")")
+            stack.pop();
+        else if (char === "<" && line[i - 1] !== "<" && line[i + 2] !== "<") {
+            const match = HEREDOC_RE.exec(line.slice(i));
+            if (match)
+                return match;
+        }
+    }
+    return null;
+}
+function readValue(raw) {
+    if (raw.includes(PEM_BEGIN) && !raw.includes(PEM_END))
+        return { literal: undefined, empty: false, extra: false, open: { kind: "pem" } };
+    const first = raw[0];
+    if (first === "'" || first === '"') {
+        const close = closingIndex(raw, first, 1);
+        if (close < 0)
+            return { literal: undefined, empty: false, extra: false, open: { kind: "quote", quote: first } };
+        const inner = raw.slice(1, close);
+        const rest = raw.slice(close + 1);
+        const computed = first === '"' && /[$`\\]/.test(inner);
+        if (!isTrailingComment(rest)) {
+            return computed ? { literal: undefined, empty: false, extra: false, open: null } : { literal: undefined, empty: false, extra: true, open: null };
+        }
+        return { literal: computed ? undefined : inner, empty: inner === "", extra: false, open: null };
+    }
+    if (raw.endsWith("\\"))
+        return { literal: undefined, empty: false, extra: false, open: { kind: "backslash" } };
+    const space = raw.search(/\s/);
+    const word = space < 0 ? raw : raw.slice(0, space);
+    const rest = space < 0 ? "" : raw.slice(space);
+    if (word === "")
+        return { literal: undefined, empty: isTrailingComment(rest), extra: !isTrailingComment(rest), open: null };
+    const literal = UNQUOTED_LITERAL_RE.test(word) && !word.startsWith("~") ? word : undefined;
+    if (!isTrailingComment(rest)) {
+        // `$(gh auth token)` and backticks carry spaces of their own: still one computed value.
+        return /\$\(|`/.test(raw) ? { literal: undefined, empty: false, extra: false, open: null } : { literal: undefined, empty: false, extra: true, open: null };
+    }
+    return { literal, empty: false, extra: false, open: null };
+}
+function isTrailingComment(rest) {
+    const t = rest.trim();
+    return t === "" || (t.startsWith("#") && /^\s/.test(rest));
+}
+/** Index of the quote that closes a value opened before `from`, or -1. A double quote honours `\"`. */
+function closingIndex(text, quote, from) {
+    for (let i = from; i < text.length; i++) {
+        if (quote === '"' && text[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (text[i] === quote)
+            return i;
+    }
+    return -1;
+}

package/dist/env/settings-toml.js

@@ -61,6 +61,14 @@ export function validateSettingsToml(text) {
         ? { state: "invalid", errors }
         : { state: "valid", errors: [], variableNames };
 }
+/** The declared variables and their secret flags, or null unless the file passes `validateSettingsToml`.
+ *  Names and flags only: the check refuses a `value` key, so none can be read here. */
+export function readDeclaredVariables(text) {
+    if (validateSettingsToml(text).state !== "valid")
+        return null;
+    const parsed = parse(text);
+    return (parsed.environment?.variables ?? []).map((raw) => ({ name: String(raw.name), secret: raw.secret === true }));
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/env/shell-plan.js

@@ -14,7 +14,10 @@ const HOME = "/home/catalyst";
 export const ENV_SHELL_START_SCRIPT = [
     "set -u",
     'mode="$1"; shift',
-    `if [ "$#" -gt 0 ]; then mise install "$@" >&2 || exit ${START_EXIT_TOOLCHAIN}; fi`,
+    // Only a spec nothing installed satisfies is installed. `mise install node@22` resolves "22" against
+    // the online list and downloads the newest 22.x even when the image has an older 22.x, while
+    // `mise where` (and `mise exec`) prefer an installed match (CTC-6389).
+    `for spec in "$@"; do mise where "$spec" >/dev/null 2>&1 || mise install "$spec" >&2 || exit ${START_EXIT_TOOLCHAIN}; done`,
     'if [ "$mode" = check ]; then',
     '  for spec in "$@"; do printf \'toolchain\\t%s\\t%s\\n\' "$spec" "$(basename "$(mise where "$spec")")"; done',
     "  for name in ${CATALYST_ENV_NAMES:-}; do",