From e92c22970915eb706a41462b5fd16352a5079100 Mon Sep 17 00:00:00 2001
From: Jonathan Gangi <jgangi@redhat.com>
Date: Fri, 8 May 2026 14:48:32 -0300
Subject: [PATCH] Add CLAUDE.md and AGENTS.md for AI code assistants

CLAUDE.md provides guidance to Claude Code and other AI assistants
when working in this repository. It documents development commands
(tox environments, pytest usage), code standards (black, isort,
flake8 settings), the BaseService[T] architecture pattern, data
model serialization via attrs/AttrsJSONDecodeMixin, and the
testing/dependency management workflow.

AGENTS.md is a symlink to CLAUDE.md for tools that use that
filename convention.

Refers to SPSTRAT-736

Signed-off-by: Jonathan Gangi <jgangi@redhat.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 AGENTS.md |  1 +
 CLAUDE.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 120000 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 120000
index 0000000..681311e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..14af8c7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CloudPub is a Python library (no CLI) for publishing VM images to cloud marketplace product listings. Supports AWS Marketplace Catalog and Microsoft Azure. Part of [release-engineering](https://github.com/release-engineering) tooling, complementing Stratosphere Tooling with minimal dependencies for Pub integration.
+
+## Development Commands
+
+```bash
+# Run tests (pick your Python version)
+tox -e py313
+
+# Run a single test file or test
+pytest -vv tests/aws/test_service.py
+pytest -vv tests/aws/test_service.py::TestClassName::test_method
+
+# Lint (flake8 + black + isort)
+tox -e lint
+
+# Auto-format
+tox -e autoformat
+
+# Type check
+tox -e mypy
+
+# Security scan (bandit + safety)
+tox -e security
+
+# Build docs
+tox -e docs
+
+# Repin dependencies
+tox -e pip-compile
+```
+
+## Code Standards
+
+- **Line length**: 100 characters
+- **Formatter**: `black -S -t py310 -l 100` (note `-S` preserves single quotes)
+- **Import sorting**: `isort -l 100 --profile black`
+- **Docstrings**: required on public classes/functions (flake8-docstrings); D100/D104/D105 ignored globally, D101/D102/D103 ignored in tests
+- **Type checking**: mypy with `--warn-unused-ignores --ignore-missing-imports`
+- **Python**: 3.10 through 3.13
+
+## Architecture
+
+### Service Pattern
+
+`BaseService[T]` (`cloudpub/common.py`) is a generic abstract class parameterized on a metadata type extending `PublishingMetadata`. Each cloud provider implements `publish(metadata: T)`:
+
+- **`AWSProductService`** (`cloudpub/aws/service.py`) — uses boto3 for AWS Marketplace Catalog API. Manages product versions, delivery options, and changesets. Polls changesets via tenacity retry (default: 288 attempts x 10min = 48h).
+- **`AzureService`** (`cloudpub/ms_azure/service.py`) — uses the Product Ingestion API via `PartnerPortalSession` (`cloudpub/ms_azure/session.py`), a custom `requests.Session` with HTTPS retry and SAS URI handling. Uses `deepdiff` for minimal change detection. Supports draft/preview/live staging.
+
+### Data Models
+
+All models live in `cloudpub/models/` and use `attrs` classes with `AttrsJSONDecodeMixin` (`cloudpub/models/common.py`). This mixin provides `from_json()`/`to_json()` with field alias support (e.g., `"VersionTitle"` ↔ `version_title`), nested object conversion, and optional field hiding.
+
+- `cloudpub/models/aws.py` — AWS response/request models
+- `cloudpub/models/ms_azure.py` — Azure resource models with a `RESOURCE_MAPING` dict for type dispatch
+
+### Azure Schemas
+
+`schemas/azure/` contains JSON schema files for Azure resource validation, updated via `tox -e azure_schemas`.
+
+## Testing
+
+Tests mirror the source structure under `tests/`. Each provider subdir has a `conftest.py` with shared fixtures. HTTP interactions are mocked with `httmock` (AWS) and `requests-mock` (Azure).
+
+## Dependencies
+
+Unpinned deps in `setup.py`, pinned with hashes in `requirements.txt` and `requirements-test.txt` via pip-tools. Install with `pip install --no-deps --require-hashes -r requirements.txt`.