Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
20.5 KB
Raw Blame
// What a session's project expects from its environment, for
// `environment.toolchain` (see toolchain.ts): the names in its .env files
// (values only when clearly not secret), the environment variable names its
// code reads, the host (OS release, WSL, CPU) and the shell (name, version,
// version managers, PATH with the home directory and user name removed).
//
// Nothing here spawns a version-manager shim. Every value that could hold a
// secret is left out; when in doubt, the value is omitted and only the name
// is kept.

import { gitChildEnv } from "./git-env.js";
import { execFile } from "node:child_process";
import { readFile, readdir, lstat } from "node:fs/promises";
import { cpus, homedir, release as osRelease, userInfo } from "node:os";
import nodePath from "node:path";

import { gitSkipReason } from "./command-guard.js";
import { redactionRaw } from "./context/redact-policy.js";

export const MAX_ENV_FILES = 50;
export const MAX_ENV_KEYS_PER_FILE = 500;
export const MAX_ENV_FILE_BYTES = 256 * 1024;
export const MAX_ENV_NAMES_READ = 500;
export const MAX_PATH_ENTRIES = 64;
const MAX_ENV_VALUE_CHARS = 100;
const MAX_WALK_DEPTH = 6;
const MAX_WALK_DIRECTORIES = 5_000;
const MAX_SCANNED_FILES = 20_000;
const MAX_SCANNED_FILE_BYTES = 512 * 1024;
const MAX_SCANNED_TOTAL_BYTES = 32 * 1024 * 1024;

/** Folders never searched for .env files or source: dependencies, environments, build output. */
const SKIPPED_DIRS = new Set([
  "node_modules", ".git", ".hg", ".svn", ".venv", "venv", "env", ".tox", ".nox", "__pycache__", ".mypy_cache",
  ".pytest_cache", ".ruff_cache", "dist", "build", "out", "target", "vendor", ".next", ".nuxt", ".cache", ".turbo",
  "coverage", ".gradle", ".idea", ".terraform", "bower_components", "Pods", ".dart_tool", ".pnpm-store", ".yarn",
]);

export type EnvKey = { name: string; value?: string };
export type EnvFile = { path: string; keys: EnvKey[]; keys_truncated?: boolean };

export type SecretChecks = {
  /** The capture's secret-name rule (workspace-sync isSecretAssignmentKey). */
  isSecretName?: (name: string) => boolean;
  /** The capture's text scrub; a value it would change is never kept. */
  scrubText?: (value: string) => string;
  /** The capture's path denylist; a denied file's code is never scanned. */
  isDenied?: (path: string) => boolean;
};

// --- .env files ------------------------------------------------------------------

const ENV_FILE = /^\.env(?:\..+)?$/;
/** Documented placeholders, normal project files: not environment files. */
const ENV_TEMPLATE = /\.(?:example|sample|template)$/i;
// Names whose value is never kept, on top of the capture's own secret rule:
// anything that might be a credential, a personal detail or an identifier.
const SECRETISH_NAME = /KEY|SECRET|TOKEN|PASS|PWD|AUTH|CRED|PRIVATE|CERT|SALT|SESSION|COOKIE|SIGN|DSN|HASH|SEED|OTP|PIN|CODE|ACCOUNT|USER|LOGIN|EMAIL|MAIL|PHONE|TENANT|WEBHOOK|ENCRYPT|BEARER|JWT|API/i;
const BOOLEAN = /^(?:true|false|yes|no|on|off)$/i;
const NUMBER = /^-?\d{1,6}(?:\.\d{1,4})?$/;
const LOCAL_URL = /^(?:https?|wss?|postgres(?:ql)?|mysql|mariadb|redis|rediss|mongodb|amqp|nats|grpc):\/\/(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0|host\.docker\.internal)(?::\d{1,5})?(?:\/[A-Za-z0-9._~\/-]*)?$/i;
const SAFE_WORDS = new Set([
  "development", "dev", "production", "prod", "staging", "stage", "test", "testing", "local", "preview", "qa", "ci",
  "sandbox", "release", "debug", "info", "warn", "warning", "error", "trace", "fatal", "silent", "verbose", "none",
  "utc", "json", "text", "pretty", "auto", "always", "never", "enabled", "disabled", "localhost", "0.0.0.0",
  "127.0.0.1", "memory", "disk", "sqlite", "postgres", "postgresql", "mysql", "redis", "docker", "node", "python",
  "http", "https", "light", "dark", "default", "strict", "lax", "inline", "headless",
]);

/**
 * The value of `name=raw` when it is clearly not a secret: a boolean, a short
 * number (a port), a well-known enum word (`NODE_ENV=development`) or a
 * localhost URL without credentials. Undefined otherwise, and always for a
 * secret-looking name or a value the scrub would touch.
 */
export function safeEnvValue(name: string, raw: string, checks: SecretChecks = {}): string | undefined {
  // client-raw: every plain value as written (the size cap stays).
  if (redactionRaw()) return rawEnvValue(raw);
  if (checks.isSecretName?.(name) || SECRETISH_NAME.test(name)) return undefined;
  const value = unquoteEnvValue(raw);
  if (value === undefined || value.length > MAX_ENV_VALUE_CHARS) return undefined;
  const safe = value === ""
    || BOOLEAN.test(value)
    || NUMBER.test(value)
    || SAFE_WORDS.has(value.toLowerCase())
    || (LOCAL_URL.test(value) && !value.includes("@"));
  if (!safe) return undefined;
  if (checks.scrubText && checks.scrubText(value) !== value) return undefined;
  return value;
}

/** The first `quote` in `text` from `from` that is not escaped (an even run of backslashes before it, none included); -1 when none. */
function closingQuote(text: string, quote: string, from: number): number {
  for (let at = text.indexOf(quote, from); at >= 0; at = text.indexOf(quote, at + 1)) {
    let slashes = 0;
    while (at - slashes - 1 >= 0 && text[at - slashes - 1] === "\\") slashes += 1;
    if (slashes % 2 === 0) return at;
  }
  return -1;
}

/** client-raw: a dotenv right-hand side byte for byte as written (its quotes, `$`, `\\` and inner quotes included). */
function rawEnvValue(raw: string): string {
  return raw.trim();
}

/** The literal value of a dotenv right-hand side, or undefined when it is not one plain value. */
function unquoteEnvValue(raw: string): string | undefined {
  const text = raw.trim();
  const quote = text[0];
  if (quote === '"' || quote === "'" || quote === "`") {
    const end = text.indexOf(quote, 1);
    if (end < 0) return undefined;
    const rest = text.slice(end + 1).trim();
    if (rest && !rest.startsWith("#")) return undefined;
    const inner = text.slice(1, end);
    return /\$\{?|\\/.test(inner) ? undefined : inner;
  }
  // An inline comment starts at a `#` after whitespace.
  const value = text.replace(/\s+#.*$/, "").trim();
  return /[$\\\s"'`]/.test(value) ? undefined : value;
}

/** The keys of one dotenv text, in order, each with its value only when safeEnvValue keeps it. */
export function parseEnvFile(text: string, checks: SecretChecks = {}): { keys: EnvKey[]; truncated: boolean } {
  const keys: EnvKey[] = [];
  const seen = new Set<string>();
  let openQuote: string | null = null;
  let truncated = false;
  // client-raw: a multi-line quoted value (a PEM key) is kept whole.
  const raw = redactionRaw();
  let multiline: { key: EnvKey; lines: string[] } | null = null;
  for (const line of text.split(/\r?\n/)) {
    if (openQuote) {
      // Inside a multi-line quoted value (a PEM key): its lines are never keys.
      const end = raw ? closingQuote(line, openQuote, 0) : line.indexOf(openQuote);
      if (multiline) {
        // Every line as written, the closing one whole (its quote included).
        multiline.lines.push(line);
        if (end >= 0) multiline.key.value = multiline.lines.join("\n");
      }
      if (end >= 0) {
        openQuote = null;
        multiline = null;
      }
      continue;
    }
    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*=(.*)$/.exec(line);
    if (!match) continue;
    const name = match[1]!;
    const rhs = match[2]!.trim();
    const quote = rhs[0];
    if ((quote === '"' || quote === "'" || quote === "`") && (raw ? closingQuote(rhs, quote, 1) : rhs.indexOf(quote, 1)) < 0) openQuote = quote;
    if (seen.has(name)) continue;
    if (keys.length >= MAX_ENV_KEYS_PER_FILE) {
      truncated = true;
      continue;
    }
    seen.add(name);
    if (raw && openQuote) {
      const key: EnvKey = { name };
      multiline = { key, lines: [rhs] };
      keys.push(key);
      continue;
    }
    const value = openQuote ? undefined : safeEnvValue(name, rhs, checks);
    keys.push(value === undefined ? { name } : { name, value });
  }
  return { keys, truncated };
}

/** Every .env file under `root` (template files excluded), as project-relative paths. */
export async function findEnvFiles(root: string): Promise<string[]> {
  const found: string[] = [];
  let directories = 0;
  const walk = async (dir: string, depth: number): Promise<void> => {
    if (found.length >= MAX_ENV_FILES || directories >= MAX_WALK_DIRECTORIES) return;
    directories += 1;
    let entries;
    try {
      entries = await readdir(dir, { withFileTypes: true });
    } catch {
      return;
    }
    entries.sort((a, b) => a.name.localeCompare(b.name));
    for (const entry of entries) {
      if (found.length >= MAX_ENV_FILES) return;
      if (entry.isFile() && ENV_FILE.test(entry.name) && !ENV_TEMPLATE.test(entry.name)) {
        found.push(nodePath.relative(root, nodePath.join(dir, entry.name)).split(nodePath.sep).join("/"));
      }
    }
    if (depth >= MAX_WALK_DEPTH) return;
    for (const entry of entries) {
      if (entry.isDirectory() && !SKIPPED_DIRS.has(entry.name) && !entry.name.startsWith(".")) await walk(nodePath.join(dir, entry.name), depth + 1);
    }
  };
  await walk(root, 0);
  return found;
}

export async function collectEnvFiles(root: string, checks: SecretChecks = {}): Promise<EnvFile[]> {
  const files: EnvFile[] = [];
  for (const path of await findEnvFiles(root)) {
    const full = nodePath.join(root, path);
    try {
      const info = await lstat(full);
      if (!info.isFile() || info.size > MAX_ENV_FILE_BYTES) {
        files.push({ path, keys: [], keys_truncated: info.isFile() });
        continue;
      }
      const { keys, truncated } = parseEnvFile(await readFile(full, "utf8"), checks);
      files.push(truncated ? { path, keys, keys_truncated: true } : { path, keys });
    } catch {
      // Unreadable: left out.
    }
  }
  return files;
}

// --- environment variable names the code reads -----------------------------------

const NAME = "([A-Za-z_][A-Za-z0-9_]{0,127})";
const Q = "[\"'`]";
const ENV_READS = new RegExp([
  `process\\.env\\.${NAME}`,
  `process\\.env\\[\\s*${Q}${NAME}${Q}\\s*\\]`,
  `import\\.meta\\.env\\.${NAME}`,
  `Bun\\.env\\.${NAME}`,
  `Deno\\.env\\.get\\(\\s*${Q}${NAME}${Q}`,
  `os\\.environ\\[\\s*${Q}${NAME}${Q}\\s*\\]`,
  `os\\.environ\\.get\\(\\s*${Q}${NAME}${Q}`,
  `getenv\\(\\s*${Q}${NAME}${Q}`,
  `env::var(?:_os)?\\(\\s*"${NAME}"`,
  `env!\\(\\s*"${NAME}"`,
  `os\\.(?:Getenv|LookupEnv)\\(\\s*"${NAME}"`,
  `System\\.getenv\\(\\s*"${NAME}"`,
  `\\bENV(?:\\.fetch\\(\\s*|\\[\\s*)${Q}${NAME}${Q}`,
  `\\$_ENV\\[\\s*${Q}${NAME}${Q}`,
  `Environment\\.GetEnvironmentVariable\\(\\s*"${NAME}"`,
].join("|"), "g");
const CODE_EXTENSIONS = new Set([
  ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".mts", ".cts", ".vue", ".svelte", ".astro", ".py", ".pyi", ".rs",
  ".go", ".java", ".kt", ".kts", ".scala", ".groovy", ".rb", ".php", ".cs", ".fs", ".c", ".cc", ".cpp", ".cxx",
  ".h", ".hpp", ".swift", ".ex", ".exs", ".dart", ".lua", ".jl", ".r",
]);

/** The environment variable names in `text` read through a known accessor. */
export function envNamesIn(text: string, into: Set<string> = new Set()): Set<string> {
  ENV_READS.lastIndex = 0;
  for (const match of text.matchAll(ENV_READS)) {
    const name = match.slice(1).find((group) => group !== undefined);
    if (name) into.add(name);
  }
  return into;
}

async function projectSourceFiles(root: string, checks: SecretChecks): Promise<string[]> {
  const keep = (path: string) => CODE_EXTENSIONS.has(nodePath.extname(path).toLowerCase()) && !checks.isDenied?.(path)
    && !path.split("/").some((part) => SKIPPED_DIRS.has(part));
  if (!(await gitSkipReason())) {
    const listed = await new Promise<string[] | null>((resolvePromise) => {
      execFile("git", ["-C", root, "ls-files", "-co", "--exclude-standard", "-z"], {
        encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 10_000, windowsHide: true,
        env: gitChildEnv({ GIT_OPTIONAL_LOCKS: "0" }),
      }, (error, stdout) => resolvePromise(error ? null : Buffer.from(stdout).toString("utf8").split("\0").filter(Boolean)));
    });
    if (listed) return listed.filter(keep).slice(0, MAX_SCANNED_FILES);
  }
  const files: string[] = [];
  let directories = 0;
  const walk = async (dir: string, depth: number): Promise<void> => {
    if (files.length >= MAX_SCANNED_FILES || directories >= MAX_WALK_DIRECTORIES || depth > MAX_WALK_DEPTH * 2) return;
    directories += 1;
    let entries;
    try {
      entries = await readdir(dir, { withFileTypes: true });
    } catch {
      return;
    }
    for (const entry of entries) {
      const full = nodePath.join(dir, entry.name);
      if (entry.isDirectory()) {
        if (!SKIPPED_DIRS.has(entry.name) && !entry.name.startsWith(".")) await walk(full, depth + 1);
      } else if (entry.isFile()) {
        const path = nodePath.relative(root, full).split(nodePath.sep).join("/");
        if (keep(path)) files.push(path);
      }
    }
  };
  await walk(root, 0);
  return files.slice(0, MAX_SCANNED_FILES);
}

/** The environment variable names the project's code reads, sorted, capped at MAX_ENV_NAMES_READ. */
export async function collectEnvNamesRead(root: string, checks: SecretChecks = {}): Promise<{ names: string[]; truncated: boolean }> {
  const names = new Set<string>();
  let total = 0;
  for (const path of await projectSourceFiles(root, checks)) {
    if (total >= MAX_SCANNED_TOTAL_BYTES) break;
    try {
      const full = nodePath.join(root, path);
      const info = await lstat(full);
      if (!info.isFile() || info.size > MAX_SCANNED_FILE_BYTES) continue;
      total += info.size;
      envNamesIn(await readFile(full, "utf8"), names);
    } catch {
      // Gone or unreadable.
    }
  }
  const sorted = [...names].sort();
  return { names: sorted.slice(0, MAX_ENV_NAMES_READ), truncated: sorted.length > MAX_ENV_NAMES_READ };
}

// --- host ------------------------------------------------------------------------

export type SystemInfo = {
  distro_id?: string;
  distro_version?: string;
  distro_name?: string;
  macos_version?: string;
  macos_build?: string;
  windows_build?: string;
  wsl: boolean;
  cpu_model?: string;
  cpu_logical_cores?: number;
};

/** Fields of an os-release file. */
export function parseOsRelease(text: string): Record<string, string> {
  const fields: Record<string, string> = {};
  for (const line of text.split(/\r?\n/)) {
    const match = /^([A-Z_]+)=(.*)$/.exec(line.trim());
    if (match) fields[match[1]!] = match[2]!.replace(/^(["'])(.*)\1$/, "$2");
  }
  return fields;
}

/** `sw_vers` output: ProductVersion and BuildVersion. */
export function parseSwVers(text: string): { version?: string; build?: string } {
  const field = (key: string) => new RegExp(`^${key}:\\s*(\\S+)`, "m").exec(text)?.[1];
  return { version: field("ProductVersion"), build: field("BuildVersion") };
}

export function isWsl(procVersion: string | null, env: NodeJS.ProcessEnv = process.env): boolean {
  return Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP) || /microsoft|wsl/i.test(procVersion ?? "");
}

export type RunText = (file: string, args: string[]) => Promise<string | null>;

export async function systemInfo(run: RunText, platform: NodeJS.Platform = process.platform): Promise<SystemInfo> {
  const info: SystemInfo = { wsl: false };
  const clip = (value: string | undefined, limit = 128) => (value ? value.trim().slice(0, limit) || undefined : undefined);
  if (platform === "linux") {
    const osRelease = await readFile("/etc/os-release", "utf8").catch(() => readFile("/usr/lib/os-release", "utf8").catch(() => ""));
    const fields = parseOsRelease(osRelease);
    info.distro_id = clip(fields.ID, 64);
    info.distro_version = clip(fields.VERSION_ID, 64);
    info.distro_name = clip(fields.PRETTY_NAME);
    info.wsl = isWsl(await readFile("/proc/version", "utf8").catch(() => null));
  } else if (platform === "darwin") {
    // /usr/bin/sw_vers is part of the OS, not a Command Line Tools shim.
    const output = await run("/usr/bin/sw_vers", []);
    const { version, build } = parseSwVers(output ?? "");
    info.macos_version = clip(version, 32);
    info.macos_build = clip(build, 32);
  } else if (platform === "win32") {
    info.windows_build = clip(osRelease().split(".")[2], 16);
  }
  try {
    const list = cpus();
    info.cpu_model = clip(list[0]?.model?.replace(/\s+/g, " "));
    info.cpu_logical_cores = list.length || undefined;
  } catch {
    // No CPU information in this runtime.
  }
  for (const key of Object.keys(info) as (keyof SystemInfo)[]) if (info[key] === undefined) delete info[key];
  return info;
}

// --- shell -------------------------------------------------------------------------

export type ShellInfo = {
  name?: string;
  version?: string;
  version_managers: string[];
  path: string[];
};

const MANAGER_ENV: Record<string, string[]> = {
  nvm: ["NVM_DIR", "NVM_BIN"],
  fnm: ["FNM_DIR", "FNM_MULTISHELL_PATH"],
  volta: ["VOLTA_HOME"],
  pyenv: ["PYENV_ROOT", "PYENV_SHELL", "PYENV_VERSION"],
  asdf: ["ASDF_DIR", "ASDF_DATA_DIR"],
  mise: ["MISE_SHELL", "__MISE_ACTIVATE", "RTX_SHELL"],
  rbenv: ["RBENV_ROOT", "RBENV_SHELL"],
  conda: ["CONDA_PREFIX", "CONDA_EXE"],
  sdkman: ["SDKMAN_DIR"],
};
const MANAGER_PATH: Record<string, RegExp> = {
  nvm: /[\\/]\.nvm[\\/]/,
  fnm: /fnm_multishells|[\\/]fnm[\\/]/,
  volta: /[\\/]\.volta[\\/]/,
  pyenv: /[\\/]\.pyenv[\\/]|pyenv-win/,
  asdf: /[\\/]\.asdf[\\/]/,
  mise: /[\\/]mise[\\/](shims|installs)/,
  rbenv: /[\\/]\.rbenv[\\/]/,
  conda: /[\\/](ana|mini)conda\d*[\\/]|miniforge|mambaforge/i,
  sdkman: /[\\/]\.sdkman[\\/]/,
};

/** Version managers in use, from environment variable names and PATH entries only (no shim is run). */
export function versionManagers(env: NodeJS.ProcessEnv = process.env, pathEntries: string[] = []): string[] {
  const found: string[] = [];
  for (const [name, keys] of Object.entries(MANAGER_ENV)) {
    if (keys.some((key) => env[key]) || pathEntries.some((entry) => MANAGER_PATH[name]!.test(entry))) found.push(name);
  }
  return found;
}

/**
 * PATH as a list: the home directory becomes `~`, and the user name, wherever
 * else it appears, becomes `<user>`. Capped at MAX_PATH_ENTRIES.
 */
export function sanitizedPath(pathValue: string, options: { home?: string; user?: string; platform?: NodeJS.Platform } = {}): string[] {
  const platform = options.platform ?? process.platform;
  const home = (options.home ?? safeHome()).replace(/[\\/]+$/, "");
  const user = options.user ?? safeUser();
  const separator = platform === "win32" ? ";" : ":";
  const entries: string[] = [];
  for (const raw of pathValue.split(separator)) {
    let entry = raw.trim().replace(/^"(.*)"$/, "$1");
    if (!entry) continue;
    if (home && (platform === "win32" ? entry.toLowerCase().startsWith(home.toLowerCase()) : entry.startsWith(home))) {
      const rest = entry.slice(home.length);
      if (rest === "" || rest.startsWith("/") || rest.startsWith("\\")) entry = `~${rest}`;
    }
    // client-raw: the account name stays as written (the home as `~` above stays).
    if (user && !redactionRaw()) {
      const escaped = user.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
      // A short name is replaced only as a whole path component.
      entry = user.length >= 3
        ? entry.replace(new RegExp(escaped, "gi"), "<user>")
        : entry.replace(new RegExp(`(^|[\\\\/])${escaped}(?=[\\\\/]|$)`, "gi"), "$1<user>");
    }
    entries.push(entry.slice(0, 256));
    if (entries.length >= MAX_PATH_ENTRIES) break;
  }
  return entries;
}

function safeHome(): string {
  try {
    return homedir();
  } catch {
    return "";
  }
}

function safeUser(): string {
  try {
    return userInfo().username;
  } catch {
    return process.env.USER ?? process.env.USERNAME ?? "";
  }
}

const VERSIONED_SHELLS = new Set(["bash", "zsh", "fish", "ksh", "tcsh", "nu", "elvish", "xonsh"]);

export async function shellInfo(run: RunText, options: { env?: NodeJS.ProcessEnv; platform?: NodeJS.Platform } = {}): Promise<ShellInfo> {
  const env = options.env ?? process.env;
  const platform = options.platform ?? process.platform;
  const shellPath = (platform === "win32" ? env.ComSpec ?? env.COMSPEC : env.SHELL)?.trim();
  const name = shellPath ? nodePath.basename(shellPath.replace(/\\/g, "/")).replace(/\.exe$/i, "").toLowerCase() : undefined;
  const path = sanitizedPath((platform === "win32" ? env.Path ?? env.PATH : env.PATH) ?? "", { platform });
  const info: ShellInfo = { version_managers: versionManagers(env, path), path };
  if (name) info.name = name.slice(0, 32);
  if (shellPath && name && VERSIONED_SHELLS.has(name) && nodePath.isAbsolute(shellPath)) {
    const output = await run(shellPath, ["--version"]);
    const line = output?.split(/\r?\n/).map((part) => part.trim()).find(Boolean);
    if (line) info.version = line.slice(0, 200);
  }
  return info;
}