[CLI] Add the reproduce command in CLI (#5029)

This PR adds the `reproduce` command into the `casp` CLI, enabling local
reproduction of a ClusterFuzz testcase inside a Docker container. This
command simplifies the process by managing the Docker environment and
automatically mounting necessary configurations and credentials.

---
## Changes Made

A new `reproduce` command was added to the `casp` CLI. Given a
testcase-id, the command performs the following
actions:

1. Pulls the appropriate ClusterFuzz Docker immutable image (if not
already pulled).
2. Mounts the user's gcloud credentials and any custom ClusterFuzz
configurations into the container.
3. Executes the butler.py reproduce command within the container to
fetch the testcase, set up the job and fuzzer
    environment, and attempt to reproduce the crash.
 4. Streams the output from the container to the local terminal.

This PR also introduces some utility functions:
- `load_and_validate_config` to `casp.utils.config`;
- `build_command` to the new `casp.utils.container`;
- As this is a common part for most future commands, these functions
build the command to run within the container;
    - The new module also keeps some common constants;
- `prepare_docker_volumes` to `docker_utils`;
---
### How to Test Manually

First, install `casp`.

If you have not installed yet, please navigate to the `cli` directory
and run to install it in editable mode:
```shell
  $ pip install -e casp
```

1. Authentication & Setup
Now, you must have run `casp init` to configure your credentials. If you
haven't, please run it now:

```shell
  $ casp init
```

2. Usage
Once set up, run the reproduce command with the following format:

```shell
  $ casp reproduce --testcase-id=<testcase_id> -p internal
```

---
### Testing

Unit tests for this feature have been added in
`cli/casp/src/casp/tests/commands/test_reproduce.py`.

Unit tests for `casp.utils.container` will be added in future PR.

### Demo prints

Here are two examples reproducing testcases of both `internal` and
`external` projects.

* `casp reproduce --testcase-id=5115444050460672 -p internal`
(truncated):
<img width="1885" height="297" alt="image"
src="https://github.com/user-attachments/assets/6fdb5e63-ea5c-45e2-bf38-247d5ff7c2e2"
/>
<img width="1884" height="190" alt="image"
src="https://github.com/user-attachments/assets/f5295879-c26c-45ec-a83a-33e0e330924b"
/>


* `casp reproduce -p external --testcase-id=6083012753424384`
(truncated):
<img width="1884" height="218" alt="image"
src="https://github.com/user-attachments/assets/60cfefc4-57b5-422a-9e69-47feeb4ad742"
/>
<img width="1884" height="190" alt="image"
src="https://github.com/user-attachments/assets/55e3126a-1eb7-4de2-9672-cf0a89a6203a"
/>

Author: PauloVLB

cli/casp/src/casp/commands/reproduce.py

@@ -11,12 +11,64 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Reproduce command."""
+"""Reproduces a testcase locally using Docker."""
 
+import sys
+
+from casp.utils import config
+from casp.utils import container
+from casp.utils import docker_utils
 import click
 
 
-@click.command(name='reproduce', help='Reproduces a testcase locally')
-def cli():
-  """Reproduces a testcase locally"""
-  click.echo('To be implemented...')
+@click.command(
+    name='reproduce',
+    help=('Reproduces a testcase locally. '
+          ' WARN: This essentially runs untrusted code '
+          'in your local environment. '
+          'Please acknowledge the testcase (mainly input and build) '
+          'before running this command.'))
+@click.option(
+    '--project',
+    '-p',
+    help='The ClusterFuzz project to use.',
+    required=True,
+    type=click.Choice(
+        docker_utils.PROJECT_TO_IMAGE.keys(), case_sensitive=False),
+)
+@click.option(
+    '--config-dir',
+    '-c',
+    required=False,
+    default=str(container.CONTAINER_CONFIG_PATH / 'config'),
+    help=('Path to the config directory. If you set a custom '
+          'config directory, this argument is not used.'),
+)
+@click.option(
+    '--testcase-id', required=True, help='The ID of the testcase to reproduce.')
+def cli(project: str, config_dir: str, testcase_id: str) -> None:
+  """Reproduces a testcase locally by running a Docker container.
+
+  Args:
+    project: The ClusterFuzz project name.
+    config_dir: The default configuration directory path within the container.
+    testcase_id: The ID of the testcase to be reproduced.
+  """
+  cfg = config.load_and_validate_config()
+
+  volumes, container_config_dir = docker_utils.prepare_docker_volumes(
+      cfg, config_dir)
+
+  command = container.build_butler_command(
+      'reproduce',
+      config_dir=str(container_config_dir),
+      testcase_id=testcase_id,
+  )
+
+  if not docker_utils.run_command(
+      command,
+      volumes,
+      privileged=True,
+      image=docker_utils.PROJECT_TO_IMAGE[project],
+  ):
+    sys.exit(1)

cli/casp/src/casp/tests/commands/test_reproduce.py

@@ -0,0 +1,154 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Tests for the reproduce command.
+
+  For running all the tests, use (from the root of the project):
+  python -m unittest discover -s cli/casp/src/casp/tests -p test_reproduce.py -v
+"""
+
+from pathlib import Path
+import unittest
+from unittest.mock import patch
+
+from casp.commands import reproduce
+from click.testing import CliRunner
+
+
+class ReproduceCliTest(unittest.TestCase):
+  """Tests for the reproduce command."""
+
+  def setUp(self):
+    self.runner = CliRunner()
+    self.mock_config = self.enterContext(
+        patch('casp.commands.reproduce.config', autospec=True))
+    self.mock_docker_utils = self.enterContext(
+        patch('casp.commands.reproduce.docker_utils', autospec=True))
+    self.mock_container = self.enterContext(
+        patch('casp.commands.reproduce.container', autospec=True))
+
+  def test_reproduce_success(self):
+    """Tests successful reproduction with default options."""
+    self.mock_config.load_and_validate_config.return_value = {
+        'gcloud_credentials_path': '/fake/credentials/path'
+    }
+    self.mock_docker_utils.prepare_docker_volumes.return_value = ({
+        '/fake/credentials': {
+            'bind': '/root/.config/gcloud/',
+            'mode': 'rw'
+        }
+    }, Path('/container/config/dir'))
+    self.mock_container.build_butler_command.return_value = ['run']
+    self.mock_docker_utils.run_command.return_value = True
+
+    result = self.runner.invoke(
+        reproduce.cli, ['--testcase-id', '123', '--project', 'internal'])
+
+    self.assertEqual(0, result.exit_code, msg=result.output)
+    self.mock_docker_utils.run_command.assert_called_once_with(
+        ['run'],
+        {'/fake/credentials': {
+            'bind': '/root/.config/gcloud/',
+            'mode': 'rw'
+        }},
+        privileged=True,
+        image=self.mock_docker_utils.PROJECT_TO_IMAGE['internal'],
+    )
+
+  def test_reproduce_success_with_custom_config(self):
+    """Tests successful reproduction with a custom config path."""
+    self.mock_config.load_and_validate_config.return_value = {
+        'gcloud_credentials_path': '/fake/credentials/path',
+        'custom_config_path': '/my/custom/config'
+    }
+    self.mock_docker_utils.prepare_docker_volumes.return_value = ({
+        '/fake/credentials': {
+            'bind': '/root/.config/gcloud/',
+            'mode': 'rw'
+        },
+        '/my/custom/config': {
+            'bind': '/container/custom/config',
+            'mode': 'rw'
+        }
+    }, Path('/container/custom/config'))
+    self.mock_container.build_butler_command.return_value = ['run']
+    self.mock_docker_utils.run_command.return_value = True
+
+    result = self.runner.invoke(
+        reproduce.cli, ['--testcase-id', '123', '--project', 'internal'])
+
+    self.assertEqual(0, result.exit_code, msg=result.output)
+    self.mock_docker_utils.run_command.assert_called_once()
+    self.mock_container.build_butler_command.assert_called_once_with(
+        'reproduce',
+        config_dir='/container/custom/config',
+        testcase_id='123',
+    )
+
+  def test_reproduce_no_config(self):
+    """Tests when no config is found."""
+    self.mock_config.load_and_validate_config.side_effect = SystemExit(1)
+    result = self.runner.invoke(
+        reproduce.cli, ['--testcase-id', '123', '--project', 'internal'])
+
+    self.assertEqual(1, result.exit_code)
+    self.mock_docker_utils.run_command.assert_not_called()
+
+  def test_reproduce_no_gcloud_credentials(self):
+    """Tests when gcloud credentials are not in the config."""
+    self.mock_config.load_and_validate_config.side_effect = SystemExit(1)
+    result = self.runner.invoke(
+        reproduce.cli, ['--testcase-id', '123', '--project', 'internal'])
+
+    self.assertEqual(1, result.exit_code)
+    self.mock_docker_utils.run_command.assert_not_called()
+
+  def test_reproduce_docker_command_fails(self):
+    """Tests when the docker command fails."""
+    self.mock_config.load_and_validate_config.return_value = {
+        'gcloud_credentials_path': '/fake/credentials/path'
+    }
+    self.mock_docker_utils.run_command.return_value = False
+    self.mock_docker_utils.prepare_docker_volumes.return_value = (
+        {}, Path('/mock/path'))
+    self.mock_container.build_butler_command.return_value = ['fail']
+
+    result = self.runner.invoke(
+        reproduce.cli, ['--testcase-id', '123', '--project', 'internal'])
+
+    self.assertEqual(1, result.exit_code)
+    self.mock_docker_utils.run_command.assert_called_once()
+
+  def test_reproduce_with_project_option(self):
+    """Tests that the --project option is passed to docker_utils."""
+    self.mock_config.load_and_validate_config.return_value = {
+        'gcloud_credentials_path': '/fake/credentials/path'
+    }
+    self.mock_docker_utils.prepare_docker_volumes.return_value = (
+        {}, Path('/mock/path'))
+    self.mock_container.build_butler_command.return_value = ['false']
+    self.mock_docker_utils.run_command.return_value = True
+    self.mock_docker_utils.PROJECT_TO_IMAGE = {'dev': 'dev-image'}
+
+    result = self.runner.invoke(reproduce.cli,
+                                ['--testcase-id', '123', '--project', 'dev'])
+
+    self.assertEqual(0, result.exit_code, msg=result.output)
+    self.mock_docker_utils.run_command.assert_called_once()
+    _, kwargs = self.mock_docker_utils.run_command.call_args
+    self.assertEqual(self.mock_docker_utils.PROJECT_TO_IMAGE['dev'],
+                     kwargs.get('image'))
+
+
+if __name__ == '__main__':
+  unittest.main()

cli/casp/src/casp/utils/config.py

@@ -21,21 +21,36 @@
 
 import json
 import os
+import sys
+from typing import Any
+
+import click
 
 CONFIG_DIR = os.path.expanduser('~/.casp')
 CONFIG_FILE = os.path.join(CONFIG_DIR, 'config.json')
 
 
-def save_config(data):
+def save_config(data: dict[str, Any]) -> None:
   """Saves configuration data."""
   os.makedirs(CONFIG_DIR, exist_ok=True)
   with open(CONFIG_FILE, 'w') as f:
     json.dump(data, f)
 
 
-def load_config():
+def load_config() -> dict[str, Any]:
   """Loads configuration data."""
   if not os.path.exists(CONFIG_FILE):
     return {}
   with open(CONFIG_FILE) as f:
     return json.load(f)
+
+
+def load_and_validate_config() -> dict[str, Any]:
+  """Loads and validates the configuration."""
+  cfg = load_config()
+  if not cfg or 'gcloud_credentials_path' not in cfg:
+    click.secho(
+        'Error: gcloud credentials not found. Please run "casp init".',
+        fg='red')
+    sys.exit(1)
+  return cfg

cli/casp/src/casp/utils/container.py

@@ -0,0 +1,52 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Container-specific utilities."""
+
+from pathlib import Path
+
+# The root directory for the ClusterFuzz source code inside the container.
+SRC_ROOT = Path('/data/clusterfuzz/src')
+
+# The path to the ClusterFuzz appengine directory inside the container.
+# This directory is the default location for ClusterFuzz configurations.
+CONTAINER_CONFIG_PATH = SRC_ROOT / 'appengine'
+
+# The path where gcloud credentials will be mounted inside the container.
+# This allows the container to authenticate with Google Cloud services.
+CONTAINER_CREDENTIALS_PATH = Path('/root/.config/gcloud/')
+
+# The base command prefix for executing ClusterFuzz butler commands.
+# This ensures that commands are run with the correct Python environment
+# and logging settings within the container.
+_COMMAND_PREFIX = 'pipenv run python butler.py --local-logging'
+
+
+def build_butler_command(subcommand: str, **kwargs: str) -> list[str]:
+  """Builds a butler command to be executed inside the container.
+
+  Args:
+    subcommand: The butler subcommand to execute (e.g., 'reproduce').
+    **kwargs: A dictionary of command-line arguments to pass to the subcommand.
+              For example, `testcase_id='123'` becomes
+              '--testcase-id=123'.
+
+  Returns:
+    A list of strings representing the command to be executed.
+  """
+  command = f'{_COMMAND_PREFIX} {subcommand}'
+  for key, value in kwargs.items():
+    key = key.replace('_', '-')
+    command += f' --{key}={value}'
+
+  return ['bash', '-c', command]