feat: Add AGENTS.md and fix lint/format scripts (#4921)

This change adds a new `AGENTS.md` file to guide developers and agents
through the complete setup process for this project. It also includes
necessary fixes to the dependency installation and linting/formatting
scripts to ensure they run correctly on modern systems and in CI/agent
environments.

---------

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: google-labs-jules[bot]

AGENTS.md

@@ -0,0 +1,86 @@
+# Agent Instructions
+
+This document provides instructions for agents on how to perform common development tasks in this repository.
+
+## Initial Setup
+
+This project uses `asdf` to manage tool versions. Before you can install the project's dependencies, you need to install and configure `asdf`.
+
+### 1. Install `asdf`
+
+First, make sure you have `git` and `curl` installed. Then, clone the `asdf` repository:
+
+```bash
+git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0
+```
+
+### 2. Configure Your Shell
+
+Add `asdf` to your shell's startup file. For `bash`, run:
+
+```bash
+echo -e "\n. \"$HOME/.asdf/asdf.sh\"" >> ~/.bashrc
+```
+
+Then, source your `.bashrc` to apply the changes to your current session:
+
+```bash
+source ~/.bashrc
+```
+
+### 3. Install `asdf` Plugins and Tools
+
+Now, from the root of this project, run the following commands to install the necessary `asdf` plugins and the tools specified in the `.tool-versions` file:
+
+```bash
+asdf plugin add python
+asdf plugin add gcloud https://github.com/jthegedus/asdf-gcloud
+asdf install
+```
+
+### 4. Install `pipenv`
+
+Once `asdf` has installed the correct python version, you need to install `pipenv`:
+
+```bash
+python -m pip install pipenv
+```
+
+### 5. Install Project Dependencies
+
+Now you are ready to install the project's dependencies. Run the following command from the root of the repository:
+
+```bash
+./local/install_deps.bash
+```
+
+## Testing
+
+To run all unit tests, execute the following commands:
+
+```bash
+python butler.py py_unittest -t appengine -m
+python butler.py py_unittest -t core -m
+```
+
+The `-m` flag runs the tests in parallel, which is recommended.
+
+## Linting
+
+To check the code for style and linting issues, run the following command:
+
+```bash
+python butler.py lint
+```
+
+This will lint the changed code in your current branch.
+
+## Formatting
+
+To automatically format the code to match the project's style guidelines, run:
+
+```bash
+python butler.py format
+```
+
+This will format the changed code in your current branch.

local/install_deps_linux.bash

@@ -54,7 +54,7 @@ fi
 # Check if the distro is supported.
 distro_codename=$(lsb_release --codename --short)
 distro_id=$(lsb_release --id --short)
-supported_codenames="(xenial|artful|bionic|cosmic|focal)"
+supported_codenames="(xenial|artful|bionic|cosmic|focal|noble)"
 supported_ids="(Debian)"
 if [[ ! $distro_codename =~ $supported_codenames &&
       ! $distro_id =~ $supported_ids ]]; then

src/local/butler/format.py

@@ -30,8 +30,13 @@
 
 def execute(_):
   """Format changed code."""
-  _, output = common.execute('git diff --name-only FETCH_HEAD')
+  if os.path.exists('.git/FETCH_HEAD'):
+    diff_command = 'git diff --name-only FETCH_HEAD'
+  else:
+    # If not, fall back to diffing against HEAD.
+    diff_command = 'git diff --name-only HEAD'
 
+  _, output = common.execute(diff_command)
   file_paths = [
       f.decode('utf-8') for f in output.splitlines() if os.path.exists(f)
   ]

src/local/butler/lint.py

@@ -178,10 +178,15 @@ def execute(args):
 
   if 'GOOGLE_CLOUDBUILD' in os.environ:
     # Explicitly compare against master if we're running on the CI
-    _, output = common.execute('git diff --name-only master FETCH_HEAD')
+    diff_command = 'git diff --name-only master FETCH_HEAD'
   else:
-    _, output = common.execute('git diff --name-only FETCH_HEAD')
+    if os.path.exists('.git/FETCH_HEAD'):
+      diff_command = 'git diff --name-only FETCH_HEAD'
+    else:
+      # If not, fall back to diffing against HEAD.
+      diff_command = 'git diff --name-only HEAD'
 
+  _, output = common.execute(diff_command)
   file_paths = [
       f.decode('utf-8') for f in output.splitlines() if os.path.exists(f)
   ]