feat: Define initial package structure and implementation

[aseguragonzalez]

This pull request introduces comprehensive project scaffolding and automation for the repository, establishing conventions, CI/CD pipelines, and contributor guidance. It adds configuration for development containers, pre-commit hooks, code linting, type-checking, release automation, and detailed documentation for contributors and maintainers.

The most important changes are:

CI/CD Automation:

• Adds GitHub Actions workflows for CI (.github/workflows/ci.yml), release (.github/workflows/release.yml), and pre-release (.github/workflows/pre-release.yml), automating linting, type-checking, testing, building, versioning, and publishing to PyPI and GitHub Packages. [1] [2] [3]

Development Environment and Tooling:

• Introduces a devcontainer configuration (.devcontainer/devcontainer.json) for consistent local development with Python 3.13, uv, and VSCode extensions.
• Adds pre-commit hook configuration (.pre-commit-config.yaml) for linting (ruff), type-checking (pyright), markdown linting, and commit message enforcement.
• Adds markdown linting configuration (.markdownlint.yaml) for documentation consistency.

Contributor Experience:

• Provides extensive contributor documentation (CONTRIBUTING.md, CLAUDE.md) covering local setup, commit conventions, testing, and project architecture. [1] [2]
• Adds a code of conduct (CODE_OF_CONDUCT.md) and a changelog placeholder (CHANGELOG.md). [1] [2]

Issue and Pull Request Templates:

• Adds issue templates for bugs, features, and questions (.github/ISSUE_TEMPLATE/bug_report.yml, feature_request.yml, question.yml) and configures issue triage (config.yml). [1] [2] [3] [4]
• Introduces a pull request template (.github/PULL_REQUEST_TEMPLATE.md) to standardize PR submissions.

[Copilot]

Pull request overview

This PR bootstraps the python-seedwork library by introducing the initial DDD/CQRS building blocks (domain/application/infrastructure layers), a reference examples/ bounded context, a test suite, and repository automation (CI, release workflows, tooling, and contributor documentation).

Changes:

• Add core seedwork primitives (entities, aggregates, value objects, domain events/errors, repository/UoW protocols) plus basic CQRS buses/builders and repository decorators.
• Add a complete bank-account example and a corresponding test suite covering domain, application, and infrastructure primitives.
• Add project automation and contributor experience scaffolding (CI/typecheck/lint/test, release/pre-release workflows, pre-commit, devcontainer, docs/templates).

Reviewed changes

Copilot reviewed 70 out of 78 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/infrastructure/test_transactional_command_bus.py	Tests transactional wrapping behavior for command dispatch.
tests/infrastructure/test_registry_query_bus.py	Tests handler registry and error behavior for query bus.
tests/infrastructure/test_registry_command_bus.py	Tests handler registry plus DomainError-to-Result mapping for command bus.
tests/infrastructure/test_query_bus_builder.py	Tests query bus builder composition and middleware order.
tests/infrastructure/test_in_memory_repository.py	Tests CRUD semantics of the in-memory repository implementation.
tests/infrastructure/test_domain_event_publishing_repository.py	Tests repository decorator that publishes domain events on save.
tests/infrastructure/test_command_bus_builder.py	Tests command bus builder composition (transaction + middleware).
tests/domain/test_value_object.py	Validates value-object equality/immutability and example Money invariants.
tests/domain/test_entity.py	Validates identity-based entity equality/hash and null-id guard.
tests/domain/test_domain_event.py	Validates DomainEventRecord defaults (id/occurred_at) and immutability.
tests/domain/test_domain_error.py	Validates DomainError behavior and example error contracts.
tests/domain/test_aggregate_root.py	Validates aggregate immutability, event recording, and example behaviors.
tests/application/test_result.py	Validates Result/ResultError success/failure and immutability semantics.
tests/application/test_get_balance_handler.py	Tests a typed query handler pattern via the example read repository.
src/seedwork/py.typed	Marks the package as PEP 561 typed for type checkers.
src/seedwork/infrastructure/transactional_command_bus.py	Adds transactional decorator command bus (UoW context wrapping).
src/seedwork/infrastructure/registry_query_bus.py	Adds in-process query bus registry (query type → handler).
src/seedwork/infrastructure/registry_command_bus.py	Adds in-process command bus registry with DomainError→Result conversion.
src/seedwork/infrastructure/query_bus_builder.py	Adds query bus builder for composing middleware/decorators.
src/seedwork/infrastructure/in_memory_repository.py	Adds generic dict-backed async repository for tests/prototyping.
src/seedwork/infrastructure/domain_event_publishing_repository.py	Adds repository decorator publishing aggregate domain events after save.
src/seedwork/infrastructure/command_bus_builder.py	Adds command bus builder including transactional wrapping and middleware.
src/seedwork/infrastructure/init.py	Re-exports infrastructure components for stable public imports.
src/seedwork/domain/value_object.py	Adds base ValueObject marker as frozen dataclass.
src/seedwork/domain/unit_of_work.py	Defines UnitOfWork protocol as async context manager.
src/seedwork/domain/repository.py	Defines async Repository protocol for aggregates.
src/seedwork/domain/entity.py	Adds base Entity with identity equality/hash and evolve helper.
src/seedwork/domain/domain_event.py	Adds DomainEvent protocol and DomainEventRecord with defaults.
src/seedwork/domain/domain_error.py	Adds base DomainError with machine-readable code.
src/seedwork/domain/aggregate_root.py	Adds AggregateRoot with immutable domain_events and record helper.
src/seedwork/domain/init.py	Re-exports domain components.
src/seedwork/application/queries.py	Adds Query/QueryHandler/QueryBus contracts.
src/seedwork/application/domain_events.py	Adds DomainEventPublisher/DomainEventHandler contracts.
src/seedwork/application/commands.py	Adds Command/CommandHandler/CommandBus contracts plus Result types.
src/seedwork/application/init.py	Re-exports application components.
src/seedwork/init.py	Re-exports domain/application/infrastructure from package root.
README.md	Adds comprehensive package documentation, rationale, and usage examples.
python-seedwork/.gitignore	Adds an additional nested .gitignore (see review comment).
pyproject.toml	Adds project metadata, tooling config (ruff/pyright/pytest/coverage), and semantic-release config.
Makefile	Adds uv-based developer commands (lint/format/typecheck/test/check/etc.).
examples/bank_account/domain/money.py	Adds Money value object + related domain errors in the example context.
examples/bank_account/domain/events/account_opened.py	Adds AccountOpened domain event in the example context.
examples/bank_account/domain/events/account_debited.py	Adds AccountDebited domain event in the example context.
examples/bank_account/domain/events/account_credited.py	Adds AccountCredited domain event in the example context.
examples/bank_account/domain/events/init.py	Initializes example events package.
examples/bank_account/domain/errors.py	Adds example domain errors (insufficient funds, currency mismatch, not found).
examples/bank_account/domain/bank_account.py	Adds example aggregate root with immutable behavior + event recording.
examples/bank_account/domain/bank_account_repository.py	Adds typed repository port for the example aggregate.
examples/bank_account/domain/bank_account_id.py	Adds example NewType BankAccountId.
examples/bank_account/domain/init.py	Initializes example domain package.
examples/bank_account/application/get_balance/get_balance_query.py	Adds example query contract for balance read model.
examples/bank_account/application/get_balance/get_balance_handler.py	Adds example query handler using a read-repository port.
examples/bank_account/application/get_balance/bank_account_read_repository.py	Adds example read-repository Protocol for queries.
examples/bank_account/application/get_balance/balance_response.py	Adds example DTO response type.
examples/bank_account/application/get_balance/init.py	Initializes example application package.
examples/bank_account/application/init.py	Initializes example application package.
examples/bank_account/init.py	Initializes example bounded context package.
examples/init.py	Initializes examples package.
docs/README.md	Adds docs index/entrypoint.
docs/component-reference.md	Adds component reference documentation for public API.
docs/coding-standards.md	Adds coding standards aligned with the library’s intended usage.
docs/best-practices.md	Adds best practices guidance and usage patterns.
CONTRIBUTING.md	Adds contributor setup and workflow instructions.
CODE_OF_CONDUCT.md	Adds code of conduct.
CLAUDE.md	Adds repository guidance for Claude Code (commands/architecture/conventions).
CHANGELOG.md	Adds changelog placeholder.
.pre-commit-config.yaml	Adds pre-commit hooks for ruff, pyright, markdownlint, and commit message enforcement.
.markdownlint.yaml	Adds markdownlint configuration.
.github/workflows/release.yml	Adds release workflow (CI + semantic-release + build + publish).
.github/workflows/pre-release.yml	Adds manually-triggered pre-release workflow.
.github/workflows/ci.yml	Adds CI workflow (lint/format check, pyright, pytest on 3.12/3.13).
.github/PULL_REQUEST_TEMPLATE.md	Adds PR template.
.github/ISSUE_TEMPLATE/question.yml	Adds question/discussion issue template.
.github/ISSUE_TEMPLATE/feature_request.yml	Adds feature request issue template.
.github/ISSUE_TEMPLATE/config.yml	Configures issue templates and contact links (see review comment).
.github/ISSUE_TEMPLATE/bug_report.yml	Adds bug report issue template.
.devcontainer/devcontainer.json	Adds devcontainer for consistent local dev environment (see review comment).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.