@cloudcli-ai/cloudcli 1.36.3 → 1.37.1

package/server/modules/auth/auth.service.ts

@@ -0,0 +1,155 @@
+import { AppError } from '@/shared/utils.js';
+
+type AuthUser = {
+  id: number | bigint;
+  username: string;
+};
+
+type AuthLoginUser = AuthUser & { password_hash: string };
+
+type AuthDependencies = {
+  users: {
+    hasUsers(): boolean;
+    createUser(username: string, passwordHash: string): AuthUser;
+    getUserByUsername(username: string): AuthLoginUser | undefined;
+    updateLastLogin(userId: number): void;
+  };
+  transaction: {
+    begin(): void;
+    commit(): void;
+    rollback(): void;
+  };
+  hashPassword(password: string): Promise<string>;
+  comparePassword(password: string, passwordHash: string): Promise<boolean>;
+  generateToken(user: AuthUser): string;
+};
+
+function numericUserId(userId: number | bigint): number {
+  return Number(userId);
+}
+
+function isUniqueConstraintError(error: unknown): boolean {
+  return typeof error === 'object'
+    && error !== null
+    && 'code' in error
+    && error.code === 'SQLITE_CONSTRAINT_UNIQUE';
+}
+
+/**
+ * Creates the Auth application service around explicit persistence, crypto,
+ * transaction, and token dependencies.
+ */
+export function createAuthService(dependencies: AuthDependencies) {
+  return {
+    getStatus() {
+      return {
+        needsSetup: !dependencies.users.hasUsers(),
+        isAuthenticated: false,
+      };
+    },
+
+    async register(usernameInput: unknown, passwordInput: unknown) {
+      const username = typeof usernameInput === 'string' ? usernameInput : '';
+      const password = typeof passwordInput === 'string' ? passwordInput : '';
+
+      if (!username || !password) {
+        throw new AppError('Username and password are required', {
+          code: 'AUTH_CREDENTIALS_REQUIRED',
+          statusCode: 400,
+        });
+      }
+      if (username.length < 3 || password.length < 6) {
+        throw new AppError(
+          'Username must be at least 3 characters, password at least 6 characters',
+          { code: 'AUTH_CREDENTIALS_TOO_SHORT', statusCode: 400 },
+        );
+      }
+
+      dependencies.transaction.begin();
+      try {
+        if (dependencies.users.hasUsers()) {
+          throw new AppError('User already exists. This is a single-user system.', {
+            code: 'AUTH_USER_ALREADY_CONFIGURED',
+            statusCode: 403,
+          });
+        }
+
+        const passwordHash = await dependencies.hashPassword(password);
+        const user = dependencies.users.createUser(username, passwordHash);
+        const token = dependencies.generateToken(user);
+        dependencies.transaction.commit();
+        dependencies.users.updateLastLogin(numericUserId(user.id));
+
+        return {
+          success: true,
+          user: { id: user.id, username: user.username },
+          token,
+        };
+      } catch (error) {
+        dependencies.transaction.rollback();
+        if (isUniqueConstraintError(error)) {
+          throw new AppError('Username already exists', {
+            code: 'AUTH_USERNAME_CONFLICT',
+            statusCode: 409,
+          });
+        }
+        throw error;
+      }
+    },
+
+    async login(usernameInput: unknown, passwordInput: unknown) {
+      const username = typeof usernameInput === 'string' ? usernameInput : '';
+      const password = typeof passwordInput === 'string' ? passwordInput : '';
+      if (!username || !password) {
+        throw new AppError('Username and password are required', {
+          code: 'AUTH_CREDENTIALS_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      const user = dependencies.users.getUserByUsername(username);
+      const validPassword = user
+        ? await dependencies.comparePassword(password, user.password_hash)
+        : false;
+      if (!user || !validPassword) {
+        throw new AppError('Invalid username or password', {
+          code: 'AUTH_INVALID_CREDENTIALS',
+          statusCode: 401,
+        });
+      }
+
+      dependencies.users.updateLastLogin(numericUserId(user.id));
+      return {
+        success: true,
+        user: { id: user.id, username: user.username },
+        token: dependencies.generateToken(user),
+      };
+    },
+
+    getCurrentUser(user: unknown) {
+      return { user };
+    },
+
+    refreshSession(user: unknown) {
+      if (
+        typeof user !== 'object'
+        || user === null
+        || !('id' in user)
+        || !('username' in user)
+        || (typeof user.id !== 'number' && typeof user.id !== 'bigint')
+        || typeof user.username !== 'string'
+      ) {
+        throw new AppError('Authenticated user is required', {
+          code: 'AUTH_USER_REQUIRED',
+          statusCode: 401,
+        });
+      }
+
+      return { token: dependencies.generateToken(user as AuthUser) };
+    },
+
+    logout() {
+      return { success: true, message: 'Logged out successfully' };
+    },
+  };
+}

package/server/modules/auth/index.ts

@@ -0,0 +1,9 @@
+// authRoutes: used by the server entrypoint to mount public authentication endpoints.
+export { authRoutes } from './auth.module.js';
+
+// authenticateToken: used by the server entrypoint to protect authenticated API modules.
+export { authenticateToken } from './auth.middleware.js';
+// authenticateWebSocket: used by WebSocket setup to verify connection tokens.
+export { authenticateWebSocket } from './auth.middleware.js';
+// validateApiKey: used by the server entrypoint for optional API-wide key validation.
+export { validateApiKey } from './auth.middleware.js';

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

@@ -0,0 +1,95 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { AppError } from '@/shared/utils.js';
+
+import { createAuthService } from '../auth.service.js';
+
+type AuthDependencies = Parameters<typeof createAuthService>[0];
+
+function createDependencies(overrides: Partial<AuthDependencies> = {}): AuthDependencies {
+  return {
+    users: {
+      hasUsers: () => false,
+      createUser: (username, passwordHash) => ({ id: 1, username, password_hash: passwordHash }),
+      getUserByUsername: () => undefined,
+      updateLastLogin: () => undefined,
+    },
+    transaction: {
+      begin: () => undefined,
+      commit: () => undefined,
+      rollback: () => undefined,
+    },
+    hashPassword: async () => 'hashed-password',
+    comparePassword: async () => false,
+    generateToken: () => 'signed-token',
+    ...overrides,
+  };
+}
+
+test('register hashes credentials and commits through injected dependencies', async () => {
+  const operations: string[] = [];
+  const service = createAuthService(createDependencies({
+    transaction: {
+      begin: () => operations.push('begin'),
+      commit: () => operations.push('commit'),
+      rollback: () => operations.push('rollback'),
+    },
+    hashPassword: async (password) => {
+      operations.push(`hash:${password}`);
+      return 'hash';
+    },
+    users: {
+      hasUsers: () => false,
+      createUser: (username, passwordHash) => {
+        operations.push(`create:${username}:${passwordHash}`);
+        return { id: 1, username, password_hash: passwordHash };
+      },
+      getUserByUsername: () => undefined,
+      updateLastLogin: (userId) => operations.push(`login:${userId}`),
+    },
+  }));
+
+  const result = await service.register('alice', 'secret12');
+
+  assert.equal(result.token, 'signed-token');
+  assert.deepEqual(operations, ['begin', 'hash:secret12', 'create:alice:hash', 'commit', 'login:1']);
+});
+
+test('login rejects an invalid password without issuing a token', async () => {
+  let tokenIssued = false;
+  const service = createAuthService(createDependencies({
+    users: {
+      hasUsers: () => true,
+      createUser: () => { throw new Error('unused'); },
+      getUserByUsername: () => ({ id: 1, username: 'alice', password_hash: 'hash' }),
+      updateLastLogin: () => undefined,
+    },
+    comparePassword: async () => false,
+    generateToken: () => {
+      tokenIssued = true;
+      return 'token';
+    },
+  }));
+
+  await assert.rejects(
+    service.login('alice', 'wrong-password'),
+    (error: unknown) => error instanceof AppError && error.code === 'AUTH_INVALID_CREDENTIALS',
+  );
+  assert.equal(tokenIssued, false);
+});
+
+test('refreshSession issues a replacement token for the authenticated user', () => {
+  let tokenUser: { id: number | bigint; username: string } | undefined;
+  const service = createAuthService(createDependencies({
+    generateToken: (user) => {
+      tokenUser = user;
+      return 'replacement-token';
+    },
+  }));
+
+  const result = service.refreshSession({ id: 7, username: 'alice' });
+
+  assert.deepEqual(result, { token: 'replacement-token' });
+  assert.deepEqual(tokenUser, { id: 7, username: 'alice' });
+});

package/server/{browser-use-mcp.ts → modules/browser-use/browser-use-mcp.ts}

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-import './load-env.js';
+// The MCP executable must load the root environment bootstrap before reading configuration.
+// eslint-disable-next-line boundaries/no-unknown
+import '../../load-env.js';
 
 type JsonRpcRequest = {
   jsonrpc: '2.0';

package/server/modules/browser-use/browser-use.service.ts

@@ -9,10 +9,10 @@ import spawn from 'cross-spawn';
 
 import { appConfigDb } from '@/modules/database/index.js';
 import { providerMcpService } from '@/modules/providers/index.js';
-import { getModuleDir } from '@/utils/runtime-paths.js';
+import { getModuleDirectory } from '@/shared/utils.js';
 
 const require = createRequire(import.meta.url);
-const __dirname = getModuleDir(import.meta.url);
+const __dirname = getModuleDirectory(import.meta.url);
 const IS_PLATFORM = process.env.VITE_IS_PLATFORM === 'true';
 const MAX_SESSIONS_PER_OWNER = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_MAX_SESSIONS_PER_OWNER || '3', 10);
 const SESSION_TTL_MS = Number.parseInt(process.env.CLOUDCLI_BROWSER_USE_SESSION_TTL_MS || String(30 * 60 * 1000), 10);
@@ -150,8 +150,7 @@ function getPlaywright(): any | null {
 }
 
 function getMcpCommand(): { command: string; args: string[] } {
-  const serverDir = path.resolve(__dirname, '..', '..');
-  const mcpScriptPath = path.join(serverDir, 'browser-use-mcp.js');
+  const mcpScriptPath = path.join(__dirname, 'browser-use-mcp.js');
   if (fs.existsSync(mcpScriptPath)) {
     return {
       command: process.execPath,

package/server/modules/browser-use/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Lazily starts the Browser Use MCP stdio entrypoint. Keeping this import lazy
+ * ensures the entrypoint loads environment configuration before its runtime is
+ * evaluated.
+ */
+export async function startBrowserUseMcp(): Promise<void> {
+  await import('./browser-use-mcp.js');
+}

package/server/modules/cli/cli.module.ts

@@ -0,0 +1,96 @@
+import { execFileSync, execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import spawn from 'cross-spawn';
+
+import type { CliApplication, CliPackageMetadata } from '@/shared/types.js';
+import { findApplicationRoot, getModuleDirectory } from '@/shared/utils.js';
+
+import { createCliService } from './cli.service.js';
+import { createSandboxCommandService } from './sandbox.service.js';
+
+/**
+ * Creates the production CLI application for the executable entrypoint. This is
+ * the CLI module's single composition root: it reads package metadata and wires
+ * all concrete Node filesystem, subprocess, environment, clock, and module-start
+ * adapters before passing them into otherwise isolated services.
+ */
+export function createCliApplication(): CliApplication {
+  const applicationRoot = findApplicationRoot(getModuleDirectory(import.meta.url));
+  const packageMetadataJson = JSON.parse(
+    fs.readFileSync(path.join(applicationRoot, 'package.json'), 'utf8'),
+  ) as { version: string; homepage?: string; bugs?: { url?: string } };
+  const packageMetadata: CliPackageMetadata = {
+    version: packageMetadataJson.version,
+    homepage: packageMetadataJson.homepage,
+    bugsUrl: packageMetadataJson.bugs?.url,
+  };
+  const fileSystem = {
+    readTextFile: (filePath: string) => fs.readFileSync(filePath, 'utf8'),
+    pathExists: (filePath: string) => fs.existsSync(filePath),
+    getFileStats: (filePath: string) => {
+      const stats = fs.statSync(filePath);
+      return { size: stats.size, modifiedAt: stats.mtime };
+    },
+  };
+  const output = {
+    log: (message?: string) => console.log(message),
+    error: (message?: string) => console.error(message),
+  };
+  const homeDirectory = os.homedir();
+  const sandboxService = createSandboxCommandService({
+    homeDirectory,
+    fileSystem,
+    output,
+    runSandboxCommand: (argumentsList, inheritOutput = false) => {
+      const result = execFileSync('sbx', argumentsList, {
+        encoding: 'utf8',
+        stdio: inheritOutput ? 'inherit' : 'pipe',
+      });
+      return result || '';
+    },
+    spawnDetachedSandbox: (argumentsList) => {
+      const childProcess = spawn('sbx', argumentsList, {
+        detached: true,
+        stdio: ['ignore', 'ignore', 'ignore'],
+      });
+      childProcess.unref();
+    },
+    wait: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  });
+
+  return createCliService({
+    applicationRoot,
+    defaultDatabasePath: path.join(homeDirectory, '.cloudcli', 'auth.db'),
+    homeDirectory,
+    packageMetadata,
+    environment: process.env,
+    fileSystem,
+    output,
+    sandboxService,
+    getLatestPackageVersion: async () => {
+      // Yield first so the default `start` command can begin loading the server
+      // before this best-effort npm registry check runs.
+      await new Promise<void>((resolve) => setImmediate(resolve));
+      return execSync(
+        'npm show @cloudcli-ai/cloudcli version',
+        { encoding: 'utf8' },
+      ).trim();
+    },
+    updateGlobalPackage: () => {
+      execSync('npm update -g @cloudcli-ai/cloudcli', { stdio: 'inherit' });
+    },
+    startServer: async () => {
+      // The server executable is an entrypoint rather than a feature module,
+      // so it has no barrel contract to import through.
+      // eslint-disable-next-line boundaries/no-unknown
+      await import('../../index.js');
+    },
+    startBrowserUseMcp: async () => {
+      const { startBrowserUseMcp } = await import('../browser-use/index.js');
+      await startBrowserUseMcp();
+    },
+  });
+}

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

@@ -0,0 +1,281 @@
+import path from 'node:path';
+
+import type {
+  CliApplication,
+  CliEnvironment,
+  CliFileSystem,
+  CliOutput,
+  CliPackageMetadata,
+  SandboxCommandService,
+} from '@/shared/types.js';
+import { terminalTextStyles } from '@/shared/utils.js';
+
+type CliServiceDependencies = {
+  applicationRoot: string;
+  defaultDatabasePath: string;
+  homeDirectory: string;
+  packageMetadata: CliPackageMetadata;
+  environment: CliEnvironment;
+  fileSystem: CliFileSystem;
+  output: CliOutput;
+  sandboxService: SandboxCommandService;
+  getLatestPackageVersion(): Promise<string>;
+  updateGlobalPackage(): void;
+  startServer(): Promise<void>;
+  startBrowserUseMcp(): Promise<void>;
+};
+
+type ParsedCliArguments = {
+  command: string;
+  options: {
+    serverPort?: string;
+    databasePath?: string;
+  };
+  remainingArguments: string[];
+};
+
+function parseCliArguments(argumentsList: string[]): ParsedCliArguments {
+  const parsedArguments: ParsedCliArguments = {
+    command: 'start',
+    options: {},
+    remainingArguments: [],
+  };
+
+  for (let argumentIndex = 0; argumentIndex < argumentsList.length; argumentIndex += 1) {
+    const argument = argumentsList[argumentIndex];
+    if (argument === '--port' || argument === '-p') {
+      parsedArguments.options.serverPort = argumentsList[++argumentIndex];
+    } else if (argument.startsWith('--port=')) {
+      parsedArguments.options.serverPort = argument.slice('--port='.length);
+    } else if (argument === '--database-path') {
+      parsedArguments.options.databasePath = argumentsList[++argumentIndex];
+    } else if (argument.startsWith('--database-path=')) {
+      parsedArguments.options.databasePath = argument.slice('--database-path='.length);
+    } else if (argument === '--help' || argument === '-h') {
+      parsedArguments.command = 'help';
+    } else if (argument === '--version' || argument === '-v') {
+      parsedArguments.command = 'version';
+    } else if (!argument.startsWith('-')) {
+      parsedArguments.command = argument;
+      if (argument === 'sandbox') {
+        parsedArguments.remainingArguments = argumentsList.slice(argumentIndex + 1);
+        break;
+      }
+    }
+  }
+
+  return parsedArguments;
+}
+
+function isNewerVersion(candidateVersion: string, currentVersion: string): boolean {
+  const candidateParts = candidateVersion.split('.').map(Number);
+  const currentParts = currentVersion.split('.').map(Number);
+  for (let partIndex = 0; partIndex < 3; partIndex += 1) {
+    if (candidateParts[partIndex] > currentParts[partIndex]) return true;
+    if (candidateParts[partIndex] < currentParts[partIndex]) return false;
+  }
+  return false;
+}
+
+function loadEnvironmentFile(dependencies: CliServiceDependencies): void {
+  try {
+    const environmentFile = dependencies.fileSystem.readTextFile(
+      path.join(dependencies.applicationRoot, '.env'),
+    );
+    for (const line of environmentFile.split('\n')) {
+      const trimmedLine = line.trim();
+      if (!trimmedLine || trimmedLine.startsWith('#')) continue;
+
+      const [key, ...valueParts] = trimmedLine.split('=');
+      if (key && valueParts.length > 0 && !dependencies.environment[key]) {
+        dependencies.environment[key] = valueParts.join('=').trim();
+      }
+    }
+  } catch {
+    // The repository-level .env file is optional for every CLI command.
+  }
+}
+
+function showStatus(dependencies: CliServiceDependencies): void {
+  loadEnvironmentFile(dependencies);
+  const { environment, fileSystem, output } = dependencies;
+  const databasePath = environment.DATABASE_PATH || dependencies.defaultDatabasePath;
+  const databaseExists = fileSystem.pathExists(databasePath);
+  const claudeProjectsPath = path.join(dependencies.homeDirectory, '.claude', 'projects');
+  const environmentFilePath = path.join(dependencies.applicationRoot, '.env');
+
+  output.log(`\n${terminalTextStyles.bright('CloudCLI UI - Status')}\n`);
+  output.log(terminalTextStyles.dim('═'.repeat(60)));
+  output.log(`\n${terminalTextStyles.info('[INFO]')} Version: ${terminalTextStyles.bright(dependencies.packageMetadata.version)}`);
+  output.log(`\n${terminalTextStyles.info('[INFO]')} Installation Directory:`);
+  output.log(`       ${terminalTextStyles.dim(dependencies.applicationRoot)}`);
+  output.log(`\n${terminalTextStyles.info('[INFO]')} Database Location:`);
+  output.log(`       ${terminalTextStyles.dim(databasePath)}`);
+  output.log(`       Status: ${databaseExists
+    ? terminalTextStyles.ok('[OK] Exists')
+    : terminalTextStyles.warn('[WARN] Not created yet (will be created on first run)')}`);
+
+  if (databaseExists) {
+    const databaseStats = fileSystem.getFileStats(databasePath);
+    output.log(`       Size: ${terminalTextStyles.dim(`${(databaseStats.size / 1024).toFixed(2)} KB`)}`);
+    output.log(`       Modified: ${terminalTextStyles.dim(databaseStats.modifiedAt.toLocaleString())}`);
+  }
+
+  output.log(`\n${terminalTextStyles.info('[INFO]')} Configuration:`);
+  output.log(`       SERVER_PORT: ${terminalTextStyles.bright(environment.SERVER_PORT || environment.PORT || '3001')} ${terminalTextStyles.dim(environment.SERVER_PORT || environment.PORT ? '' : '(default)')}`);
+  output.log(`       DATABASE_PATH: ${terminalTextStyles.dim(environment.DATABASE_PATH || '(using default location)')}`);
+  output.log(`       CLAUDE_CLI_PATH: ${terminalTextStyles.dim(environment.CLAUDE_CLI_PATH || 'claude (default)')}`);
+  output.log(`       CONTEXT_WINDOW: ${terminalTextStyles.dim(environment.CONTEXT_WINDOW || '160000 (default)')}`);
+  output.log(`\n${terminalTextStyles.info('[INFO]')} Claude Projects Folder:`);
+  output.log(`       ${terminalTextStyles.dim(claudeProjectsPath)}`);
+  output.log(`       Status: ${fileSystem.pathExists(claudeProjectsPath)
+    ? terminalTextStyles.ok('[OK] Exists')
+    : terminalTextStyles.warn('[WARN] Not found')}`);
+  output.log(`\n${terminalTextStyles.info('[INFO]')} Configuration File:`);
+  output.log(`       ${terminalTextStyles.dim(environmentFilePath)}`);
+  output.log(`       Status: ${fileSystem.pathExists(environmentFilePath)
+    ? terminalTextStyles.ok('[OK] Exists')
+    : terminalTextStyles.warn('[WARN] Not found (using defaults)')}`);
+  output.log(`\n${terminalTextStyles.dim('═'.repeat(60))}`);
+  output.log(`\n${terminalTextStyles.tip('[TIP]')} Hints:`);
+  output.log(`      ${terminalTextStyles.dim('>')} Use ${terminalTextStyles.bright('cloudcli --port 8080')} to run on a custom port`);
+  output.log(`      ${terminalTextStyles.dim('>')} Use ${terminalTextStyles.bright('cloudcli --database-path /path/to/db')} for custom database`);
+  output.log(`      ${terminalTextStyles.dim('>')} Run ${terminalTextStyles.bright('cloudcli help')} for all options`);
+  output.log(`      ${terminalTextStyles.dim('>')} Access the UI at http://localhost:${environment.SERVER_PORT || environment.PORT || '3001'}\n`);
+}
+
+function showHelp(dependencies: CliServiceDependencies): void {
+  dependencies.output.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║              CloudCLI - Command Line Tool               ║
+╚═══════════════════════════════════════════════════════════════╝
+
+Usage:
+  claude-code-ui [command] [options]
+  cloudcli [command] [options]
+
+Commands:
+  start            Start the CloudCLI server (default)
+  sandbox          Manage Docker sandbox environments
+  browser-use-mcp  Run Browser MCP stdio server
+  status           Show configuration and data locations
+  update           Update to the latest version
+  help             Show this help information
+  version          Show version information
+
+Options:
+  -p, --port <port>           Set server port (default: 3001)
+  --database-path <path>      Set custom database location
+  -h, --help                  Show this help information
+  -v, --version               Show version information
+
+Examples:
+  $ cloudcli                        # Start with defaults
+  $ cloudcli --port 8080            # Start on port 8080
+  $ cloudcli sandbox ~/my-project   # Run in a Docker sandbox
+  $ cloudcli status                 # Show configuration
+
+Environment Variables:
+  SERVER_PORT         Set server port (default: 3001)
+  PORT                Set server port (default: 3001) (LEGACY)
+  DATABASE_PATH       Set custom database location
+  CLAUDE_CLI_PATH     Set custom Claude CLI path
+  CONTEXT_WINDOW      Set context window size (default: 160000)
+
+Documentation:
+  ${dependencies.packageMetadata.homepage || 'https://github.com/siteboon/claudecodeui'}
+
+Report Issues:
+  ${dependencies.packageMetadata.bugsUrl || 'https://github.com/siteboon/claudecodeui/issues'}
+`);
+}
+
+/**
+ * Creates the top-level CLI command service used by the CLI composition root
+ * and unit tests. Every filesystem, subprocess, environment, output, and
+ * cross-module startup dependency is explicit and required.
+ */
+export function createCliService(dependencies: CliServiceDependencies): CliApplication {
+  const checkForUpdates = async (silent = false): Promise<boolean> => {
+    try {
+      const latestVersion = await dependencies.getLatestPackageVersion();
+      const currentVersion = dependencies.packageMetadata.version;
+      if (isNewerVersion(latestVersion, currentVersion)) {
+        dependencies.output.log(`\n${terminalTextStyles.warn('[UPDATE]')} New version available: ${terminalTextStyles.bright(latestVersion)} (current: ${currentVersion})`);
+        dependencies.output.log(`         Run ${terminalTextStyles.bright('cloudcli update')} to update\n`);
+        return true;
+      }
+      if (!silent) {
+        dependencies.output.log(`${terminalTextStyles.ok('[OK]')} You are on the latest version (${currentVersion})`);
+      }
+      return false;
+    } catch {
+      if (!silent) {
+        dependencies.output.log(`${terminalTextStyles.warn('[WARN]')} Could not check for updates`);
+      }
+      return false;
+    }
+  };
+
+  const updatePackage = async (): Promise<void> => {
+    dependencies.output.log(`${terminalTextStyles.info('[INFO]')} Checking for updates...`);
+    const hasUpdate = await checkForUpdates(true);
+    if (!hasUpdate) {
+      dependencies.output.log(`${terminalTextStyles.ok('[OK]')} Already on the latest version (${dependencies.packageMetadata.version})`);
+      return;
+    }
+
+    try {
+      dependencies.output.log(`${terminalTextStyles.info('[INFO]')} Updating ${dependencies.packageMetadata.version}...`);
+      dependencies.updateGlobalPackage();
+      dependencies.output.log(`${terminalTextStyles.ok('[OK]')} Update complete! Restart cloudcli to use the new version.`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      dependencies.output.error(`${terminalTextStyles.error('[ERROR]')} Update failed: ${message}`);
+      dependencies.output.log(`${terminalTextStyles.tip('[TIP]')} Try running manually: npm update -g @cloudcli-ai/cloudcli`);
+    }
+  };
+
+  return {
+    async run(argumentsList) {
+      const parsedArguments = parseCliArguments(argumentsList);
+      if (parsedArguments.options.serverPort) {
+        dependencies.environment.SERVER_PORT = parsedArguments.options.serverPort;
+      } else if (!dependencies.environment.SERVER_PORT && dependencies.environment.PORT) {
+        dependencies.environment.SERVER_PORT = dependencies.environment.PORT;
+      }
+      if (parsedArguments.options.databasePath) {
+        dependencies.environment.DATABASE_PATH = parsedArguments.options.databasePath;
+      }
+
+      switch (parsedArguments.command) {
+        case 'start':
+          void checkForUpdates(true);
+          await dependencies.startServer();
+          return 0;
+        case 'sandbox':
+          return dependencies.sandboxService.execute(parsedArguments.remainingArguments);
+        case 'browser-use-mcp':
+          await dependencies.startBrowserUseMcp();
+          return 0;
+        case 'status':
+        case 'info':
+          showStatus(dependencies);
+          return 0;
+        case 'help':
+          showHelp(dependencies);
+          return 0;
+        case 'version':
+          dependencies.output.log(dependencies.packageMetadata.version);
+          return 0;
+        case 'update':
+          await updatePackage();
+          return 0;
+        default:
+          dependencies.output.error(`\n❌ Unknown command: ${parsedArguments.command}`);
+          dependencies.output.log('   Run "cloudcli help" for usage information.\n');
+          return 1;
+      }
+    },
+  };
+}