@cloudcli-ai/cloudcli 1.36.3 → 1.37.1

package/server/modules/cli/cli.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { createCliApplication } from './index.js';
+
+const cliApplication = createCliApplication();
+
+cliApplication.run(process.argv.slice(2)).then((exitCode) => {
+  process.exitCode = exitCode;
+}).catch((error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error('\n❌ Error:', message);
+  process.exitCode = 1;
+});

package/server/modules/cli/index.ts

@@ -0,0 +1,2 @@
+// createCliApplication: used by the CLI executable to obtain the fully wired command application.
+export { createCliApplication } from './cli.module.js';

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:
+  cloudcli sandbox <workspace>            Create and start a sandbox
+  cloudcli 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:
+  $ cloudcli sandbox ~/my-project
+  $ cloudcli sandbox ~/my-project --agent codex --port 8080
+  $ cloudcli sandbox ~/my-project --env SERVER_PORT=8080 --env HOST=0.0.0.0
+  $ cloudcli sandbox ls
+  $ cloudcli sandbox stop my-project
+  $ cloudcli sandbox start my-project
+  $ cloudcli 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: cloudcli 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 cloudcli 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: cloudcli sandbox <path>\n`,
+            );
+            dependencies.output.log(`   Example: ${terminalTextStyles.bright('cloudcli 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 cloudcli 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 @cloudcli-ai/cloudcli\n`);
+          return 0;
+        }
+
+        default:
+          showSandboxHelp(dependencies.output);
+          return 0;
+      }
+    },
+  };
+}

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

@@ -0,0 +1,91 @@
+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: {
+      readTextFile: () => {
+        throw new Error('missing');
+      },
+      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('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/);
+});

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

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createSandboxCommandService } from '../sandbox.service.js';
+
+test('creates a sandbox through injected filesystem, subprocess, and clock adapters', async () => {
+  const commands: string[][] = [];
+  const detachedCommands: string[][] = [];
+  const waits: number[] = [];
+  const service = createSandboxCommandService({
+    homeDirectory: '/home/user',
+    fileSystem: {
+      pathExists: (candidatePath) => candidatePath === '/home/user/project',
+    },
+    output: { log: () => undefined, error: () => undefined },
+    runSandboxCommand: (argumentsList) => {
+      commands.push(argumentsList);
+      return argumentsList[0] === 'secret' ? 'anthropic' : '';
+    },
+    spawnDetachedSandbox: (argumentsList) => detachedCommands.push(argumentsList),
+    wait: async (milliseconds) => {
+      waits.push(milliseconds);
+    },
+  });
+
+  const exitCode = await service.execute(['~/project']);
+
+  assert.equal(exitCode, 0);
+  assert.deepEqual(detachedCommands, [[
+    'run',
+    '--template',
+    'docker.io/cloudcliai/sandbox:claude-code',
+    '--name',
+    'project',
+    'claude',
+    '/home/user/project',
+  ]]);
+  assert.deepEqual(waits, [5_000]);
+  assert.ok(commands.some((argumentsList) => argumentsList[0] === 'ports'));
+});
+
+test('does not spawn when the workspace does not exist', async () => {
+  let detachedCalls = 0;
+  const service = createSandboxCommandService({
+    homeDirectory: '/home/user',
+    fileSystem: {
+      pathExists: () => false,
+    },
+    output: { log: () => undefined, error: () => undefined },
+    runSandboxCommand: () => '',
+    spawnDetachedSandbox: () => {
+      detachedCalls += 1;
+    },
+    wait: async () => undefined,
+  });
+
+  const exitCode = await service.execute(['/missing']);
+
+  assert.equal(exitCode, 1);
+  assert.equal(detachedCalls, 0);
+});

package/server/modules/commands/commands.module.ts

@@ -0,0 +1,22 @@
+import * as fs from 'node:fs/promises';
+import os from 'node:os';
+
+import { providerModelsService } from '@/modules/providers/index.js';
+import { findApplicationRoot, getModuleDirectory } from '@/shared/utils.js';
+
+import { createCommandsRouter } from './commands.routes.js';
+
+/** Commands router assembled for the authenticated server mount. */
+export const commandsRoutes = createCommandsRouter({
+  fileSystem: fs,
+  homeDirectory: os.homedir,
+  appRoot: findApplicationRoot(getModuleDirectory(import.meta.url)),
+  models: providerModelsService,
+  runtime: {
+    uptime: process.uptime,
+    memoryUsage: process.memoryUsage,
+    version: process.version,
+    platform: process.platform,
+    pid: process.pid,
+  },
+});