From db567de058ab7f1e6a30d42290b60f5ea685ec18 Mon Sep 17 00:00:00 2001 From: Nhomar Hernandez Date: Sat, 25 Apr 2026 21:34:00 -0600 Subject: [PATCH 1/2] [IMP] core: prevent agents in PTY from hanging and force AI instruction universally MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In environments where an agent operates inside an Integrated Terminal (like Cursor or Copilot), a Pseudo-TTY (PTY) is allocated. This causes the pre-commit hook to evaluate `[ -c /dev/tty ] && [ -t 1 ]` as TRUE, trapping the agent in the interactive `read` prompt indefinitely since agents cannot type "y". This commit improves the safety net by: 1. Adding a 10-second timeout (`-t 10`) to the interactive prompt. If no input is received (e.g. from an agent), it assumes "Y" and proceeds to run the linter. 2. Removing the `[ ! -c /dev/tty ]` condition from the failure instructions block. This ensures that the 🤖 AUTOMATION & AI AGENT INSTRUCTION is printed universally whenever the hook fails, serving as a vital recovery manual for both agents (in PTYs), headless CI environments, and human developers. --- src/pre_commit_vauxoo/git_hook_pre_commit | 32 ++++++++++++++++++----- 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/src/pre_commit_vauxoo/git_hook_pre_commit b/src/pre_commit_vauxoo/git_hook_pre_commit index f536b34..461f3a1 100755 --- a/src/pre_commit_vauxoo/git_hook_pre_commit +++ b/src/pre_commit_vauxoo/git_hook_pre_commit @@ -4,15 +4,35 @@ if [ "$NOLINT" == "1" ] || [ "$NOLINT" == true ]; then exit 0; fi if [ "$TRAVIS" != true ] && [ -z ${NOLINT+x} ]; then - read -p "Do you want to run pre-commit-vauxoo? (y/N): " yn ACTION: Run 'git status', 'git add ' and RETRY 'git commit'." + echo "2. LINTING: If Flake8/Pylint found errors, the code needs manual fixing." + echo " -> ACTION: Read the errors above, FIX the python code, 'git add', and RETRY 'git commit'." + echo "3. DO NOT silence lints without explicit user permission." + echo "=======================================================================================" + fi + exit $EXIT_CODE else echo '`pre-commit-vauxoo` not found. Did you forget to activate your virtualenv?' 1>&2 exit 1 From 9086a33825c78a31f3965d138b6d7ae96958563d Mon Sep 17 00:00:00 2001 From: Nhomar Hernandez Date: Sat, 25 Apr 2026 21:34:00 -0600 Subject: [PATCH 2/2] [ADD] .agents: Ship native AI skill to enforce pre-commit installation By embedding an AI agent skill directly into the pre-commit-vauxoo repository, developers can symlink this skill into their global AI environments (like ~/.gemini/antigravity/skills/). This natively teaches any AI agent working on 15+ different Odoo projects to ALWAYS verify and install pre-commit-vauxoo before making a commit, preventing silent CI failures and enforcing the ecosystem's quality rules. --- .agents/skills/vauxoo-pre-commit/SKILL.md | 60 +++++++++++++++++++++++ README.rst | 19 +++++++ 2 files changed, 79 insertions(+) create mode 100644 .agents/skills/vauxoo-pre-commit/SKILL.md diff --git a/.agents/skills/vauxoo-pre-commit/SKILL.md b/.agents/skills/vauxoo-pre-commit/SKILL.md new file mode 100644 index 0000000..a7f7805 --- /dev/null +++ b/.agents/skills/vauxoo-pre-commit/SKILL.md @@ -0,0 +1,60 @@ +--- +name: "vauxoo-pre-commit" +description: >- + Use this skill when you need to set up, execute, or troubleshoot pre-commit in Vauxoo and OCA repositories, or when preparing to commit code that must pass strict linting standards. + Triggers on: 'vauxoo/**' repos, 'oca/**' repos, 'lint', 'pre-commit', 'format code', 'new project'. +last_validated: "2026-04-25" +--- + +# Skill: Vauxoo / OCA Pre-Commit Protocol + +This skill enforces the mandatory linting and formatting standards required for any code landing in a `vauxoo/***` or `oca/***` Odoo repository. + +> [!IMPORTANT] +> **This code will land in a strict CI environment.** +> If you do not pass these checks, the pipeline WILL fail, the Merge Request will be blocked, and you will put the next developer (or agent) through hell trying to clean up your mess. +> **DO NOT SILENCE LINTS** (`# noqa`, `# pylint: disable=...`) without explicit, documented permission from the user. + +--- + +## 1. Installation & Environment Check + +Before making your first commit in a new or recently cloned repository, you MUST verify that the git hooks are installed. + +1. **Verify Installation:** Check if `.git/hooks/pre-commit` exists. +2. **Install if missing:** If it does not exist, you must install the hooks within the Python virtual environment: + ```bash + pip install pre-commit-vauxoo + pre-commit install + ``` +3. **Never bypass:** Do not attempt to commit code if the repository does not have the pre-commit hook installed. + +## 2. The Headless TTY Trap (Legacy Systems) + +> [!WARNING] +> **Historical Context:** In headless AI agent environments, `git commit` does **NOT** have an interactive TTY. +> Legacy versions of the Vauxoo git hook (prior to PR #222) would prompt the user: *"Do you want to run pre-commit-vauxoo?"*. Without a TTY, this prompt silently failed or hung the agent indefinitely. + +Because of this legacy trap on older repositories, **if you are unsure if the hook is updated, you must run the linter manually.** + +## 3. Mandatory Execution Flow + +1. **Run the linter explicitly:** + ```bash + pre-commit run --files + ``` + *Or for all files:* + ```bash + pre-commit run -a + ``` + +2. **Handle Formatting Auto-Fixes (Black, isort):** + If the pre-commit output shows that files were modified/reformatted, your Git working tree is now dirty. + - **ACTION:** You must run `git add ` again to stage the auto-formatted changes. + +3. **Handle Linting Errors (Flake8, Pylint):** + If the output shows errors (e.g., `F841 unused variable`): + - **ACTION:** Stop, read the logs, fix the python code manually, `git add` the fixes, and run `pre-commit run` again until it passes cleanly. + +4. **Commit:** + Only execute `git commit` when you are absolutely certain the code passes the linters or the hook has auto-formatted and you have staged those changes. diff --git a/README.rst b/README.rst index 23802a0..0176c5b 100644 --- a/README.rst +++ b/README.rst @@ -235,6 +235,25 @@ Full --help command result: .. https://pre-commit-vauxoo.readthedocs.io/ +AI Agents Integration +===================== + +``pre-commit-vauxoo`` natively ships with an AI Agent Skill (located in the ``.agents/skills/`` directory). This skill provides context to your AI assistants (such as Cursor, Claude Desktop, or Gemini) on how to properly handle pre-commit hooks in Vauxoo and OCA repositories, preventing silent CI failures and handling headless TTY environments correctly. + +To enable this globally across all your projects, create a symbolic link from your local clone of ``pre-commit-vauxoo`` to your global AI skills directory. + +For **Gemini / Antigravity**: +:: + + ln -sfn /path/to/your/clone/pre-commit-vauxoo/.agents/skills/vauxoo-pre-commit ~/.gemini/antigravity/skills/vauxoo-pre-commit + +For **Cursor** (using custom rules): +:: + + ln -sfn /path/to/your/clone/pre-commit-vauxoo/.agents/skills/vauxoo-pre-commit/SKILL.md ~/.cursorrules_precommit + +Once linked, your AI agents will automatically know they must verify and enforce ``pre-commit`` rules before attempting to commit code in the ecosystem. + Development ===========