wind-agent-cli 1.37.2

package/server/modules/cli/sandbox.service.ts

@@ -0,0 +1,413 @@
+import path from 'node:path';
+
+import type {
+  CliFileSystem,
+  CliOutput,
+  SandboxCommandService,
+} from '@/shared/types.js';
+import { terminalTextStyles } from '@/shared/utils.js';
+
+type SandboxServiceDependencies = {
+  fileSystem: Pick<CliFileSystem, 'pathExists'>;
+  output: CliOutput;
+  homeDirectory: string;
+  runSandboxCommand(argumentsList: string[], inheritOutput?: boolean): string;
+  spawnDetachedSandbox(argumentsList: string[]): void;
+  wait(milliseconds: number): Promise<void>;
+};
+
+type SandboxOptions = {
+  subcommand: 'create' | 'ls' | 'stop' | 'start' | 'rm' | 'logs' | 'help';
+  workspace: string | null;
+  agent: string;
+  name: string | null;
+  port: number;
+  template: string;
+  environmentVariables: string[];
+};
+
+const SANDBOX_TEMPLATES: Record<string, string> = {
+  claude: 'docker.io/cloudcliai/sandbox:claude-code',
+  codex: 'docker.io/cloudcliai/sandbox:codex',
+};
+
+const SANDBOX_SECRETS: Record<string, string> = {
+  claude: 'anthropic',
+  codex: 'openai',
+};
+
+function parseSandboxArguments(argumentsList: string[], homeDirectory: string): SandboxOptions {
+  const parsedOptions: Omit<SandboxOptions, 'subcommand' | 'template'> & {
+    subcommand: SandboxOptions['subcommand'] | null;
+    template: string | null;
+  } = {
+    subcommand: null,
+    workspace: null,
+    agent: 'claude',
+    name: null,
+    port: 3001,
+    template: null,
+    environmentVariables: [],
+  };
+  const subcommands: SandboxOptions['subcommand'][] = [
+    'ls',
+    'stop',
+    'start',
+    'rm',
+    'logs',
+    'help',
+  ];
+
+  for (let argumentIndex = 0; argumentIndex < argumentsList.length; argumentIndex += 1) {
+    const argument = argumentsList[argumentIndex];
+    if (argumentIndex === 0 && subcommands.includes(argument as SandboxOptions['subcommand'])) {
+      parsedOptions.subcommand = argument as SandboxOptions['subcommand'];
+    } else if (argument === '--agent' || argument === '-a') {
+      parsedOptions.agent = argumentsList[++argumentIndex];
+    } else if (argument === '--name' || argument === '-n') {
+      parsedOptions.name = argumentsList[++argumentIndex];
+    } else if (argument === '--port') {
+      parsedOptions.port = Number.parseInt(argumentsList[++argumentIndex], 10);
+    } else if (argument === '--template' || argument === '-t') {
+      parsedOptions.template = argumentsList[++argumentIndex];
+    } else if (argument === '--env' || argument === '-e') {
+      parsedOptions.environmentVariables.push(argumentsList[++argumentIndex]);
+    } else if (!argument.startsWith('-')) {
+      if (!parsedOptions.subcommand) {
+        parsedOptions.workspace = argument;
+      } else {
+        parsedOptions.name = argument;
+      }
+    }
+  }
+
+  const subcommand = parsedOptions.subcommand ?? 'create';
+  const expandedWorkspace = parsedOptions.workspace?.replace(/^~/, homeDirectory) ?? null;
+  const name = parsedOptions.name
+    ?? (expandedWorkspace ? path.basename(path.resolve(expandedWorkspace)) : null);
+  const template = parsedOptions.template
+    ?? SANDBOX_TEMPLATES[parsedOptions.agent]
+    ?? SANDBOX_TEMPLATES.claude;
+
+  return { ...parsedOptions, subcommand, name, template };
+}
+
+function readCommandError(error: unknown): string {
+  if (!(error instanceof Error)) {
+    return String(error);
+  }
+
+  const commandError = error as Error & {
+    stdout?: string | Buffer;
+    stderr?: string | Buffer;
+  };
+  return String(commandError.stdout || commandError.stderr || commandError.message || '');
+}
+
+function showSandboxHelp(output: CliOutput): void {
+  output.log(`
+${terminalTextStyles.bright('CloudCLI Sandbox')} — Run CloudCLI inside Docker Sandboxes
+
+Usage:
+  wacli sandbox <workspace>            Create and start a sandbox
+  wacli sandbox <subcommand> [name]    Manage sandboxes
+
+Subcommands:
+  ${terminalTextStyles.bright('(default)')}    Create a sandbox and start the web UI
+  ${terminalTextStyles.bright('ls')}           List all sandboxes
+  ${terminalTextStyles.bright('start')}        Restart a stopped sandbox and re-launch the web UI
+  ${terminalTextStyles.bright('stop')}         Stop a sandbox (preserves state)
+  ${terminalTextStyles.bright('rm')}           Remove a sandbox
+  ${terminalTextStyles.bright('logs')}         Show CloudCLI server logs
+  ${terminalTextStyles.bright('help')}         Show this help
+
+Options:
+  -a, --agent <agent>       Agent to use: claude, codex (default: claude)
+  -n, --name <name>         Sandbox name (default: derived from workspace folder)
+  -t, --template <image>    Custom template image
+  -e, --env <KEY=VALUE>     Set environment variable (repeatable)
+      --port <port>         Host port for the web UI (default: 3001)
+
+Examples:
+  $ wacli sandbox ~/my-project
+  $ wacli sandbox ~/my-project --agent codex --port 8080
+  $ wacli sandbox ~/my-project --env SERVER_PORT=8080 --env HOST=0.0.0.0
+  $ wacli sandbox ls
+  $ wacli sandbox stop my-project
+  $ wacli sandbox start my-project
+  $ wacli sandbox rm my-project
+
+Prerequisites:
+  1. Install sbx CLI: https://docs.docker.com/ai/sandboxes/get-started/
+  2. Authenticate and store your API key:
+       sbx login
+       sbx secret set -g anthropic   # for Claude
+       sbx secret set -g openai      # for Codex
+
+Advanced usage:
+  For branch mode, multiple workspaces, memory limits, network policies,
+  or passing prompts to the agent, use sbx directly with the template:
+
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/my-project --branch my-feature
+    sbx run --template docker.io/cloudcliai/sandbox:claude-code claude ~/project ~/libs:ro --memory 8g
+
+  Full Docker Sandboxes docs: https://docs.docker.com/ai/sandboxes/usage/
+`);
+}
+
+function requireSandboxName(options: SandboxOptions, output: CliOutput): string | null {
+  if (options.name) {
+    return options.name;
+  }
+
+  output.error(`\n${terminalTextStyles.error('❌')} Sandbox name required: wacli sandbox ${options.subcommand} <name>\n`);
+  return null;
+}
+
+function publishSandboxPort(
+  options: SandboxOptions,
+  dependencies: SandboxServiceDependencies,
+): boolean {
+  const sandboxName = options.name as string;
+  dependencies.output.log(`${terminalTextStyles.info('▶')} Forwarding port ${options.port} → 3001...`);
+  try {
+    dependencies.runSandboxCommand(
+      ['ports', sandboxName, '--publish', `${options.port}:3001`],
+    );
+    return true;
+  } catch (error) {
+    const errorMessage = readCommandError(error);
+    if (!errorMessage.includes('address already in use')) {
+      throw error;
+    }
+
+    const alternativePort = options.port + 1;
+    dependencies.output.log(
+      `${terminalTextStyles.warn('⚠')}  Port ${options.port} in use, trying ${alternativePort}...`,
+    );
+    try {
+      dependencies.runSandboxCommand(
+        ['ports', sandboxName, '--publish', `${alternativePort}:3001`],
+      );
+      options.port = alternativePort;
+      return true;
+    } catch {
+      dependencies.output.error(
+        `${terminalTextStyles.error('❌')} Ports ${options.port} and ${alternativePort} both in use. Use --port to specify a free port.`,
+      );
+      return false;
+    }
+  }
+}
+
+/**
+ * Creates the Sandbox command service used by the CLI composition root and
+ * focused unit tests. Filesystem, subprocess, clock, home, and output access are
+ * all required adapters so the service has no production singleton fallbacks.
+ */
+export function createSandboxCommandService(
+  dependencies: SandboxServiceDependencies,
+): SandboxCommandService {
+  return {
+    async execute(argumentsList) {
+      const options = parseSandboxArguments(argumentsList, dependencies.homeDirectory);
+      if (options.subcommand === 'help') {
+        showSandboxHelp(dependencies.output);
+        return 0;
+      }
+
+      if (options.name && !/^[\w-]+$/.test(options.name)) {
+        dependencies.output.error(
+          `\n${terminalTextStyles.error('❌')} Invalid sandbox name: ${options.name}`,
+        );
+        dependencies.output.log('   Names may only contain letters, numbers, hyphens, and underscores.\n');
+        return 1;
+      }
+
+      try {
+        dependencies.runSandboxCommand(['version']);
+      } catch {
+        dependencies.output.error(
+          `\n${terminalTextStyles.error('❌')} ${terminalTextStyles.bright('sbx')} CLI not found.\n`,
+        );
+        dependencies.output.log(`   Install it from: ${terminalTextStyles.info('https://docs.docker.com/ai/sandboxes/get-started/')}`);
+        dependencies.output.log(`   Then run: ${terminalTextStyles.bright('sbx login')}`);
+        dependencies.output.log(`   And store your API key: ${terminalTextStyles.bright('sbx secret set -g anthropic')}\n`);
+        return 1;
+      }
+
+      switch (options.subcommand) {
+        case 'ls':
+          dependencies.runSandboxCommand(['ls'], true);
+          return 0;
+
+        case 'stop':
+        case 'rm': {
+          const sandboxName = requireSandboxName(options, dependencies.output);
+          if (!sandboxName) {
+            return 1;
+          }
+          dependencies.runSandboxCommand([options.subcommand, sandboxName], true);
+          return 0;
+        }
+
+        case 'logs': {
+          const sandboxName = requireSandboxName(options, dependencies.output);
+          if (!sandboxName) {
+            return 1;
+          }
+          try {
+            dependencies.runSandboxCommand(
+              ['exec', sandboxName, 'bash', '-c', 'cat /tmp/cloudcli-ui.log'],
+              true,
+            );
+          } catch (error) {
+            dependencies.output.error(
+              `\n${terminalTextStyles.error('❌')} Could not read logs: ${readCommandError(error) || 'Is the sandbox running?'}\n`,
+            );
+          }
+          return 0;
+        }
+
+        case 'start': {
+          const sandboxName = requireSandboxName(options, dependencies.output);
+          if (!sandboxName) {
+            return 1;
+          }
+          dependencies.output.log(
+            `\n${terminalTextStyles.info('▶')} Starting sandbox ${terminalTextStyles.bright(sandboxName)}...`,
+          );
+          dependencies.spawnDetachedSandbox(['run', sandboxName]);
+          await dependencies.wait(5_000);
+          dependencies.output.log(`${terminalTextStyles.info('▶')} Launching CloudCLI web server...`);
+          dependencies.runSandboxCommand([
+            'exec',
+            sandboxName,
+            'bash',
+            '-c',
+            'nohup wacli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 & disown',
+          ]);
+          if (!publishSandboxPort(options, dependencies)) {
+            return 1;
+          }
+          dependencies.output.log(`\n${terminalTextStyles.ok('✔')} ${terminalTextStyles.bright('CloudCLI is ready!')}`);
+          dependencies.output.log(`  ${terminalTextStyles.info('→')} ${terminalTextStyles.bright(`http://localhost:${options.port}`)}\n`);
+          return 0;
+        }
+
+        case 'create': {
+          if (!options.workspace) {
+            dependencies.output.error(
+              `\n${terminalTextStyles.error('❌')} Workspace path required: wacli sandbox <path>\n`,
+            );
+            dependencies.output.log(`   Example: ${terminalTextStyles.bright('wacli sandbox ~/my-project')}\n`);
+            return 1;
+          }
+
+          const workspace = options.workspace.startsWith('~')
+            ? options.workspace.replace(/^~/, dependencies.homeDirectory)
+            : path.resolve(options.workspace);
+          if (!dependencies.fileSystem.pathExists(workspace)) {
+            dependencies.output.error(
+              `\n${terminalTextStyles.error('❌')} Workspace path not found: ${terminalTextStyles.dim(workspace)}\n`,
+            );
+            return 1;
+          }
+
+          const sandboxName = options.name as string;
+          const secret = SANDBOX_SECRETS[options.agent] || 'anthropic';
+          try {
+            const secretList = dependencies.runSandboxCommand(['secret', 'ls']);
+            if (!secretList.includes(secret)) {
+              dependencies.output.error(
+                `\n${terminalTextStyles.error('❌')} No ${terminalTextStyles.bright(secret)} API key found.\n`,
+              );
+              dependencies.output.log(`   Run: ${terminalTextStyles.bright(`sbx secret set -g ${secret}`)}\n`);
+              return 1;
+            }
+          } catch {
+            // Older sbx versions may not expose `secret ls`; creation can still
+            // proceed and let sbx report a credential error itself.
+          }
+
+          dependencies.output.log(`\n${terminalTextStyles.bright('CloudCLI Sandbox')}`);
+          dependencies.output.log(terminalTextStyles.dim('─'.repeat(50)));
+          dependencies.output.log(`  Agent:     ${terminalTextStyles.info(options.agent)} ${terminalTextStyles.dim(`(${secret} credentials)`)}`);
+          dependencies.output.log(`  Workspace: ${terminalTextStyles.dim(workspace)}`);
+          dependencies.output.log(`  Name:      ${terminalTextStyles.dim(sandboxName)}`);
+          dependencies.output.log(`  Template:  ${terminalTextStyles.dim(options.template)}`);
+          dependencies.output.log(`  Port:      ${terminalTextStyles.dim(String(options.port))}`);
+          if (options.environmentVariables.length > 0) {
+            dependencies.output.log(`  Env:       ${terminalTextStyles.dim(options.environmentVariables.join(', '))}`);
+          }
+          dependencies.output.log(terminalTextStyles.dim('─'.repeat(50)));
+
+          dependencies.output.log(
+            `\n${terminalTextStyles.info('▶')} Creating sandbox ${terminalTextStyles.bright(sandboxName)}...`,
+          );
+          dependencies.spawnDetachedSandbox([
+            'run',
+            '--template',
+            options.template,
+            '--name',
+            sandboxName,
+            options.agent,
+            workspace,
+          ]);
+          await dependencies.wait(5_000);
+
+          if (options.environmentVariables.length > 0) {
+            dependencies.output.log(`${terminalTextStyles.info('▶')} Setting environment variables...`);
+            const validEnvironmentVariables = options.environmentVariables
+              .filter((environmentVariable) => /^\w+=.+$/.test(environmentVariable));
+            const exports = validEnvironmentVariables
+              .map((environmentVariable) => `export ${environmentVariable}`)
+              .join('\n');
+            if (exports) {
+              dependencies.runSandboxCommand([
+                'exec',
+                sandboxName,
+                'bash',
+                '-c',
+                `echo '${exports}' >> /etc/sandbox-persistent.sh`,
+              ]);
+            }
+            const invalidEnvironmentVariables = options.environmentVariables
+              .filter((environmentVariable) => !/^\w+=.+$/.test(environmentVariable));
+            if (invalidEnvironmentVariables.length > 0) {
+              dependencies.output.log(
+                `${terminalTextStyles.warn('⚠')}  Skipped invalid env vars: ${invalidEnvironmentVariables.join(', ')} (expected KEY=VALUE)`,
+              );
+            }
+          }
+
+          dependencies.output.log(`${terminalTextStyles.info('▶')} Launching CloudCLI web server...`);
+          dependencies.runSandboxCommand([
+            'exec',
+            sandboxName,
+            'bash',
+            '-c',
+            'nohup wacli start --port 3001 > /tmp/cloudcli-ui.log 2>&1 & disown',
+          ]);
+          if (!publishSandboxPort(options, dependencies)) {
+            return 1;
+          }
+
+          dependencies.output.log(`\n${terminalTextStyles.ok('✔')} ${terminalTextStyles.bright('CloudCLI is ready!')}`);
+          dependencies.output.log(`  ${terminalTextStyles.info('→')} Open ${terminalTextStyles.bright(`http://localhost:${options.port}`)}`);
+          dependencies.output.log(`\n${terminalTextStyles.dim('  Manage with:')}`);
+          dependencies.output.log(`  ${terminalTextStyles.dim('$')} sbx ls`);
+          dependencies.output.log(`  ${terminalTextStyles.dim('$')} sbx stop ${sandboxName}`);
+          dependencies.output.log(`  ${terminalTextStyles.dim('$')} sbx start ${sandboxName}`);
+          dependencies.output.log(`  ${terminalTextStyles.dim('$')} sbx rm ${sandboxName}`);
+          dependencies.output.log(`\n${terminalTextStyles.dim('  Or install globally:')} npm install -g wind-agent-cli\n`);
+          return 0;
+        }
+
+        default:
+          showSandboxHelp(dependencies.output);
+          return 0;
+      }
+    },
+  };
+}

package/server/modules/cli/tests/cli-environment-bootstrap.test.ts

@@ -0,0 +1,186 @@
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { copyFile, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+type BootstrapResult = {
+  command: string | null;
+  environmentFileReads: number;
+  mode: string | null;
+  authNextCalled: boolean;
+  authStatus: number;
+  authenticatedUsername: string | null;
+  runtime: string;
+};
+
+const RESULT_PREFIX = '__CLOUDCLI_BOOTSTRAP_RESULT__';
+const testDirectory = path.dirname(fileURLToPath(import.meta.url));
+const applicationRoot = path.resolve(testDirectory, '..', '..', '..', '..');
+
+function sourceModuleUrl(...segments: string[]): string {
+  return pathToFileURL(path.join(applicationRoot, ...segments)).href;
+}
+
+async function runCliBootstrapFixture(isPlatform: boolean): Promise<BootstrapResult> {
+  const fixtureRoot = await mkdtemp(path.join(os.tmpdir(), 'cloudcli-cli-bootstrap-'));
+  const fixtureServerDirectory = path.join(fixtureRoot, 'server');
+  const fixtureCliDirectory = path.join(fixtureServerDirectory, 'modules', 'cli');
+  const fixtureDatabasePath = path.join(fixtureRoot, 'auth.db');
+
+  try {
+    await mkdir(fixtureCliDirectory, { recursive: true });
+    await Promise.all([
+      copyFile(
+        path.join(applicationRoot, 'server', 'load-env.ts'),
+        path.join(fixtureServerDirectory, 'load-env.ts'),
+      ),
+      copyFile(
+        path.join(applicationRoot, 'server', 'modules', 'cli', 'cli.ts'),
+        path.join(fixtureCliDirectory, 'cli.ts'),
+      ),
+    ]);
+    await writeFile(
+      path.join(fixtureRoot, '.env'),
+      [
+        `VITE_IS_PLATFORM=${String(isPlatform)}`,
+        `DATABASE_PATH=${fixtureDatabasePath.replace(/\\/g, '/')}`,
+      ].join('\n'),
+      'utf8',
+    );
+
+    const fixtureIndexSource = `
+import { createCliService } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'cli', 'cli.service.ts'))};
+import { authenticateToken } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'auth', 'index.ts'))};
+import { getBrowserUseRuntime } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'browser-use', 'index.ts'))};
+import { closeConnection, initializeDatabase, userDb } from ${JSON.stringify(sourceModuleUrl('server', 'modules', 'database', 'index.ts'))};
+
+let environmentFileReads = 0;
+
+export function createCliApplication() {
+  const service = createCliService({
+    applicationRoot: ${JSON.stringify(fixtureRoot)},
+    defaultDatabasePath: ${JSON.stringify(fixtureDatabasePath)},
+    homeDirectory: ${JSON.stringify(fixtureRoot)},
+    packageMetadata: { version: '1.0.0' },
+    environment: process.env,
+    fileSystem: {
+      readTextFile: () => {
+        environmentFileReads += 1;
+        return '';
+      },
+      pathExists: () => false,
+      getFileStats: () => ({ size: 0, modifiedAt: new Date(0) }),
+    },
+    output: { log: () => undefined, error: () => undefined },
+    sandboxService: { execute: async () => 0 },
+    getLatestPackageVersion: async () => '1.0.0',
+    updateGlobalPackage: () => undefined,
+    startServer: async () => undefined,
+    startBrowserUseMcp: async () => undefined,
+  });
+
+  return {
+    async run(argumentsList: string[]) {
+      const exitCode = await service.run(argumentsList);
+      await initializeDatabase();
+      userDb.createUser('bootstrap-user', 'password-hash');
+
+      const request: any = { headers: {}, query: {} };
+      const response: any = {
+        statusCode: 200,
+        body: null,
+        headers: {},
+        setHeader(name: string, value: string) {
+          this.headers[name] = value;
+        },
+        status(statusCode: number) {
+          this.statusCode = statusCode;
+          return this;
+        },
+        json(body: unknown) {
+          this.body = body;
+          return this;
+        },
+      };
+      let authNextCalled = false;
+      await authenticateToken(request, response, () => {
+        authNextCalled = true;
+      });
+      const runtime = getBrowserUseRuntime();
+
+      console.log(${JSON.stringify(RESULT_PREFIX)} + JSON.stringify({
+        command: argumentsList[0] ?? null,
+        environmentFileReads,
+        mode: process.env.VITE_IS_PLATFORM ?? null,
+        authNextCalled,
+        authStatus: response.statusCode,
+        authenticatedUsername: request.user?.username ?? null,
+        runtime,
+      }));
+      closeConnection();
+      return exitCode;
+    },
+  };
+}
+`;
+    await writeFile(path.join(fixtureCliDirectory, 'index.ts'), fixtureIndexSource, 'utf8');
+
+    const childEnvironment = { ...process.env };
+    delete childEnvironment.VITE_IS_PLATFORM;
+    delete childEnvironment.DATABASE_PATH;
+    const stdout = execFileSync(
+      process.execPath,
+      [
+        path.join(applicationRoot, 'node_modules', 'tsx', 'dist', 'cli.mjs'),
+        '--tsconfig',
+        path.join(applicationRoot, 'server', 'tsconfig.json'),
+        path.join(fixtureCliDirectory, 'cli.ts'),
+        'status',
+      ],
+      {
+        cwd: applicationRoot,
+        encoding: 'utf8',
+        env: childEnvironment,
+        timeout: 30_000,
+      },
+    );
+    const resultLine = stdout
+      .split(/\r?\n/)
+      .find((line) => line.startsWith(RESULT_PREFIX));
+    assert.ok(resultLine, `Missing bootstrap result in child output:\n${stdout}`);
+    return JSON.parse(resultLine.slice(RESULT_PREFIX.length)) as BootstrapResult;
+  } finally {
+    await rm(fixtureRoot, { recursive: true, force: true });
+  }
+}
+
+test('CLI bootstrap selects Platform authentication and cloud runtime from .env', async () => {
+  const result = await runCliBootstrapFixture(true);
+
+  assert.deepEqual(result, {
+    command: 'status',
+    environmentFileReads: 0,
+    mode: 'true',
+    authNextCalled: true,
+    authStatus: 200,
+    authenticatedUsername: 'bootstrap-user',
+    runtime: 'cloud',
+  });
+});
+
+test('CLI bootstrap selects OSS authentication and local runtime from .env', async () => {
+  const result = await runCliBootstrapFixture(false);
+
+  assert.deepEqual(result, {
+    command: 'status',
+    environmentFileReads: 0,
+    mode: 'false',
+    authNextCalled: false,
+    authStatus: 401,
+    authenticatedUsername: null,
+    runtime: 'local',
+  });
+});

package/server/modules/cli/tests/cli.service.test.ts

@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import type { CliEnvironment, CliOutput } from '@/shared/types.js';
+
+import { createCliService } from '../cli.service.js';
+
+function createHarness() {
+  const logMessages: string[] = [];
+  const errorMessages: string[] = [];
+  const environment: CliEnvironment = {};
+  const output: CliOutput = {
+    log: (message = '') => logMessages.push(message),
+    error: (message = '') => errorMessages.push(message),
+  };
+  let serverStarts = 0;
+  let sandboxArguments: string[] = [];
+  const service = createCliService({
+    applicationRoot: '/application',
+    defaultDatabasePath: '/home/user/.cloudcli/auth.db',
+    homeDirectory: '/home/user',
+    packageMetadata: {
+      version: '1.2.3',
+      homepage: 'https://cloudcli.example',
+      bugsUrl: 'https://cloudcli.example/issues',
+    },
+    environment,
+    fileSystem: {
+      pathExists: () => false,
+      getFileStats: () => ({ size: 0, modifiedAt: new Date(0) }),
+    },
+    output,
+    sandboxService: {
+      execute: async (argumentsList) => {
+        sandboxArguments = argumentsList;
+        return 7;
+      },
+    },
+    getLatestPackageVersion: async () => '1.2.3',
+    updateGlobalPackage: () => undefined,
+    startServer: async () => {
+      serverStarts += 1;
+    },
+    startBrowserUseMcp: async () => undefined,
+  });
+
+  return {
+    service,
+    environment,
+    logMessages,
+    errorMessages,
+    getServerStarts: () => serverStarts,
+    getSandboxArguments: () => sandboxArguments,
+  };
+}
+
+test('applies CLI options to the injected environment before starting the server', async () => {
+  const harness = createHarness();
+
+  const exitCode = await harness.service.run([
+    '--port',
+    '8080',
+    '--database-path=/data/app.db',
+  ]);
+
+  assert.equal(exitCode, 0);
+  assert.equal(harness.environment.SERVER_PORT, '8080');
+  assert.equal(harness.environment.DATABASE_PATH, '/data/app.db');
+  assert.equal(harness.getServerStarts(), 1);
+});
+
+test('passes only sandbox arguments to the injected sandbox service', async () => {
+  const harness = createHarness();
+
+  const exitCode = await harness.service.run(['sandbox', 'ls']);
+
+  assert.equal(exitCode, 7);
+  assert.deepEqual(harness.getSandboxArguments(), ['ls']);
+});
+
+test('shows wacli as the installed command', async () => {
+  const harness = createHarness();
+
+  const exitCode = await harness.service.run(['help']);
+
+  assert.equal(exitCode, 0);
+  assert.match(harness.logMessages.join('\n'), /wacli \[command\] \[options\]/);
+  assert.match(harness.logMessages.join('\n'), /\$ wacli status/);
+});
+
+test('returns a failure code for an unknown command without exiting the process', async () => {
+  const harness = createHarness();
+
+  const exitCode = await harness.service.run(['unknown']);
+
+  assert.equal(exitCode, 1);
+  assert.match(harness.errorMessages[0], /Unknown command: unknown/);
+});