Sync fork

.agents/config.yaml

@@ -0,0 +1,21 @@
+# 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.
+
+# Custom configuration guide: https://developers.google.com/gemini-code-assist/docs/customize-gemini-behavior-github?content_ref=the+gemini+folder+hosts+any+gemini+code+assist+related+configuration+files+like+config+yaml+and+styleguide+md#custom-configuration
+
+code_review:
+  pull_request_opened:
+    code_review: true
+    summary: true
+    include_drafts: false

.agents/skills/build/SKILL.md

@@ -0,0 +1,80 @@
+# GCSFuse Build and Style Verification Skill
+
+This skill provides a highly streamlined workflow for Antigravity agents to compile the GCSFuse codebase, verify layout formats, resolve imports, and perform static analysis checks. Executing this unified validation runbook ensures all changes are cleanly compiled and formatted exactly to the repository's strict standards before proposing pull requests.
+
+---
+
+## 1. Context and Target Standards
+
+GCSFuse uses a strict presubmit verification pipeline to ensure code hygiene and layout correctness. The root-level [Makefile](../../../Makefile) is the single-source-of-truth configuration orchestrator.
+
+Running `make build` automatically handles the entire verification chain. Agents must not execute individual compilation or formatting steps manually unless explicitly instructed by this runbook.
+
+```mermaid
+graph TD
+    A[make build] --> B[Run imports, formatting, and dependency sorting]
+    B --> C[Run code compiler verification checks]
+```
+
+Executing `make build` automatically executes and verifies the following operations:
+* **Code Generation**: Triggers `go generate` to build auto-generated structures.
+* **Auto-Imports & Formatting**: Automatically runs `goimports` and `go fmt` to align headers and style of all updated files.
+* **Dependency Hygiene**: Runs `go mod tidy` to clean up and sync local package lists.
+* **Static Analysis Checks**: Runs `go vet` to intercept logical and syntax issues early.
+* **Style Compliance**: Runs `golangci-lint` to check code cleanliness against `master`.
+* **Binary Compilation**: Builds all target packages under the root directory.
+
+---
+
+## 2. Step-by-Step Verification Workflow
+
+### Step 1: Align Go Toolchain
+1. Inspect the targeted Go compiler version specified in the root [.go-version](../../../.go-version) file (currently **`1.26.3`**).
+2. Check the active compiler version:
+   ```bash
+   go version
+   ```
+3. If there is a major/minor version mismatch with the target baseline series, notify the user immediately before compiling, as version mismatches can introduce syntax regressions.
+
+### Step 2: Run Unified Verification Target
+Run the comprehensive validation suite from the root of the workspace:
+```bash
+make build
+```
+* **Verification Success**: The build target finishes with exit code `0`.
+* **Verification Failure**: If the build target fails, analyze the output:
+  * **Compilation/Syntax Errors**: Correct the source files and re-run `make build`.
+  * **Lint Issues**: Resolve style warnings flagged by the linter.
+
+### Step 3: Stage & Commit Automatic Formatting
+Because `make build` runs auto-formatters and import organizers in-place, the workspace might receive automatic layout corrections.
+
+1. Inspect the working tree for any modifications automatically made by the build:
+   ```bash
+   git status
+   ```
+2. Inspect formatting diffs:
+   ```bash
+   git diff --exit-code --name-only
+   ```
+3. **Commit Rule**: If formatting changes exist, **commit these automatic corrections** directly alongside your functional changes. Clean formatting is a mandatory PR check block.
+
+---
+
+## 3. Graceful Warning Fallbacks
+
+### Style Linters Failure
+`golangci-lint` is required under the `make build` pipeline. In sandboxed or offline local developer environments, this check can occasionally fail or time out:
+* > [!WARNING]
+* > Do **NOT** treat local linter warnings or execution failures as a blocking compilation failure.
+* If standard compiling passes but the linter blocks execution, log a warning to the user noting that linting was bypassed, and proceed.
+
+---
+
+## 4. Compilation Verification Checklist
+
+Before final project handoff, verify the following checks:
+
+- [ ] **Toolchain Sync**: My active `go version` aligns with the project’s [.go-version](../../../.go-version) file directive.
+- [ ] **Verification Clean**: Successfully compiled using `make build` without errors.
+- [ ] **Hygiene Staged**: Any auto-formatting, import sorting, or dependency adjustments made by the Makefile are committed to the branch tree.

.agents/skills/dep-upgrade/SKILL.md

@@ -0,0 +1,195 @@
+# GCSFuse Dependency Upgrading Skill
+
+This skill provides a comprehensive, step-by-step workflow for Antigravity agents to identify, upgrade, and verify external dependencies and Go toolchain versions in the GCSFuse repository, specifically targeting the remediation of CVEs and security vulnerabilities.
+
+---
+
+## 1. Parsing Input & Discovering Vulnerabilities
+
+The user initiates this skill by providing one of the following inputs:
+
+### Input Option A: Specific Dependencies to Upgrade
+* The user explicitly specifies the module(s) and/or Go version to upgrade (e.g., "Upgrade `google.golang.org/protobuf` to latest", "Upgrade Go to 1.27.0").
+* Identify the exact module path(s) and target version(s).
+
+### Input Option B: Bug / Vulnerability Reference
+* The user specifies a bug reference, issue ID, or CVE ID (e.g., "Fix security issues mentioned in b/123456" or "Fix CVE-2026-12345").
+* **Workflow for Option B**:
+  1. Retrieve the full details of the issue, bug description, or external CVE details.
+  2. Analyze the issue content or logs to find the vulnerable dependencies (e.g., `golang.org/x/net` before `v0.17.0`) or Go standard library vulnerabilities.
+  3. If the bug mentions Go standard library vulnerabilities (e.g., `Found in: net/http@go1.26.2`, `Fixed in: net/http@go1.26.3`), identify the new target Go compiler version.
+  4. Produce a list of target packages and their minimum safe versions.
+
+---
+
+## 2. Querying Versions & Major Upgrade Safety Checks
+
+Before executing any dependency upgrades, identify the target versions and evaluate them for major breaking changes.
+
+### Core Directive
+* **Default Target**: Always aim to upgrade dependencies to their **latest stable version**.
+* **Upgrade Limit**: You may automatically upgrade dependencies to their latest minor or patch versions (e.g., `v1.2.0` -> `v1.5.3`). However, if upgrading to the latest stable version requires a **major version change**, you must halt and ask the user for permission (as detailed in Step 2).
+
+### Step 1: Query Available Versions
+List all available stable versions of the target Go module to find the latest stable release:
+```bash
+go list -m -versions <module_path>
+```
+*Example:*
+```bash
+go list -m -versions go.opentelemetry.io/otel/sdk
+```
+
+### Step 2: Version Comparison & Safety Checks
+Compare the current version of the dependency in `go.mod` against the proposed target/latest version.
+
+* **Major Version Check Rule**:
+  If the proposed upgrade involves a **major version change** (e.g., upgrading `github.com/pkg/errors` from `v0.9.1` to `v2.0.0`, or any package whose import path or major version number increments):
+  1. **Stop immediately.**
+  2. **Alert the user**: Notify them that a major version upgrade is breaking, will require changing module import paths in `.go` files, and could introduce API incompatibilities.
+  3. **Ask for permission** before proceeding.
+  4. Do NOT proceed with the upgrade unless the user explicitly approves.
+
+* **No Downgrades Rule**:
+  If the proposed target version is lower/older than the current version in `go.mod`:
+  1. **Stop immediately.**
+  2. **Alert the user**: Notify them that the target version represents a downgrade (e.g., going from `v1.5.0` to `v1.3.0`).
+  3. **Ask for permission**: Do NOT proceed with a downgrade unless the user explicitly instructs or approves it.
+
+* If the upgrade to the latest version is a minor or patch version change (e.g., `v1.2.0` to `v1.3.5`) and is a strictly higher version, proceed automatically.
+
+---
+
+## 3. Dependency Upgrade Workflow
+
+To upgrade standard Go modules (non-toolchain libraries):
+
+### Guidelines
+1. **Focus on Direct Dependencies**: Only upgrade direct dependencies directly. Do not manually upgrade indirect dependencies unless the corresponding direct dependency is also being upgraded. Let `go mod tidy` resolve and update indirect dependencies automatically based on the upgraded direct dependencies.
+2. **Lock Version Precisely**: Do not use wildcard upgrades if a specific fixed version is known.
+3. **Upgrade Co-dependencies (Peer Packages)**: Upgrading a core library (like `go.opentelemetry.io/otel/sdk`) often requires upgrading peer packages (like `go.opentelemetry.io/otel` or contribution/instrumentation packages like `otelhttp`) to the same version to prevent Skew/API conflicts.
+
+### Commands
+
+#### Case A: Upgrading All/General Dependencies
+If you are asked to upgrade all or general dependencies, run the following command to upgrade **only the direct dependencies** to their latest minor/patch versions:
+```bash
+go get $(go list -f '{{if not (or .Main .Indirect)}}{{.Path}}{{end}}' -m all)
+```
+Then, run `go mod tidy` to let Go resolve and update the indirect dependencies and clean up `go.mod` and `go.sum`:
+```bash
+go mod tidy
+```
+
+#### Case B: Upgrading Specific Dependencies
+If you are asked to upgrade specific dependencies:
+1. Run the `go get` command for the target package(s) and its direct dependencies:
+   ```bash
+   go get <module_path>@<target_version> [peer_package]@[target_version] ...
+   ```
+2. Tidy up the module definition files (`go.mod` and `go.sum`):
+   ```bash
+   go mod tidy
+   ```
+
+---
+
+## 4. Go Toolchain & Standard Library Upgrades
+
+Standard library vulnerabilities (e.g., in `net/http` or `html/template`) cannot be patched via `go get`. They require upgrading the Go toolchain/compiler version itself across the entire repository.
+
+### Core Directives for Go Version Upgrades
+
+1. **Target Go Version Rule**:
+   * **Default Target**: When upgrading the Go compiler/toolchain (whether for standard library CVE fixes, general feature upgrades, or dependency requirements), **always upgrade to the latest stable available version of Golang**, unless a specific target version is explicitly requested by the user or hardcoded in the bug description.
+   * > [!IMPORTANT]
+   * > If the upgrade involves a major/minor version change (e.g., moving the repository from Go `1.23.x` to a newer series like `1.26.x`), **upgrade to the latest available stable release of that new series** (e.g., the absolute latest stable release `1.26.3` or newer), instead of just targetting the baseline first release of the series (e.g., `1.26.0`), unless explicitly specified otherwise by the user or the bug.
+   * Verify the latest stable version of Go via the web search tool or Go's official download site before finalizing the target version.
+
+2. **Absolute Go Version Consistency**:
+   * **Strict Consistency Requirement**: The **exact same** three-part (patch-level) Go version string (e.g., `1.26.3`) must be applied globally across the entire repository. There must be absolutely no version mismatch or inconsistency.
+    * **Consistency in [go.mod](../../../go.mod)**: The `go` directive in [go.mod](../../../go.mod) **MUST be updated to match the exact patch-level version string** (e.g., `go 1.26.3`), aligning it completely with [.go-version](../../../.go-version). Do NOT use minor-only shorthand (e.g., `go 1.26`) in [go.mod](../../../go.mod) while using a three-part version string elsewhere.
+    * Every single reference to the Go compiler in main builder images, packaging Dockerfiles, presubmit checks, performance suites, and CD scripts must be kept strictly uniform.
+
+### Step 1: Retrieve Current Go Version
+Look at the [.go-version](../../../.go-version) file in the root directory, or the `go` directive in [go.mod](../../../go.mod) (e.g., `go 1.26.3`) to identify the old Go version string.
+
+### Step 2: Determine and Query the Target Go Version
+1. Identify the minimum safe version required (e.g., if remediating a CVE).
+2. Query the web or official resources to find the **latest stable available version** of the Go compiler (within the target major/minor release, or a newer release series if upgrading Go major/minor versions).
+3. Set this **latest available version** as the exact target Go version string (e.g., `1.26.3`).
+
+### Step 3: Search the Entire Repository
+Search the codebase using `grep` to find all instances of the old Go version string (e.g., `1.26.3`):
+```bash
+# Example grep query using the search tool:
+Query: "1.26.3"
+SearchPath: "<workspace_root>"
+```
+
+*Key Go Version Reference Locations that MUST match exactly:*
+1. **[.go-version](../../../.go-version)**:
+   *Located at the root of the repository.*
+   * **Mandatory Action**: Ensure this file contains the exact target Go version (e.g., `1.26.3`).
+2. **[go.mod](../../../go.mod)**:
+   * **Mandatory Action**: Ensure the `go` directive matches the exact patch-level version string (e.g., `go 1.26.3`). Do NOT use two-part versions here.
+   ```diff
+   -go 1.26.3
+   +go 1.27.1
+   ```
+3. **[Dockerfile](../../../Dockerfile)** (Main Builder Image at root)
+4. **Packaging Dockerfiles**:
+   * **[Dockerfile](../../../tools/containerize_gcsfuse_docker/Dockerfile)** (Containerization base image)
+   * **[Dockerfile](../../../tools/package_gcsfuse_docker/Dockerfile)** (Packaging base image. Make sure to align *both* the builder baseline tag `FROM golang:X.Y.Z` and the download command `goX.Y.Z.linux` to match the exact same version string).
+5. **E2E & Integration Test Scripts**:
+   * **[e2e_test.sh](../../../tools/cd_scripts/e2e_test.sh)**
+   * **[run_e2e_tests.sh](../../../tools/integration_tests/run_e2e_tests.sh)**
+   * **[improved_run_e2e_tests.sh](../../../tools/integration_tests/improved_run_e2e_tests.sh)**
+6. **Performance & Presubmit Test Scripts**:
+   * **[build.sh](../../../perfmetrics/scripts/presubmit_test/pr_perf_test/build.sh)**
+   * **[setup.sh](../../../perfmetrics/scripts/read_cache/setup.sh)**
+   * **[run_checkpoints.sh](../../../perfmetrics/scripts/ml_tests/checkpoint/Jax/run_checkpoints.sh)**
+
+### Step 4: Replace All References
+Update every file identified in Step 3, substituting the old Go version with the new exact target Go version. Ensure that no minor-only (e.g. `1.26` instead of `1.26.3`) or mismatched version strings exist.
+
+### Step 5: Sync and Tidy
+Run `go mod tidy` to ensure `go.mod` and `go.sum` are consistent and fully synchronized.
+
+---
+
+## 5. Compilation & Verification
+
+After upgrading dependencies and/or the Go toolchain, verify the integrity and safety of the changes.
+
+### Compile Check
+Verify that the entire codebase builds cleanly with no compile-time regressions:
+```bash
+make build
+```
+
+### Run Vulnerability Scan
+Verify that all active CVEs are completely cleared. First, ensure `govulncheck` is installed on the system, and install it if it is missing:
+```bash
+# Check if govulncheck is installed, if not, attempt to install it and expose $(go env GOPATH)/bin in PATH
+if ! command -v govulncheck &> /dev/null; then
+  go install golang.org/x/vuln/cmd/govulncheck@latest || true
+  export PATH=$PATH:$(go env GOPATH)/bin
+fi
+```
+Then attempt to run the vulnerability scan.
+> [!IMPORTANT]
+> If `govulncheck` fails to install or run (e.g., due to offline environments, missing access to external proxies, or toolchain configuration limits), **do NOT treat this failure as a critical blocker**. Log a warning to the user, note the issue in your summary, and proceed to running the test suite to complete the dependency upgrade.
+
+If the utility is available, run the scan:
+```bash
+govulncheck ./...
+```
+*Result:* The scan should report `Your code is affected by 0 vulnerabilities`.
+
+### Run Tests
+Verify that the test suite passes successfully with the upgraded dependencies:
+```bash
+go test ./...
+```
+