From ec2ba9a9c6a2b7c07a58ca946552c24d7b036315 Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Thu, 23 Apr 2026 11:56:54 +1200 Subject: [PATCH 1/4] feat(skills): add building-integration skill for local build/validation pipeline --- skills/building-integration/SKILL.md | 118 +++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 skills/building-integration/SKILL.md diff --git a/skills/building-integration/SKILL.md b/skills/building-integration/SKILL.md new file mode 100644 index 0000000..27f04b4 --- /dev/null +++ b/skills/building-integration/SKILL.md @@ -0,0 +1,118 @@ +--- +name: building-integration +description: "Runs the local build and validation pipeline for an Autohive integration — structure validation, code quality checks, linting, formatting, security scanning, and unit tests. Use when asked to build, validate, check, or verify an integration before pushing." +--- + +# Building & Validating an Integration Locally + +Run the same checks CI runs, locally, before pushing. + +## Prerequisites + +The tooling repo must be cloned alongside the integrations repo: + +``` +parent-dir/ +├── autohive-integrations/ ← you are here +└── autohive-integrations-tooling/ ← must exist +``` + +The integrations repo must have a `.venv` with Python 3.13+ and test dependencies installed: + +```bash +source .venv/bin/activate +uv pip install -r requirements-test.txt +``` + +## Build Pipeline + +Run these steps in order from the integrations repo root. Replace `` with the integration folder name (e.g., `clickup`). + +### Step 1 — Install integration dependencies + +```bash +source .venv/bin/activate +uv pip install -r /requirements.txt +``` + +### Step 2 — Structure validation + +```bash +python ../autohive-integrations-tooling/scripts/validate_integration.py +``` + +Checks: folder naming, required files (`config.json`, `requirements.txt`, `README.md`, icon, tests/`), config.json schema, auth config, action definitions, SDK version pinning, test structure. + +Exit codes: `0` = passed, `1` = errors found, `2` = processing error. + +### Step 3 — Code quality checks + +```bash +python ../autohive-integrations-tooling/scripts/check_code.py +``` + +Runs (in order): dependency install, Python syntax, import resolution, JSON validity, ruff lint, ruff format, bandit security scan, pip-audit, config-code sync, fetch pattern check. + +Exit codes: `0` = passed, `1` = failures found. + +### Step 4 — Unit tests + +```bash +pytest / -v +``` + +Only runs tests in `test_*_unit.py` files (configured in `pyproject.toml`). + +### Step 5 — Auto-fix lint and formatting issues + +If steps 2–4 report ruff errors, auto-fix with: + +```bash +ruff check --fix --config ../autohive-integrations-tooling/ruff.toml +ruff format --config ../autohive-integrations-tooling/ruff.toml +``` + +Then re-run steps 2–4 to confirm. + +## Ruff Configuration + +CI uses the `ruff.toml` from the tooling repo — always pass `--config ../autohive-integrations-tooling/ruff.toml` to match CI behavior. + +Key settings: +- `target-version = "py313"` +- `line-length = 120` +- Rules: `E` (pycodestyle errors), `F` (Pyflakes), `W` (pycodestyle warnings) +- `__init__.py`: `F401` ignored (re-exports) +- `**/tests/context.py`: `F401`, `E402` ignored + +## Workflow Summary + +1. Install deps → `uv pip install -r /requirements.txt` +2. Validate structure → `python ../autohive-integrations-tooling/scripts/validate_integration.py ` +3. Check code → `python ../autohive-integrations-tooling/scripts/check_code.py ` +4. Run tests → `pytest / -v` +5. Fix issues → `ruff check --fix ...` / `ruff format ...` +6. Re-run until all pass + +## Interpreting Output + +### validate_integration.py +- `❌` = Error — must fix before PR +- `⚠️` = Warning — review but won't block CI +- Final summary shows total errors/warnings across all integrations + +### check_code.py +- Each check prints `✅` or `❌` with details +- All checks run even if one fails (no short-circuit) +- Final line: `✅ CODE CHECK PASSED` or `❌ CODE CHECK FAILED` + +### Common Failures and Fixes + +| Failure | Fix | +|---|---| +| Ruff lint errors | `ruff check --fix --config ../autohive-integrations-tooling/ruff.toml ` | +| Ruff format errors | `ruff format --config ../autohive-integrations-tooling/ruff.toml ` | +| Bandit security issue | Add `# nosec B105` for test credential strings; fix real issues | +| Config-code sync | Ensure actions in `config.json` match handlers in source code | +| Missing test files | Create `tests/test__unit.py` (see `writing-unit-tests` skill) | +| Import errors | Check `requirements.txt` has all dependencies; check `__init__.py` exports | From 3422671ba816ec23967bc38aa565134934c78e2d Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Thu, 23 Apr 2026 12:01:11 +1200 Subject: [PATCH 2/4] docs(skills): add preflight checks for missing dependencies and tooling --- skills/building-integration/SKILL.md | 81 +++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 2 deletions(-) diff --git a/skills/building-integration/SKILL.md b/skills/building-integration/SKILL.md index 27f04b4..8355597 100644 --- a/skills/building-integration/SKILL.md +++ b/skills/building-integration/SKILL.md @@ -7,7 +7,11 @@ description: "Runs the local build and validation pipeline for an Autohive integ Run the same checks CI runs, locally, before pushing. -## Prerequisites +## Preflight Checks + +Run these checks **before** starting the build pipeline. Fix any that fail. + +### 1. Tooling repo The tooling repo must be cloned alongside the integrations repo: @@ -17,13 +21,86 @@ parent-dir/ └── autohive-integrations-tooling/ ← must exist ``` -The integrations repo must have a `.venv` with Python 3.13+ and test dependencies installed: +Check: `ls ../autohive-integrations-tooling/scripts/validate_integration.py` + +If missing, clone it: + +```bash +git clone https://github.com/autohive-ai/autohive-integrations-tooling.git ../autohive-integrations-tooling +``` + +### 2. Python 3.13+ + +Check: `python3 --version` (must be 3.13+) + +If not available, install with uv: + +```bash +uv python install 3.13 +``` + +Or use your system package manager / pyenv. + +### 3. Virtual environment + +Check: `ls .venv/bin/python` + +If missing, create it: + +```bash +uv venv --python 3.13 .venv +``` + +Or without uv: + +```bash +python3.13 -m venv .venv +``` + +Always activate before running any commands: ```bash source .venv/bin/activate +``` + +### 4. Package installer + +Check: `which uv` or `which pip` + +uv is preferred. If neither is available, install uv: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +### 5. Test dependencies + +Check: `python -c "import pytest"` (from within the activated venv) + +If missing, install: + +```bash uv pip install -r requirements-test.txt ``` +Or with pip: + +```bash +pip install -r requirements-test.txt +``` + +### 6. Ruff + +Check: `ruff --version` (from within the activated venv) + +If missing, install: + +```bash +uv pip install ruff +``` + +Note: `check_code.py` auto-installs ruff when it runs, but you need it locally for the manual auto-fix commands in Step 5. + ## Build Pipeline Run these steps in order from the integrations repo root. Replace `` with the integration folder name (e.g., `clickup`). From 80cff6bea113230fd2f3f8df138f1b69bae85c2a Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Thu, 23 Apr 2026 12:09:21 +1200 Subject: [PATCH 3/4] docs: add all skills to README files --- README.md | 3 +++ skills/README.md | 1 + 2 files changed, 4 insertions(+) diff --git a/README.md b/README.md index f1e62a8..f652a94 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,10 @@ The [`skills/`](skills/) directory contains agent skills for AI coding assistant | Skill | Description | |-------|-------------| +| [`building-integration`](skills/building-integration/) | Runs the local build and validation pipeline (structure, lint, format, security, tests) | | [`upgrading-sdk-v2`](skills/upgrading-sdk-v2/) | Upgrades an integration from SDK 1.x to 2.0.0 — covers source code, tests, requirements, and config | +| [`writing-unit-tests`](skills/writing-unit-tests/) | Writes pytest unit tests using mock_context + FetchResponse | +| [`writing-integration-tests`](skills/writing-integration-tests/) | Writes pytest e2e tests that call real APIs using the live_context fixture | To use a skill, copy or symlink it into your workspace's `.agents/skills/` directory or your global `~/.config/agents/skills/` directory. See [`skills/README.md`](skills/README.md) for setup instructions. diff --git a/skills/README.md b/skills/README.md index 50647f2..5029e11 100644 --- a/skills/README.md +++ b/skills/README.md @@ -6,6 +6,7 @@ Agent skills for AI coding assistants (Amp, Claude Code, etc.) that automate com | Skill | Description | |-------|-------------| +| [`building-integration/`](building-integration/) | Runs the local build and validation pipeline (structure, lint, format, security, tests) | | [`upgrading-sdk-v2/`](upgrading-sdk-v2/) | Upgrades an integration from SDK 1.x to 2.0.0 | | [`writing-unit-tests/`](writing-unit-tests/) | Writes pytest unit tests for an integration using mock_context + FetchResponse | | [`writing-integration-tests/`](writing-integration-tests/) | Writes pytest e2e integration tests that call real APIs using the live_context fixture | From 6d0665aa1bcf06c589af8675d3fcc14cfa5ebb59 Mon Sep 17 00:00:00 2001 From: Kai Koenig Date: Thu, 23 Apr 2026 12:17:37 +1200 Subject: [PATCH 4/4] fix(skills): add pip fallback for dependency install step --- skills/building-integration/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/skills/building-integration/SKILL.md b/skills/building-integration/SKILL.md index 8355597..3ff3ff7 100644 --- a/skills/building-integration/SKILL.md +++ b/skills/building-integration/SKILL.md @@ -110,6 +110,7 @@ Run these steps in order from the integrations repo root. Replace `` with ```bash source .venv/bin/activate uv pip install -r /requirements.txt +# Or with pip: pip install -r /requirements.txt ``` ### Step 2 — Structure validation @@ -164,7 +165,7 @@ Key settings: ## Workflow Summary -1. Install deps → `uv pip install -r /requirements.txt` +1. Install deps → `uv pip install -r /requirements.txt` (or `pip install -r /requirements.txt`) 2. Validate structure → `python ../autohive-integrations-tooling/scripts/validate_integration.py ` 3. Check code → `python ../autohive-integrations-tooling/scripts/check_code.py ` 4. Run tests → `pytest / -v`