Imported from erdemhalil/atlassian-client (AGENTS.md). Install upstream with npx skills add erdemhalil/atlassian-client. Copyright stays with the author.

AGENTS.md

Guidance for coding agents working in this repository.

1) Project Snapshot

• Language: Python 3.10+
• Package: atlassian-client
• Core libs: httpx, pydantic v2
• Products currently implemented: Bitbucket, Confluence, Jira
• Tooling: uv, pytest, ruff, ty, unasyncd

Always run tools through uv.

2) Ground Rules

• Prefer surgical changes; avoid unrelated refactors.
• Treat generated files as generated. Fix root causes in generators/scripts when possible.
• Keep atlassian/core/ product-agnostic and reusable.
• Preserve backward compatibility unless explicitly asked to break APIs.

3) Source of Truth

Generated artifacts

• Specs: specs/<product>/openapi.json
• Models: atlassian/<product>/models.py (from scripts/sync.py)
• Endpoints/resources: generated by scripts/generate_resources.py

Hand-maintained artifacts

• Core transport/auth/error abstractions in atlassian/core/
• Product client facades (notably grouped aliases in Confluence client)
• Post-processing sync fixups in scripts/fix_sync_imports.py

4) Common Workflows

A) Refresh OpenAPI + models

• uv run python scripts/sync.py bitbucket
• uv run python scripts/sync.py confluence
• uv run python scripts/sync.py jira

B) Regenerate endpoints/resources

• uv run python scripts/generate_resources.py bitbucket
• uv run python scripts/generate_resources.py confluence
• uv run python scripts/generate_resources.py jira

C) Regenerate sync (non-async) files

• uv run unasyncd
• uv run python scripts/fix_sync_imports.py

D) Verify

• uv run python -m pytest tests/ -q
• uv run ruff format
• uv run ruff check
• uv run ty check

E) Format-only pass

• uv run ruff format

Run this after large code generation changes or before final verification.

5) Architecture Notes

Core

• atlassian/core/async_client.py → generated sync counterpart core/client.py
• atlassian/core/resource.py holds generic async/sync resource base classes
• atlassian/core/pagination.py holds generic iterators/page model for Bitbucket-like pagination

Pagination behavior

• Bitbucket: values/isLastPage/nextPageStart
• Confluence: results/_links.next
• Jira: offset-style startAt/maxResults/total and non-offset link-style nextPage/next with isLastPage
• Confluence cursor endpoints (e.g., scan-style) are intentionally treated differently than offset paging.

6) Generator Expectations

scripts/generate_resources.py is multi-product and line-length aware.

• Uses ProductConfig per product.
• Must only import models/endpoints for emitted resources.
• Should keep short signatures/calls one-line and wrap only when needed.
• Respect current Ruff line length from pyproject.toml.

If generated output looks wrong, fix generator logic first, then regenerate.

7) Sync Pipeline Caveats

unasyncd does not handle every import/module-path rewrite perfectly.

• Always run scripts/fix_sync_imports.py after unasyncd.
• Keep tool.unasyncd.add_replacements in pyproject.toml up to date for renamed Async→Sync symbols.
• scripts/fix_sync_imports.py already runs Ruff check+format on sync targets; still run a repo-level formatter/check pass afterward when multiple files changed.

8) Testing Guidance

• Prefer uv run python -m pytest ... for stable import resolution.
• Add regression tests when fixing generator or pagination bugs.
• For pagination fixes, verify both:
  • multi-page continuation
  • stop condition when no next page
  • for Jira non-offset shapes, continuation by following server nextPage/next query params

9) Known Pitfalls

• Paged non-GET endpoints (notably in Confluence) must preserve HTTP verb and request body.
• Jira nextPage may be absolute (often includes /rest/...); normalize against client base path to avoid /rest/rest/... requests.
• Do not route product-specific behavior into core unless truly generic.
• Avoid stale unasyncd mappings pointing to non-existent files.

10) Suggested Agent Routine

1. Read relevant source + generator/script before editing generated files.
2. Implement minimal root fix.
3. Regenerate affected artifacts.
4. Run sync pipeline if async sources changed.
5. Run formatter (ruff format) and lint (ruff check).
6. Run tests + type checks.
7. Summarize changed files and behavior impact clearly.