Skip to content

Build your personal knowledge base with Trilium Notes

14.8 KB
Raw Blame
/**
 * Locates and probes the bring-your-own-binary CLIs the agent providers drive
 * (Claude Code, GitHub Copilot, Google Antigravity, OpenAI Codex).
 *
 * A GUI-launched app does not inherit the user's shell environment: on macOS
 * launchd hands `Trilium.app` a bare `/usr/bin:/bin:/usr/sbin:/sbin`, and on
 * Linux a `.desktop` launcher is no better. Version managers (nvm, fnm, asdf,
 * volta) put their bin directory on PATH from an rc file, so the CLI that
 * `pnpm desktop:start` finds is invisible to the packaged build.
 *
 * So the inherited PATH is searched first, and only when that misses does the
 * user's login shell get asked for its own PATH. A hit there is adopted into
 * `process.env.PATH`, because the CLI subprocess needs it too — an npm shim
 * resolves its `node` through PATH.
 *
 * Inside a Flatpak, no CLI installed on the computer is visible. When the user
 * allows the app to talk to `org.freedesktop.Flatpak`, the CLI is looked up on
 * the host instead and started there through `flatpak-spawn --host`, by a
 * launcher script written into the data directory (see {@link buildHostLauncher}).
 */

import { getLog } from "@triliumnext/core";
import { execFile } from "child_process";
import { chmodSync, existsSync, mkdirSync, writeFileSync } from "fs";
import { t } from "i18next";
import path from "path";
import { promisify } from "util";

const execFileAsync = promisify(execFile);

/** Brackets the `env` dump so rc-file chatter can be discarded around it. */
const DELIMITER = "__TRILIUM_SHELL_ENV__";

/** Upper bound on the login shell's startup: rc files can source a lot. */
const LOGIN_SHELL_TIMEOUT_MS = 10000;

/** Upper bound on a `flatpak-spawn --host` call that only checks or looks something up. */
const HOST_LOOKUP_TIMEOUT_MS = 5000;

/** The `env` dump a login shell prints, delimited so rc-file chatter can be discarded. */
const ENV_DUMP_SCRIPT = `printf %s ${DELIMITER}; env; printf %s ${DELIMITER}`;

/**
 * The variables a host launcher passes from Trilium to the CLI. `flatpak-spawn --host` starts
 * the CLI with the session's environment, not Trilium's, so the variables the SDK and the
 * providers set (`CLAUDE_CODE_ENTRYPOINT`, `CODEX_HOME`, `GEMINI_HOME`) are passed explicitly.
 */
const HOST_ENV_PREFIXES = [ "ANTHROPIC_", "CLAUDE_", "CODEX_", "COPILOT_", "GEMINI_", "GH_", "GITHUB_" ];

/**
 * Finds `binary` on PATH, falling back to the login shell's PATH. Returns the
 * full path to the executable, or `undefined` if it is installed nowhere the
 * user's shell could reach it either. Inside a Flatpak that may start programs
 * on the host, returns a launcher for the host's `binary` instead.
 */
export async function findOnPath(binary: string): Promise<string | undefined> {
    if (process.env.FLATPAK_ID && await canReachFlatpakHost()) {
        return findOnFlatpakHost(binary);
    }

    const inherited = searchPath(process.env.PATH, binary);
    if (inherited) {
        return inherited;
    }

    const loginShellPath = await resolveLoginShellPath();
    if (!loginShellPath) {
        return undefined;
    }

    const found = searchPath(loginShellPath, binary);
    if (found) {
        process.env.PATH = mergePaths(process.env.PATH, loginShellPath);
        getLog().info(`Adopted PATH from the login shell to reach ${binary} at ${found}`);
    }
    return found;
}

/**
 * Why `cli` cannot be found when Trilium runs as a Flatpak that may not start programs on the
 * host, with the steps that allow it. `undefined` outside a Flatpak, or once the host is
 * reachable and the CLI is simply not installed there.
 */
export async function describeFlatpakSandbox(cli: string): Promise<string | undefined> {
    const appId = process.env.FLATPAK_ID;
    if (!appId || await canReachFlatpakHost()) {
        return undefined;
    }
    return t("llm_providers.flatpak_sandbox", {
        cli,
        grantCommand: `flatpak override --user --talk-name=org.freedesktop.Flatpak ${appId}`,
        revokeCommand: `flatpak override --user --no-talk-name=org.freedesktop.Flatpak ${appId}`
    });
}

/**
 * The script that starts `hostBinary` on the host from inside the Flatpak. It passes the
 * variables named by {@link HOST_ENV_PREFIXES}, and moves to the home directory when the
 * current one exists only in the sandbox, which `flatpak-spawn` would refuse to start in.
 * `hostPath` is the login shell's PATH, set when that is where the CLI was found.
 */
export function buildHostLauncher(hostBinary: string, hostPath?: string): string {
    const pathFlag = hostPath ? ` ${shellQuote(`--env=PATH=${hostPath}`)}` : "";
    const prefixes = HOST_ENV_PREFIXES.map((prefix) => `${prefix}*`).join("|");
    return `#!/bin/sh
# Written by Trilium: runs ${hostBinary} outside the Flatpak sandbox.
set -- ${shellQuote(hostBinary)} "$@"
for var in $(env | sed -n 's/^\\([A-Za-z_][A-Za-z0-9_]*\\)=.*/\\1/p'); do
    case "$var" in
        ${prefixes}) eval "set -- \\"--env=$var=\\\${$var}\\" \\"\\$@\\"" ;;
    esac
done
case "$PWD" in
    "$HOME" | "$HOME"/*) ;;
    *) cd "$HOME" || exit 1 ;;
esac
exec flatpak-spawn --host --watch-bus${pathFlag} "$@"
`;
}

/**
 * Memoize a binary probe: concurrent first calls share one run, and a failed
 * one is forgotten so a later install is picked up without a restart.
 */
export function cachedProbe(probe: () => Promise<string>): { resolve: () => Promise<string>; reset: () => void } {
    let cached: Promise<string> | undefined;
    return {
        resolve() {
            if (!cached) {
                cached = probe().catch((err: unknown) => {
                    cached = undefined;
                    throw err;
                });
            }
            return cached;
        },
        reset() {
            cached = undefined;
        }
    };
}

/**
 * Runs `binary --version` with stdin closed and resolves with everything it
 * printed, stdout before stderr. On failure, `failure` names the timeout or
 * carries execFile's own message for a spawn or exit failure.
 */
export function runVersionProbe(binary: string, timeoutMs: number): Promise<{ output: string; failure?: string }> {
    return new Promise((resolve) => {
        // `shell` is required for the .cmd/.bat shims npm creates on Windows —
        // Node refuses to spawn those directly (CVE-2024-27980). With a shell
        // the command line is not auto-quoted, so quote the path ourselves.
        const shell = needsShell(binary);
        const options = { timeout: timeoutMs, encoding: "utf8" as const, shell };
        const child = execFile(shell ? `"${binary}"` : binary, ["--version"], options, (err, stdout, stderr) => {
            const output = [stdout, stderr].map((text) => text.trim()).filter(Boolean).join("\n");
            if (!err) {
                resolve({ output });
            } else if (err.killed) {
                resolve({ output, failure: `did not exit within ${timeoutMs / 1000} seconds` });
            } else {
                // execFile's message already quotes stderr after the command.
                const failure = (err instanceof Error ? err.message : String(err)).trim();
                resolve({ output: stdout.trim(), failure });
            }
        });
        child.stdin?.end();
    });
}

/**
 * Whether the binary is an npm `.cmd`/`.bat` shim that can only be launched
 * through a shell. Used by the version probe and the ACP spawn.
 */
export function needsShell(binary: string): boolean {
    return /\.(cmd|bat)$/i.test(binary);
}

/** For tests: forget the login shell's PATH so the next call re-reads it. */
export function resetLoginShellPathCache(): void {
    cachedLoginShellPath = undefined;
    cachedHostReachable = undefined;
    cachedHostLoginShellPath = undefined;
}

/**
 * Extracts the `PATH` value from the delimited `env` dump a login shell wrote.
 * Returns `undefined` when the shell exited before both delimiters were
 * printed, or when it reported no PATH at all.
 */
export function extractPathFromShellEnv(shellOutput: string): string | undefined {
    const start = shellOutput.indexOf(DELIMITER);
    const end = shellOutput.lastIndexOf(DELIMITER);
    if (start === -1 || end <= start) {
        return undefined;
    }

    const env = shellOutput.slice(start + DELIMITER.length, end);
    return /^PATH=(.+)$/m.exec(env)?.[1];
}

function searchPath(rawPath: string | undefined, binary: string): string | undefined {
    // On Windows, npm-installed packages create a bare extensionless file (a
    // POSIX bash script for Git Bash/WSL) alongside the real .cmd/.exe shims.
    // The bash script can't be executed by Node's execFile/spawn, so we must
    // try the Windows-native extensions first and skip the bare name entirely.
    const extensions = process.platform === "win32" ? [".cmd", ".exe", ".bat"] : [""];
    for (const dir of (rawPath ?? "").split(path.delimiter)) {
        if (!dir) {
            continue;
        }
        for (const ext of extensions) {
            const candidate = path.join(dir, binary + ext);
            if (existsSync(candidate)) {
                return candidate;
            }
        }
    }
    return undefined;
}

/**
 * The in-flight/successful login shell read. A failed read is cached too: the
 * shell is unlikely to answer differently before a restart, and every miss
 * costs a full shell startup.
 */
let cachedLoginShellPath: Promise<string | undefined> | undefined;

function resolveLoginShellPath(): Promise<string | undefined> {
    if (!cachedLoginShellPath) {
        cachedLoginShellPath = readLoginShellPath();
    }
    return cachedLoginShellPath;
}

async function readLoginShellPath(): Promise<string | undefined> {
    // Windows has no login-shell profile that PATH is built from, and $SHELL is
    // how the shell to ask is named.
    const shell = process.platform === "win32" ? undefined : process.env.SHELL?.trim();
    if (!shell) {
        return undefined;
    }

    // `printf` and `env` are external commands, so the dump reads the same under
    // bash, zsh, fish and dash. `-i` matters: nvm and fnm are commonly set up in
    // an interactive-only rc file (.zshrc, .bashrc).
    const args = ["-ilc", ENV_DUMP_SCRIPT];
    try {
        const { stdout } = await execFileAsync(shell, args, {
            timeout: LOGIN_SHELL_TIMEOUT_MS,
            encoding: "utf8",
            maxBuffer: 1024 * 1024,
            // A shell that believes it drives a terminal can redraw a prompt or
            // start an instant-prompt plugin over the output we parse.
            env: { ...process.env, TERM: "dumb" }
        });
        return extractPathFromShellEnv(stdout);
    } catch (err) {
        const detail = err instanceof Error ? err.message : String(err);
        getLog().info(`Could not read PATH from the login shell "${shell}" (${detail})`);
        return undefined;
    }
}

/** Keeps the inherited entries ahead of the login shell's, without duplicates. */
function mergePaths(inherited: string | undefined, loginShell: string): string {
    const entries = [
        ...(inherited ?? "").split(path.delimiter),
        ...loginShell.split(path.delimiter)
    ];
    return [...new Set(entries.filter((entry) => entry))].join(path.delimiter);
}

/** Whether `flatpak-spawn --host` works, which takes the user's `--talk-name` override. */
let cachedHostReachable: Promise<boolean> | undefined;

function canReachFlatpakHost(): Promise<boolean> {
    if (!cachedHostReachable) {
        cachedHostReachable = execFileAsync("flatpak-spawn", [ "--host", "true" ], { timeout: HOST_LOOKUP_TIMEOUT_MS })
            .then(() => true, (err: unknown) => {
                const detail = err instanceof Error ? err.message : String(err);
                getLog().info(`Running as a Flatpak that cannot start programs on the host (${detail})`);
                return false;
            });
    }
    return cachedHostReachable;
}

/**
 * Looks `binary` up on the host's PATH, then on its login shell's, and writes a launcher for it.
 * The lookup runs `command -v` in the host's `sh`, since no host path can be tested from inside
 * the sandbox.
 */
async function findOnFlatpakHost(binary: string): Promise<string | undefined> {
    const onSessionPath = await commandOnHost(binary);
    if (onSessionPath) {
        return writeHostLauncher(binary, onSessionPath);
    }

    const loginShellPath = await resolveHostLoginShellPath();
    const onLoginShellPath = loginShellPath ? await commandOnHost(binary, loginShellPath) : undefined;
    if (!onLoginShellPath) {
        return undefined;
    }
    getLog().info(`Found ${binary} at ${onLoginShellPath} on the PATH of the host's login shell`);
    return writeHostLauncher(binary, onLoginShellPath, loginShellPath);
}

async function commandOnHost(binary: string, hostPath?: string): Promise<string | undefined> {
    const pathFlag = hostPath ? [ `--env=PATH=${hostPath}` ] : [];
    try {
        const { stdout } = await execFileAsync("flatpak-spawn", [
            "--host", ...pathFlag, "sh", "-c", "command -v \"$1\"", "sh", binary
        ], { timeout: HOST_LOOKUP_TIMEOUT_MS, encoding: "utf8" });
        const found = stdout.trim();
        // `command -v` prints a bare name for a builtin, function or alias.
        return path.posix.isAbsolute(found) ? found : undefined;
    } catch {
        return undefined;
    }
}

/** The host login shell's PATH; a failed read is cached too, as for {@link resolveLoginShellPath}. */
let cachedHostLoginShellPath: Promise<string | undefined> | undefined;

function resolveHostLoginShellPath(): Promise<string | undefined> {
    if (!cachedHostLoginShellPath) {
        cachedHostLoginShellPath = readHostLoginShellPath();
    }
    return cachedHostLoginShellPath;
}

async function readHostLoginShellPath(): Promise<string | undefined> {
    // The sandbox sets SHELL to its own /bin/sh, so the host's `sh` reads the session's SHELL.
    try {
        const { stdout } = await execFileAsync("flatpak-spawn", [
            "--host", "--env=TERM=dumb", "sh", "-c", "exec \"${SHELL:-/bin/sh}\" -ilc \"$1\"", "sh", ENV_DUMP_SCRIPT
        ], { timeout: LOGIN_SHELL_TIMEOUT_MS, encoding: "utf8", maxBuffer: 1024 * 1024 });
        return extractPathFromShellEnv(stdout);
    } catch (err) {
        const detail = err instanceof Error ? err.message : String(err);
        getLog().info(`Could not read PATH from the host's login shell (${detail})`);
        return undefined;
    }
}

async function writeHostLauncher(binary: string, hostBinary: string, hostPath?: string): Promise<string> {
    // Imported here: data_dir resolves the data directory as soon as it loads.
    const { default: dataDirs } = await import("../../data_dir.js");
    const dir = path.resolve(dataDirs.TRILIUM_DATA_DIR, "flatpak-host");
    mkdirSync(dir, { recursive: true });
    const launcher = path.join(dir, binary);
    writeFileSync(launcher, buildHostLauncher(hostBinary, hostPath));
    chmodSync(launcher, 0o755);
    return launcher;
}

function shellQuote(value: string): string {
    return `'${value.replaceAll("'", `'\\''`)}'`;
}