Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
import { $ } from 'bun';
import { existsSync } from 'node:fs';
import { homedir } from 'node:os';
import { resolve } from 'node:path';
import { getRepoRoot } from './config';
/**
* Result of executing a command.
*/
export interface ExecResult {
exitCode: number;
stdout: string;
stderr: string;
}
/**
* Options for exec function.
*/
interface ExecOptions {
cwd?: string;
env?: Record<string, string | undefined>;
}
/**
* Docker bind mount configuration.
*/
export interface DockerMount {
source: string;
target: string;
readonly?: boolean;
}
/**
* Docker named volume mount configuration.
*/
export interface DockerVolumeMount {
/** Named volume name (must be created with `docker volume create` first) */
volume: string;
/** Container path to mount the volume at */
target: string;
/** Whether to mount read-only */
readonly?: boolean;
}
/**
* Options for running a Node container.
*/
export interface RunNodeContainerOptions {
imageTag: string;
cmd: string | string[];
cwd?: string;
mounts?: DockerMount[];
/** Named volume mounts (volumes must be created beforehand with `docker volume create`) */
volumes?: DockerVolumeMount[];
env?: Record<string, string | undefined>;
labels?: Record<string, string>;
name?: string;
/** Whether to auto-remove the container after exit (default: true) */
remove?: boolean;
}
/**
* Options for ensureNodeImage.
*/
export interface EnsureNodeImageOptions {
repoRoot?: string;
dockerfilePath?: string;
}
/**
* Options for checkDocker.
*/
export interface CheckDockerOptions {
repoRoot?: string;
}
/**
* Escapes a shell argument for safe use in Bun shell raw strings.
*/
function escapeShellArg(arg: string): string {
// Single-quote the arg and escape any embedded single quotes
return `'${arg.replace(/'/g, "'\\''")}'`;
}
/**
* Creates default Docker labels for Node.js e2e images.
*/
function defaultNodeLabels(nodeVersion?: string): Record<string, string> {
const labels: Record<string, string> = {
'composio.e2e': 'true',
'composio.runtime': 'node',
};
if (nodeVersion) {
labels['composio.node_version'] = nodeVersion;
}
return labels;
}
/**
* Creates default Docker labels for Deno e2e images.
*/
function defaultDenoLabels(denoVersion?: string): Record<string, string> {
const labels: Record<string, string> = {
'composio.e2e': 'true',
'composio.runtime': 'deno',
};
if (denoVersion) {
labels['composio.deno_version'] = denoVersion;
}
return labels;
}
/**
* Creates default Docker labels for CLI e2e images.
*/
function defaultCliLabels(cliVersion?: string): Record<string, string> {
const labels: Record<string, string> = {
'composio.e2e': 'true',
'composio.runtime': 'cli',
};
if (cliVersion) {
labels['composio.cli_version'] = cliVersion;
}
return labels;
}
/**
* Converts labels object to Docker CLI arguments array.
*/
function labelsToArgs(labels: Record<string, string> = {}): string[] {
const args: string[] = [];
for (const [k, v] of Object.entries(labels)) {
args.push('--label', `${k}=${v}`);
}
return args;
}
/**
* Converts environment variables to Docker CLI arguments array.
* Skips undefined values to avoid passing empty env vars to Docker.
*/
function envToArgs(env: Record<string, string | undefined> = {}): string[] {
const args: string[] = [];
for (const [k, v] of Object.entries(env)) {
if (v === undefined) continue;
args.push('-e', `${k}=${v}`);
}
return args;
}
/**
* Adds a bind mount for host ~/.composio into container home.
* This allows E2E jobs to inject `user_data.json` once per job.
*/
function addHostComposioMount(dockerArgs: string[], containerComposioPath: string): void {
const hostComposioPath = resolve(homedir(), '.composio');
if (!existsSync(hostComposioPath)) {
return;
}
dockerArgs.push(
'--mount',
`type=bind,src=${hostComposioPath},dst=${containerComposioPath},readonly`
);
}
/**
* Executes a command and captures stdout/stderr using Bun shell.
*/
async function exec(cmd: string, args: string[], options: ExecOptions = {}): Promise<ExecResult> {
const { cwd, env } = options;
const escapedArgs = args.map(escapeShellArg).join(' ');
let shell = $`${{ raw: cmd }} ${{ raw: escapedArgs }}`.nothrow().quiet();
if (cwd) {
shell = shell.cwd(cwd);
}
if (env) {
shell = shell.env({ ...process.env, ...env });
}
const result = await shell;
return {
exitCode: result.exitCode,
stdout: result.stdout.toString(),
stderr: result.stderr.toString(),
};
}
/**
* Checks if Docker is available.
*/
export async function checkDocker(options: CheckDockerOptions = {}): Promise<ExecResult> {
const repoRoot = options.repoRoot ?? getRepoRoot();
return exec('docker', ['info'], { cwd: repoRoot });
}
// bun and pnpm are installed inside the images from mise.toml/mise.lock, so only the
// matrixed runtimes (node, deno) need to be resolved on the host and threaded as build args.
async function getMiseVersion(tool: 'node' | 'deno', repoRoot: string): Promise<string> {
const result = await exec('mise', ['current', tool], { cwd: repoRoot });
const version = result.stdout.trim();
if (result.exitCode !== 0 || !version) {
throw new Error(
`Failed to resolve ${tool} version from mise.toml: ${result.stderr || result.stdout}`
);
}
return version;
}
function getMajorVersion(version: string): string {
return version.split('.')[0] ?? version;
}
/**
* Creates image tag for a given Node version.
*/
function imageTagForNodeVersion(nodeVersion: string): string {
return `composio-e2e-node:${nodeVersion}`;
}
/**
* Parses Node version from an image tag.
*/
function parseNodeVersionFromImageTag(imageTag: string): string | undefined {
const match = /^composio-e2e-node:(.+)$/.exec(imageTag);
return match?.[1];
}
/**
* Ensures a Docker image exists for the given Node version, building it if necessary.
*/
export async function ensureNodeImage(
nodeVersion: string,
options: EnsureNodeImageOptions = {}
): Promise<string> {
if (!nodeVersion || typeof nodeVersion !== 'string') {
throw new Error(`ensureNodeImage(${nodeVersion}): nodeVersion must be a non-empty string`);
}
const repoRoot = options.repoRoot ?? getRepoRoot();
const dockerfilePath =
options.dockerfilePath ?? resolve(repoRoot, 'ts/e2e-tests/_utils/Dockerfile.node');
const imageTag = imageTagForNodeVersion(nodeVersion);
const inspect = await exec('docker', ['image', 'inspect', imageTag], { cwd: repoRoot });
if (inspect.exitCode === 0) {
return imageTag;
}
const buildArgs = [
'build',
'-f',
dockerfilePath,
'--build-arg',
`NODE_VERSION=${nodeVersion}`,
...labelsToArgs(defaultNodeLabels(nodeVersion)),
'-t',
imageTag,
repoRoot,
];
const built = await exec('docker', buildArgs, { cwd: repoRoot });
if (built.exitCode !== 0) {
// Handle race condition: concurrent builds may fail because another build
// already tagged the image. If the image now exists, treat it as success.
const output = built.stderr || built.stdout;
if (output.includes('already exists')) {
const recheck = await exec('docker', ['image', 'inspect', imageTag], { cwd: repoRoot });
if (recheck.exitCode === 0) {
return imageTag;
}
}
const err = new Error(`Failed to build Docker image ${imageTag}`);
(err as Error & { cause: Error }).cause = new Error(output);
throw err;
}
return imageTag;
}
/**
* Runs a command in a Node Docker container.
*/
export async function runNodeContainer(options: RunNodeContainerOptions): Promise<ExecResult> {
const { imageTag, cmd, cwd, mounts, volumes, env, labels, name, remove } = options;
// Validate imageTag is provided, as it determines which Docker image to run.
if (!imageTag || typeof imageTag !== 'string') {
throw new Error('runNodeContainer({ imageTag, ... }): imageTag must be a non-empty string');
}
const nodeVersion = parseNodeVersionFromImageTag(imageTag);
const dockerArgs = ['run'];
if (remove !== false) {
dockerArgs.push('--rm');
}
dockerArgs.push(...labelsToArgs({ ...defaultNodeLabels(nodeVersion), ...(labels ?? {}) }));
// Assign a custom container name for easier identification and cleanup.
if (name) {
dockerArgs.push('--name', name);
}
// Set the working directory inside the container, defaulting relative paths to /app.
if (cwd) {
const containerCwd = cwd.startsWith('/') ? cwd : `/app/${cwd}`;
dockerArgs.push('--workdir', containerCwd);
}
addHostComposioMount(dockerArgs, '/root/.composio');
// Pass environment variables to the container for runtime configuration.
dockerArgs.push(...envToArgs(env));
// Configure bind mounts to share host directories with the container.
if (mounts) {
for (const m of mounts) {
// Ensure each mount has required source and target paths.
if (!m?.source || !m?.target) {
throw new Error('runNodeContainer(...): each mount must have { source, target }');
}
const parts = [`type=bind`, `src=${m.source}`, `dst=${m.target}`];
// Mark mount as read-only to prevent container from modifying host files.
if (m.readonly) parts.push('readonly');
dockerArgs.push('--mount', parts.join(','));
}
}
// Configure named volume mounts for sharing state between container runs.
if (volumes) {
for (const v of volumes) {
// Ensure each volume mount has required volume name and target path.
if (!v?.volume || !v?.target) {
throw new Error('runNodeContainer(...): each volume must have { volume, target }');
}
const parts = [`type=volume`, `src=${v.volume}`, `dst=${v.target}`];
// Mark mount as read-only if specified.
if (v.readonly) parts.push('readonly');
dockerArgs.push('--mount', parts.join(','));
}
}
dockerArgs.push(imageTag);
// Handle cmd as array for direct execution without shell interpretation.
if (Array.isArray(cmd)) {
dockerArgs.push(...cmd.map(String));
// Preserve the image's configured PATH instead of resetting it in a login shell.
} else if (typeof cmd === 'string' && cmd.length > 0) {
dockerArgs.push('sh', '-c', cmd);
} else {
throw new Error('runNodeContainer({ cmd, ... }): cmd must be a non-empty string or string[]');
}
return exec('docker', dockerArgs);
}
// ============================================================================
// Deno Docker utilities
// ============================================================================
/**
* Options for running a Deno container.
*/
export interface RunDenoContainerOptions {
imageTag: string;
cmd: string | string[];
cwd?: string;
mounts?: DockerMount[];
/** Named volume mounts (volumes must be created beforehand with `docker volume create`) */
volumes?: DockerVolumeMount[];
env?: Record<string, string | undefined>;
labels?: Record<string, string>;
name?: string;
/** Whether to auto-remove the container after exit (default: true) */
remove?: boolean;
}
/**
* Options for ensureDenoImage.
*/
export interface EnsureDenoImageOptions {
repoRoot?: string;
dockerfilePath?: string;
}
/**
* Creates image tag for a given Deno version.
*/
function imageTagForDenoVersion(denoVersion: string): string {
return `composio-e2e-deno:${denoVersion}`;
}
/**
* Parses Deno version from an image tag.
*/
function parseDenoVersionFromImageTag(imageTag: string): string | undefined {
const match = /^composio-e2e-deno:(.+)$/.exec(imageTag);
return match?.[1];
}
/**
* Ensures a Docker image exists for the given Deno version, building it if necessary.
*/
export async function ensureDenoImage(
denoVersion: string,
options: EnsureDenoImageOptions = {}
): Promise<string> {
if (!denoVersion || typeof denoVersion !== 'string') {
throw new Error(`ensureDenoImage(${denoVersion}): denoVersion must be a non-empty string`);
}
const repoRoot = options.repoRoot ?? getRepoRoot();
const dockerfilePath =
options.dockerfilePath ?? resolve(repoRoot, 'ts/e2e-tests/_utils/Dockerfile.deno');
const imageTag = imageTagForDenoVersion(denoVersion);
const nodeVersion = await getMiseVersion('node', repoRoot);
const inspect = await exec('docker', ['image', 'inspect', imageTag], { cwd: repoRoot });
if (inspect.exitCode === 0) {
return imageTag;
}
const buildArgs = [
'build',
'-f',
dockerfilePath,
'--build-arg',
`DENO_VERSION=${denoVersion}`,
'--build-arg',
`NODE_MAJOR=${getMajorVersion(nodeVersion)}`,
...labelsToArgs(defaultDenoLabels(denoVersion)),
'-t',
imageTag,
repoRoot,
];
const built = await exec('docker', buildArgs, { cwd: repoRoot });
if (built.exitCode !== 0) {
// Handle race condition: concurrent builds may fail because another build
// already tagged the image. If the image now exists, treat it as success.
const output = built.stderr || built.stdout;
if (output.includes('already exists')) {
const recheck = await exec('docker', ['image', 'inspect', imageTag], { cwd: repoRoot });
if (recheck.exitCode === 0) {
return imageTag;
}
}
const err = new Error(`Failed to build Docker image ${imageTag}`);
(err as Error & { cause: Error }).cause = new Error(output);
throw err;
}
return imageTag;
}
/**
* Runs a command in a Deno Docker container.
*/
export async function runDenoContainer(options: RunDenoContainerOptions): Promise<ExecResult> {
const { imageTag, cmd, cwd, mounts, volumes, env, labels, name, remove } = options;
// Validate imageTag is provided, as it determines which Docker image to run.
if (!imageTag || typeof imageTag !== 'string') {
throw new Error('runDenoContainer({ imageTag, ... }): imageTag must be a non-empty string');
}
const denoVersion = parseDenoVersionFromImageTag(imageTag);
const dockerArgs = ['run'];
if (remove !== false) {
dockerArgs.push('--rm');
}
dockerArgs.push(...labelsToArgs({ ...defaultDenoLabels(denoVersion), ...(labels ?? {}) }));
// Assign a custom container name for easier identification and cleanup.
if (name) {
dockerArgs.push('--name', name);
}
// Set the working directory inside the container, defaulting relative paths to /app.
if (cwd) {
const containerCwd = cwd.startsWith('/') ? cwd : `/app/${cwd}`;
dockerArgs.push('--workdir', containerCwd);
}
addHostComposioMount(dockerArgs, '/root/.composio');
// Pass environment variables to the container for runtime configuration.
dockerArgs.push(...envToArgs(env));
// Configure bind mounts to share host directories with the container.
if (mounts) {
for (const m of mounts) {
// Ensure each mount has required source and target paths.
if (!m?.source || !m?.target) {
throw new Error('runDenoContainer(...): each mount must have { source, target }');
}
const parts = [`type=bind`, `src=${m.source}`, `dst=${m.target}`];
// Mark mount as read-only to prevent container from modifying host files.
if (m.readonly) parts.push('readonly');
dockerArgs.push('--mount', parts.join(','));
}
}
// Configure named volume mounts for sharing state between container runs.
if (volumes) {
for (const v of volumes) {
// Ensure each volume mount has required volume name and target path.
if (!v?.volume || !v?.target) {
throw new Error('runDenoContainer(...): each volume must have { volume, target }');
}
const parts = [`type=volume`, `src=${v.volume}`, `dst=${v.target}`];
// Mark mount as read-only if specified.
if (v.readonly) parts.push('readonly');
dockerArgs.push('--mount', parts.join(','));
}
}
dockerArgs.push(imageTag);
// Handle cmd as array for direct execution without shell interpretation.
if (Array.isArray(cmd)) {
dockerArgs.push(...cmd.map(String));
// Preserve the image's configured PATH instead of resetting it in a login shell.
// Callers must explicitly use 'deno run --allow-all <file>' when running Deno scripts.
} else if (typeof cmd === 'string' && cmd.length > 0) {
dockerArgs.push('sh', '-c', cmd);
} else {
throw new Error('runDenoContainer({ cmd, ... }): cmd must be a non-empty string or string[]');
}
return exec('docker', dockerArgs);
}
// ============================================================================
// CLI Docker utilities
// ============================================================================
/**
* Options for running a CLI container.
*/
export interface RunCliContainerOptions {
imageTag: string;
cmd: string | string[];
cwd?: string;
mounts?: DockerMount[];
/** Named volume mounts (volumes must be created beforehand with `docker volume create`) */
volumes?: DockerVolumeMount[];
env?: Record<string, string | undefined>;
labels?: Record<string, string>;
name?: string;
/** Whether to auto-remove the container after exit (default: true) */
remove?: boolean;
}
/**
* Options for ensureCliImage.
*/
export interface EnsureCliImageOptions {
repoRoot?: string;
dockerfilePath?: string;
}
/**
* Creates image tag for a given CLI version.
*/
function imageTagForCliVersion(cliVersion: string): string {
return `composio-e2e-cli:${cliVersion}`;
}
/**
* Parses CLI version from an image tag.
*/
function parseCliVersionFromImageTag(imageTag: string): string | undefined {
const match = /^composio-e2e-cli:(.+)$/.exec(imageTag);
return match?.[1];
}
/**
* Ensures a Docker image exists for the given CLI version, building it if necessary.
*/
export async function ensureCliImage(
cliVersion: string,
options: EnsureCliImageOptions = {}
): Promise<string> {
if (!cliVersion || typeof cliVersion !== 'string') {
throw new Error(`ensureCliImage(${cliVersion}): cliVersion must be a non-empty string`);
}
const repoRoot = options.repoRoot ?? getRepoRoot();
const dockerfilePath =
options.dockerfilePath ?? resolve(repoRoot, 'ts/e2e-tests/_utils/Dockerfile.cli');
const imageTag = imageTagForCliVersion(cliVersion);
const nodeVersion = await getMiseVersion('node', repoRoot);
const inspect = await exec('docker', ['image', 'inspect', imageTag], { cwd: repoRoot });
if (inspect.exitCode === 0) {
return imageTag;
}
const buildArgs = [
'build',
'-f',
dockerfilePath,
'--build-arg',
`CLI_VERSION=${cliVersion}`,
'--build-arg',
`NODE_VERSION=${nodeVersion}`,
...labelsToArgs(defaultCliLabels(cliVersion)),
'-t',
imageTag,
repoRoot,
];
const built = await exec('docker', buildArgs, { cwd: repoRoot });
if (built.exitCode !== 0) {
const output = built.stderr || built.stdout;
if (output.includes('already exists')) {
const recheck = await exec('docker', ['image', 'inspect', imageTag], { cwd: repoRoot });
if (recheck.exitCode === 0) {
return imageTag;
}
}
const err = new Error(`Failed to build Docker image ${imageTag}`);
(err as Error & { cause: Error }).cause = new Error(output);
throw err;
}
return imageTag;
}
/**
* Runs a command in a CLI Docker container.
*/
export async function runCliContainer(options: RunCliContainerOptions): Promise<ExecResult> {
const { imageTag, cmd, cwd, mounts, volumes, env, labels, name, remove } = options;
if (!imageTag || typeof imageTag !== 'string') {
throw new Error('runCliContainer({ imageTag, ... }): imageTag must be a non-empty string');
}
const cliVersion = parseCliVersionFromImageTag(imageTag);
const dockerArgs = ['run'];
if (remove !== false) {
dockerArgs.push('--rm');
}
dockerArgs.push(...labelsToArgs({ ...defaultCliLabels(cliVersion), ...(labels ?? {}) }));
if (name) {
dockerArgs.push('--name', name);
}
if (cwd) {
const containerCwd = cwd.startsWith('/') ? cwd : `/app/${cwd}`;
dockerArgs.push('--workdir', containerCwd);
}
// Allow CLI e2e suites to reach host-side mock servers deterministically.
dockerArgs.push('--add-host', 'host.docker.internal:host-gateway');
addHostComposioMount(dockerArgs, '/tmp/.composio');
dockerArgs.push(...envToArgs(env));
if (mounts) {
for (const m of mounts) {
if (!m?.source || !m?.target) {
throw new Error('runCliContainer(...): each mount must have { source, target }');
}
const parts = [`type=bind`, `src=${m.source}`, `dst=${m.target}`];
if (m.readonly) parts.push('readonly');
dockerArgs.push('--mount', parts.join(','));
}
}
if (volumes) {
for (const v of volumes) {
if (!v?.volume || !v?.target) {
throw new Error('runCliContainer(...): each volume must have { volume, target }');
}
const parts = [`type=volume`, `src=${v.volume}`, `dst=${v.target}`];
if (v.readonly) parts.push('readonly');
dockerArgs.push('--mount', parts.join(','));
}
}
dockerArgs.push(imageTag);
if (Array.isArray(cmd)) {
dockerArgs.push(...cmd.map(String));
} else if (typeof cmd === 'string' && cmd.length > 0) {
// Use -c (not -lc) for busybox sh compatibility in scratch images
dockerArgs.push('sh', '-c', cmd);
} else {
throw new Error('runCliContainer({ cmd, ... }): cmd must be a non-empty string or string[]');
}
return exec('docker', dockerArgs);
}
// ============================================================================
// CLI installer Docker utilities
// ============================================================================
export type InstallShell = 'bash' | 'zsh' | 'fish';
export type InstallPlatform = 'linux/amd64' | 'linux/arm64';
export interface EnsureInstallImageOptions {
repoRoot?: string;
dockerfilePath?: string;
platform?: InstallPlatform;
}
export interface InstallImage {
imageTag: string;
platform: InstallPlatform;
}
export interface RunInstallContainerOptions {
imageTag: string;
shell: InstallShell;
platform: InstallPlatform;
cmd: string[];
env?: Record<string, string | undefined>;
labels?: Record<string, string>;
}
function imageTagForInstallShell(shell: InstallShell): string {
return `composio-e2e-install:${shell}`;
}
function defaultInstallLabels(shell: InstallShell): Record<string, string> {
return {
'composio.e2e': 'true',
'composio.runtime': 'cli-install',
'composio.install_shell': shell,
};
}
export async function ensureInstallImage(
shell: InstallShell,
options: EnsureInstallImageOptions = {}
): Promise<InstallImage> {
if (shell !== 'bash' && shell !== 'zsh' && shell !== 'fish') {
throw new Error(`ensureInstallImage(${shell}): shell must be bash, zsh, or fish`);
}
const repoRoot = options.repoRoot ?? getRepoRoot();
const dockerfilePath =
options.dockerfilePath ?? resolve(repoRoot, 'ts/e2e-tests/_utils/Dockerfile.install');
const platform = options.platform ?? (process.arch === 'arm64' ? 'linux/arm64' : 'linux/amd64');
const architecture = platform === 'linux/arm64' ? 'arm64' : 'amd64';
const imageTag = imageTagForInstallShell(shell);
const inspect = await exec(
'docker',
['image', 'inspect', '--format', '{{.Architecture}}', imageTag],
{ cwd: repoRoot }
);
if (inspect.exitCode === 0 && inspect.stdout.trim() === architecture) {
return { imageTag, platform };
}
const built = await exec(
'docker',
[
'build',
'--platform',
platform,
'-f',
dockerfilePath,
'--build-arg',
`INSTALL_SHELL=${shell}`,
...labelsToArgs(defaultInstallLabels(shell)),
'-t',
imageTag,
repoRoot,
],
{ cwd: repoRoot }
);
if (built.exitCode !== 0) {
// Handle race condition: concurrent builds may fail because another build
// already tagged the image. If the image now exists, treat it as success.
const output = built.stderr || built.stdout;
if (output.includes('already exists')) {
const recheck = await exec(
'docker',
['image', 'inspect', '--format', '{{.Architecture}}', imageTag],
{ cwd: repoRoot }
);
if (recheck.exitCode === 0 && recheck.stdout.trim() === architecture) {
return { imageTag, platform };
}
}
const err = new Error(`Failed to build Docker image ${imageTag}`);
(err as Error & { cause: Error }).cause = new Error(output);
throw err;
}
return { imageTag, platform };
}
export async function runInstallContainer(
options: RunInstallContainerOptions
): Promise<ExecResult> {
const { imageTag, shell, platform, cmd, env, labels } = options;
if (!Array.isArray(cmd) || cmd.length === 0) {
throw new Error('runInstallContainer({ cmd, ... }): cmd must be a non-empty array');
}
const dockerArgs = [
'run',
'--rm',
'--platform',
platform,
...labelsToArgs({ ...defaultInstallLabels(shell), ...(labels ?? {}) }),
'--add-host',
'host.docker.internal:host-gateway',
];
dockerArgs.push(...envToArgs(env));
// Installer tests intentionally do not mount the host's ~/.composio directory.
dockerArgs.push(imageTag, ...cmd.map(String));
return exec('docker', dockerArgs);
}