[CLI] Migrate format (#5035)

### Changes

This PR introduces a new `format` command to the `casp` CLI, which acts
as a convenient wrapper for the root `butler.py format` script. It also
adds a `casp.utils.path_utils` module that handles finding paths and
directories.
To enable `casp` to target specific directories for formatting, the
`butler.py format` command was updated to accept a `--dir` argument.
### How it works:
- `casp format` without arguments will format all changed files in the
current branch, preserving the default `butler` behavior.
- `casp format <path>` or `casp format --dir <path>` will now run the
formatter exclusively on the specified directory.

### Changes in butler

Regarding the refactor/improvement in `butler.py`, here are some
screenshots comparing running `python butler.py format` in this branch
and master. They show that the behavior is the same.

<img width="1152" height="48" alt="image"
src="https://github.com/user-attachments/assets/84975ad9-dc29-41a8-a199-f18c3fc33cd1"
/>

<img width="1152" height="49" alt="image"
src="https://github.com/user-attachments/assets/a3f77e21-8f84-4304-b95b-479c38bd250c"
/>


### Demo prints

Here are some screenshots of `casp format` in action:
<img width="1932" height="1109" alt="image"
src="https://github.com/user-attachments/assets/7144b1b7-b922-4d72-b521-ad7a85082e36"
/>

Author: PauloVLB

butler.py

@@ -98,6 +98,19 @@ def _setup_args_for_remote(parser):
   subparsers.add_parser('reboot', help='Reboot with `sudo reboot`.')
 
 
+def _add_format_subparser(toplevel_subparsers):
+  """Adds a parser for the `format` command."""
+  parser = toplevel_subparsers.add_parser(
+      'format', help='Format changed code in current branch.')
+  parser.add_argument(
+      '--path',
+      dest='path',
+      default=None,
+      help=
+      'The file or directory to format. Default is to format changed files in '
+      'the current branch.')
+
+
 def _add_integration_tests_subparsers(toplevel_subparsers):
   """Adds a parser for the `integration_tests` command."""
   toplevel_subparsers.add_parser(
@@ -295,8 +308,6 @@ def main():
       help=('Do not close browser when tests '
             'finish. Good for debugging.'))
 
-  subparsers.add_parser('format', help='Format changed code in current branch.')
-
   parser_lint = subparsers.add_parser(
       'lint', help='Lint changed code in current branch.')
   parser_lint.add_argument(
@@ -428,6 +439,7 @@ def main():
       default='us-central',
       help='Location for App Engine.')
 
+  _add_format_subparser(subparsers)
   _add_integration_tests_subparsers(subparsers)
   _add_weights_subparser(subparsers)
   _add_reproduce_subparser(subparsers)

cli/casp/src/casp/commands/format.py

@@ -11,12 +11,43 @@
 # 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.
-"""Format command."""
+"""Run format command."""
 
+import subprocess
+import sys
+
+from casp.utils import local_butler
 import click
 
 
-@click.command(name='format', help='Format changed code in current branch.')
-def cli():
-  """Format changed code in current branch."""
-  click.echo('To be implemented...')
+@click.command(name='format', help='Run format command')
+@click.argument('path', required=False, type=click.Path(exists=True))
+@click.option(
+    '--path',
+    '-p',
+    'path_option',
+    help='The file or directory to run the format command in.',
+    default=None,
+    type=click.Path(exists=True),
+    show_default=True)
+def cli(path: str, path_option: str) -> None:
+  """Run format command"""
+  target_dir = path_option or path
+
+  try:
+    if target_dir:
+      command = local_butler.build_command('format', path=target_dir)
+    else:
+      command = local_butler.build_command('format')
+  except FileNotFoundError:
+    click.echo('butler.py not found in this directory.', err=True)
+    sys.exit(1)
+
+  try:
+    subprocess.run(command, check=True)
+  except FileNotFoundError:
+    click.echo('python not found in PATH.', err=True)
+    sys.exit(1)
+  except subprocess.CalledProcessError as e:
+    click.echo(f'Error running butler.py format: {e}', err=True)
+    sys.exit(1)

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

@@ -0,0 +1,96 @@
+# 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 format 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_format.py -v
+"""
+
+from pathlib import Path
+import subprocess
+import unittest
+from unittest.mock import patch
+
+from casp.commands import format as format_command
+from click.testing import CliRunner
+
+
+class FormatCliTest(unittest.TestCase):
+  """Tests for the format command."""
+
+  def setUp(self):
+    self.runner = CliRunner()
+    self.mock_local_butler = self.enterContext(
+        patch('casp.commands.format.local_butler', autospec=True))
+    self.mock_subprocess_run = self.enterContext(
+        patch('subprocess.run', autospec=True))
+
+  def test_format_success_no_dir(self):
+    """Tests successful execution of `casp format` without a directory."""
+    self.mock_local_butler.build_command.return_value = ['cmd']
+    result = self.runner.invoke(format_command.cli)
+    self.assertEqual(0, result.exit_code, msg=result.output)
+    self.mock_local_butler.build_command.assert_called_once_with('format')
+    self.mock_subprocess_run.assert_called_once_with(['cmd'], check=True)
+
+  def test_format_success_with_path_option(self):
+    """Tests `casp format --path <some_dir>`."""
+    self.mock_local_butler.build_command.return_value = ['cmd']
+    with self.runner.isolated_filesystem():
+      Path('test_dir').mkdir()
+      result = self.runner.invoke(format_command.cli, ['--path', 'test_dir'])
+      self.assertEqual(0, result.exit_code, msg=result.output)
+      self.mock_local_butler.build_command.assert_called_once_with(
+          'format', path='test_dir')
+      self.mock_subprocess_run.assert_called_once_with(['cmd'], check=True)
+
+  def test_format_success_with_path(self):
+    """Tests `casp format <some_dir>` (positional argument)."""
+    self.mock_local_butler.build_command.return_value = ['cmd']
+    with self.runner.isolated_filesystem():
+      Path('test_dir').mkdir()
+      result = self.runner.invoke(format_command.cli, ['test_dir'])
+      self.assertEqual(0, result.exit_code, msg=result.output)
+      self.mock_local_butler.build_command.assert_called_once_with(
+          'format', path='test_dir')
+      self.mock_subprocess_run.assert_called_once_with(['cmd'], check=True)
+
+  def test_butler_not_found(self):
+    """Tests when `butler.py` is not found."""
+    self.mock_local_butler.build_command.side_effect = FileNotFoundError
+    result = self.runner.invoke(format_command.cli)
+    self.assertNotEqual(0, result.exit_code)
+    self.assertIn('butler.py not found', result.output)
+    self.mock_subprocess_run.assert_not_called()
+
+  def test_subprocess_run_fails(self):
+    """Tests when `subprocess.run` fails."""
+    self.mock_local_butler.build_command.return_value = ['cmd']
+    self.mock_subprocess_run.side_effect = subprocess.CalledProcessError(
+        1, 'cmd')
+    result = self.runner.invoke(format_command.cli)
+    self.assertNotEqual(0, result.exit_code)
+    self.assertIn('Error running butler.py format', result.output)
+
+  def test_python_not_found(self):
+    """Tests when `python` command is not found."""
+    self.mock_local_butler.build_command.return_value = ['cmd']
+    self.mock_subprocess_run.side_effect = FileNotFoundError
+    result = self.runner.invoke(format_command.cli)
+    self.assertNotEqual(0, result.exit_code)
+    self.assertIn('python not found in PATH', result.output)
+
+
+if __name__ == '__main__':
+  unittest.main()

cli/casp/src/casp/tests/utils/test_local_butler.py

@@ -0,0 +1,62 @@
+# 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 local_butler utility functions.
+
+  For running, use (from the root of the project):
+  python -m unittest discover -s cli/casp/src/casp/tests 
+  -p test_local_butler.py -v
+"""
+
+from pathlib import Path
+import unittest
+from unittest.mock import patch
+
+from casp.utils import local_butler
+
+
+class BuildCommandTest(unittest.TestCase):
+  """Tests for build_command."""
+
+  @patch('casp.utils.path_utils.get_butler_in_dir', autospec=True)
+  def test_build_command_success_auto_find(self, mock_get_butler):
+    """Tests successful command build finding butler automatically."""
+    mock_get_butler.return_value = Path('/fake/butler.py')
+
+    command = local_butler.build_command('format', some_arg='value')
+
+    self.assertEqual(
+        command, ['python', '/fake/butler.py', 'format', '--some-arg=value'])
+    mock_get_butler.assert_called_once()
+
+  def test_build_command_success_explicit_path(self):
+    """Tests successful command build with explicit butler path."""
+    butler_path = Path('/explicit/butler.py')
+
+    command = local_butler.build_command(
+        'format', butler_path=butler_path, verbose='true')
+
+    self.assertEqual(
+        command, ['python', '/explicit/butler.py', 'format', '--verbose=true'])
+
+  @patch('casp.utils.path_utils.get_butler_in_dir', autospec=True)
+  def test_butler_not_found(self, mock_get_butler):
+    """Tests validation when butler.py is not found."""
+    mock_get_butler.return_value = None
+
+    with self.assertRaises(FileNotFoundError):
+      local_butler.build_command('format')
+
+
+if __name__ == '__main__':
+  unittest.main()

cli/casp/src/casp/utils/local_butler.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.
+"""Local butler command utilities."""
+
+from pathlib import Path
+from typing import Optional
+
+from casp.utils import path_utils
+
+
+def build_command(subcommand: str,
+                  butler_path: Optional[Path] = None,
+                  **kwargs: str) -> list[str]:
+  """Builds a butler command for local execution.
+
+  Args:
+    subcommand: The butler subcommand to execute (e.g., 'format').
+    butler_path: The path to the butler.py file. If not provided, it will be
+      searched in the current directory.
+    **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.
+
+  Raises:
+    FileNotFoundError: If butler.py is not found.
+  """
+  if butler_path is None:
+    butler_path = path_utils.get_butler_in_dir(Path.cwd())
+
+  if not butler_path:
+    raise FileNotFoundError('butler.py not found.')
+
+  command = ['python', str(butler_path), subcommand]
+  for key, value in kwargs.items():
+    key = key.replace('_', '-')
+    command.append(f'--{key}={value}')
+
+  return command

cli/casp/src/casp/utils/path_utils.py

@@ -0,0 +1,30 @@
+# 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.
+"""Manages the CASP path search and management.
+
+This module provides a set of utilities related 
+to file and directory path manipulation and discovery.
+"""
+
+import os
+from pathlib import Path
+
+
+def get_butler_in_dir(start_path: Path) -> Path | None:
+  """Find and returns the butler.py script in the current directory"""
+  current_path = os.path.abspath(start_path)
+  butler_path = os.path.join(current_path, 'butler.py')
+  if os.path.exists(butler_path):
+    return Path(butler_path)
+  return None

src/local/butler/format.py

@@ -28,9 +28,11 @@
                  [f'-p {mod}' for mod in FIRST_PARTY_MODULES]) + ' ')
 
 
-def execute(_):
+def execute(args):
   """Format changed code."""
-  if os.path.exists('.git/FETCH_HEAD'):
+  if args.path:
+    diff_command = f'git ls-files {os.path.abspath(args.path)}'
+  elif os.path.exists('.git/FETCH_HEAD'):
     diff_command = 'git diff --name-only FETCH_HEAD'
   else:
     # If not, fall back to diffing against HEAD.