specx 0.0.0a1__tar.gz

specx-0.0.0a1/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Maksim Zayats
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

specx-0.0.0a1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: specx
+Version: 0.0.0a1
+Summary: Rule-based architecture guardrails for Specx Python services.
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.13.0
+Requires-Dist: pydantic-settings>=2.14.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Specx
+
+**Codex skills for building Python services with explicit architectural boundaries.**
+
+Specx is a skill catalog for generating and evolving backend services that keep
+application code readable under agent-driven development. It gives Codex a
+shared vocabulary for packaged foundation bases, scoped core packages, delivery
+adapters, unit-of-work lifecycles, dependency injection, migrations, and
+architecture tests.
+
+[Install](#install) ·
+[Skills](#skills) ·
+[Generated Architecture](#generated-architecture) ·
+[Contribute](CONTRIBUTING.md)
+
+## Key Features
+
+- **Skill-based service scaffolding.** Specx replaces a one-off code template
+  with composable skills for project structure, foundation usage, tooling,
+  DI, use cases, services, delivery controllers, infrastructure adapters,
+  settings, migrations, and tests.
+- **Explicit class boundaries.** Generated services use class-based use cases,
+  services, controllers, repositories, gateways, capabilities, DTOs, entities,
+  units of work, and factories with packaged `specx.foundation` bases.
+- **Clear transaction ownership.** Use cases open `UnitOfWorkManager` scopes.
+  Read/effect services may use an active UoW passed by the use case, but they do
+  not own transaction lifecycle.
+- **Guardrails for agent work.** The `specx` Python package ships rule-based
+  architecture tests that reject layer leaks, entity returns from use cases,
+  schema bootstrap calls, bare classes, wrong suffixes, and hidden transaction
+  ownership.
+- **Reusable runtime bases.** Generated services import small base classes from
+  `specx.foundation` instead of vendoring a foundation tree. Projects add
+  local `foundation/` modules only when a real missing category needs one.
+- **Alembic-first persistence.** SQLAlchemy projects use real Alembic
+  migrations and drift checks instead of `metadata.create_all()` bootstraps.
+
+## Install
+
+Install every Specx skill for Codex:
+
+```sh
+npx skills add maksimzayats/specx --skill '*' --agent codex -y
+```
+
+List skills from a local checkout:
+
+```sh
+npx skills add . --list --full-depth
+```
+
+Validate the catalog:
+
+```sh
+make check
+```
+
+Use the architecture package from generated projects:
+
+```python
+from pathlib import Path
+
+from specx.testing.architecture import SpecxArchitectureConfig, assert_specx_architecture
+
+
+def test_specx_architecture() -> None:
+    assert_specx_architecture(
+        SpecxArchitectureConfig(
+            project_root=Path(__file__).resolve().parents[3],
+            package_name="order_service",
+        )
+    )
+```
+
+## What You Get
+
+- A reusable Codex skill catalog under `skills/`.
+- A typed Python guardrail package under `src/specx/`.
+- A generated reference service under `samples/task-db-service/`.
+- Rule-based architecture guardrails exposed through
+  `specx.testing.architecture`.
+- A compatibility renderer that writes the tiny generated-project pytest
+  wrapper with the correct package name.
+- Root `AGENTS.md` guidance for agents working on this catalog.
+- Generated-project `AGENTS.md` guidance that projects should carry with them.
+
+## Skills
+
+- `specx-project-structure` creates the initial `core`, `delivery`,
+  `infrastructure`, `ioc`, optional local `foundation`, optional `shared`,
+  migrations, tests, and generated-project agent instructions.
+- `specx-foundation` teaches packaged base usage and project-local extensions
+  for real missing base categories.
+- `specx-project-tooling` adds `uv`, Ruff, mypy, pytest, Makefile targets, and
+  local validation commands.
+- `specx-component-architecture` decides where code belongs across scopes,
+  boundaries, capabilities, gateways, DTOs, schemas, adapters, and shared code.
+- `specx-diwire-composition` wires `diwire.Container`, `Injected[...]`, private
+  registrations, app factories, and test overrides.
+- `specx-add-core-use-case` adds command/query-driven use cases that return
+  DTOs and own UoW scopes when persistence is needed.
+- `specx-add-core-service` adds focused reusable core behavior without hiding
+  transaction lifecycle.
+- `specx-add-infrastructure-adapter` adds repositories, gateways, UoW
+  implementations, SQLAlchemy, Redis, HTTP, SDK, and other technical adapters.
+- `specx-sqlalchemy-migrations` adds async Alembic configuration, revisions,
+  migration commands, and drift tests.
+- `specx-add-delivery-controller` adds top-level FastAPI controllers, schemas,
+  route registration, and delivery-only helpers.
+- `specx-settings` adds `pydantic-settings` configuration without direct
+  environment reads in core code.
+- `specx-tests` adds unit, integration, end-to-end, DI, migration, and
+  architecture tests backed by the `specx` package.
+
+## Generated Architecture
+
+Specx projects import foundation bases from `specx.foundation` and organize
+application code around scoped core packages:
+
+```text
+src/<package>/
+  core/
+    <scope>/
+      capabilities/
+      dtos/
+      entities/
+      exceptions/
+      gateways/
+      repositories/
+      services/
+      use_cases/
+      infrastructure/
+  delivery/
+    fastapi/
+      __main__.py
+      factory.py
+      controllers/
+      schemas/
+      services/
+  infrastructure/
+  ioc/
+  shared/
+migrations/
+```
+
+`core/<scope>/delivery/` is intentionally not part of the structure. Delivery
+lives at the top level, while core packages stay framework-free.
+
+Create `src/<package>/foundation/` only when a real class category is missing
+from `specx.foundation`. Local foundation module filenames are not
+`base_`-prefixed, but class names stay prefixed, for example `clock.py` defines
+`BaseClock`.
+
+## Core Rules
+
+- Every project class inherits an explicit packaged or project-local foundation
+  base.
+- Use cases accept exactly one same-file `Command` or `Query` and return DTOs,
+  not entities.
+- Commands represent state-changing operations. Queries are read-only, even
+  when the input is empty.
+- Commands, queries, DTOs, entities, and other core data classes should use
+  `@dataclass(frozen=True, kw_only=True, slots=True)` unless the user asks for
+  another model type. Keep Pydantic for delivery schemas and settings.
+- Core services inherit `BasePureService`, `BaseReadService`, or
+  `BaseEffectService`; do not add a generic `BaseService`.
+- Small injectable collaborators inherit `BaseCapability`, live under
+  `core/<scope>/capabilities/`, and do not pretend to be services,
+  repositories, gateways, helpers, or managers.
+- Gateway ports inherit `BaseGateway`, live under `core/<scope>/gateways/`,
+  declare external effects, use business language, and do not return entities.
+- Persistence use cases inject a `UnitOfWorkManager` and open an active
+  `UnitOfWork` inside `execute(...)`.
+- Services may receive an active UoW as a method argument, but they do not open
+  UoW scopes, commit, or roll back.
+- SQLAlchemy schema is managed by Alembic migrations, not application schema
+  bootstrap calls.
+- `diwire.Container` belongs in `ioc`, top-level delivery factory/entrypoint
+  code, and tests only.
+
+## Reference Service
+
+The sample service under `samples/task-db-service/` is a working generated
+project used to validate the skills. It includes:
+
+- FastAPI delivery with `task_db_service.delivery.fastapi.__main__:app`.
+- Task use cases with command/query inputs and DTO outputs.
+- Split pure/read/effect services.
+- SQLAlchemy repositories and UoW manager.
+- Alembic migrations and drift checks.
+- Architecture tests that call the rule-based `specx` guardrail package.
+
+Run it from the sample directory:
+
+```sh
+cd samples/task-db-service
+make check
+```
+
+## Contributing
+
+Developer setup, architecture notes, sample regeneration expectations, and
+validation workflow live in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Specx is released under the [MIT License](LICENSE.md).

specx-0.0.0a1/README.md

@@ -0,0 +1,207 @@
+# Specx
+
+**Codex skills for building Python services with explicit architectural boundaries.**
+
+Specx is a skill catalog for generating and evolving backend services that keep
+application code readable under agent-driven development. It gives Codex a
+shared vocabulary for packaged foundation bases, scoped core packages, delivery
+adapters, unit-of-work lifecycles, dependency injection, migrations, and
+architecture tests.
+
+[Install](#install) ·
+[Skills](#skills) ·
+[Generated Architecture](#generated-architecture) ·
+[Contribute](CONTRIBUTING.md)
+
+## Key Features
+
+- **Skill-based service scaffolding.** Specx replaces a one-off code template
+  with composable skills for project structure, foundation usage, tooling,
+  DI, use cases, services, delivery controllers, infrastructure adapters,
+  settings, migrations, and tests.
+- **Explicit class boundaries.** Generated services use class-based use cases,
+  services, controllers, repositories, gateways, capabilities, DTOs, entities,
+  units of work, and factories with packaged `specx.foundation` bases.
+- **Clear transaction ownership.** Use cases open `UnitOfWorkManager` scopes.
+  Read/effect services may use an active UoW passed by the use case, but they do
+  not own transaction lifecycle.
+- **Guardrails for agent work.** The `specx` Python package ships rule-based
+  architecture tests that reject layer leaks, entity returns from use cases,
+  schema bootstrap calls, bare classes, wrong suffixes, and hidden transaction
+  ownership.
+- **Reusable runtime bases.** Generated services import small base classes from
+  `specx.foundation` instead of vendoring a foundation tree. Projects add
+  local `foundation/` modules only when a real missing category needs one.
+- **Alembic-first persistence.** SQLAlchemy projects use real Alembic
+  migrations and drift checks instead of `metadata.create_all()` bootstraps.
+
+## Install
+
+Install every Specx skill for Codex:
+
+```sh
+npx skills add maksimzayats/specx --skill '*' --agent codex -y
+```
+
+List skills from a local checkout:
+
+```sh
+npx skills add . --list --full-depth
+```
+
+Validate the catalog:
+
+```sh
+make check
+```
+
+Use the architecture package from generated projects:
+
+```python
+from pathlib import Path
+
+from specx.testing.architecture import SpecxArchitectureConfig, assert_specx_architecture
+
+
+def test_specx_architecture() -> None:
+    assert_specx_architecture(
+        SpecxArchitectureConfig(
+            project_root=Path(__file__).resolve().parents[3],
+            package_name="order_service",
+        )
+    )
+```
+
+## What You Get
+
+- A reusable Codex skill catalog under `skills/`.
+- A typed Python guardrail package under `src/specx/`.
+- A generated reference service under `samples/task-db-service/`.
+- Rule-based architecture guardrails exposed through
+  `specx.testing.architecture`.
+- A compatibility renderer that writes the tiny generated-project pytest
+  wrapper with the correct package name.
+- Root `AGENTS.md` guidance for agents working on this catalog.
+- Generated-project `AGENTS.md` guidance that projects should carry with them.
+
+## Skills
+
+- `specx-project-structure` creates the initial `core`, `delivery`,
+  `infrastructure`, `ioc`, optional local `foundation`, optional `shared`,
+  migrations, tests, and generated-project agent instructions.
+- `specx-foundation` teaches packaged base usage and project-local extensions
+  for real missing base categories.
+- `specx-project-tooling` adds `uv`, Ruff, mypy, pytest, Makefile targets, and
+  local validation commands.
+- `specx-component-architecture` decides where code belongs across scopes,
+  boundaries, capabilities, gateways, DTOs, schemas, adapters, and shared code.
+- `specx-diwire-composition` wires `diwire.Container`, `Injected[...]`, private
+  registrations, app factories, and test overrides.
+- `specx-add-core-use-case` adds command/query-driven use cases that return
+  DTOs and own UoW scopes when persistence is needed.
+- `specx-add-core-service` adds focused reusable core behavior without hiding
+  transaction lifecycle.
+- `specx-add-infrastructure-adapter` adds repositories, gateways, UoW
+  implementations, SQLAlchemy, Redis, HTTP, SDK, and other technical adapters.
+- `specx-sqlalchemy-migrations` adds async Alembic configuration, revisions,
+  migration commands, and drift tests.
+- `specx-add-delivery-controller` adds top-level FastAPI controllers, schemas,
+  route registration, and delivery-only helpers.
+- `specx-settings` adds `pydantic-settings` configuration without direct
+  environment reads in core code.
+- `specx-tests` adds unit, integration, end-to-end, DI, migration, and
+  architecture tests backed by the `specx` package.
+
+## Generated Architecture
+
+Specx projects import foundation bases from `specx.foundation` and organize
+application code around scoped core packages:
+
+```text
+src/<package>/
+  core/
+    <scope>/
+      capabilities/
+      dtos/
+      entities/
+      exceptions/
+      gateways/
+      repositories/
+      services/
+      use_cases/
+      infrastructure/
+  delivery/
+    fastapi/
+      __main__.py
+      factory.py
+      controllers/
+      schemas/
+      services/
+  infrastructure/
+  ioc/
+  shared/
+migrations/
+```
+
+`core/<scope>/delivery/` is intentionally not part of the structure. Delivery
+lives at the top level, while core packages stay framework-free.
+
+Create `src/<package>/foundation/` only when a real class category is missing
+from `specx.foundation`. Local foundation module filenames are not
+`base_`-prefixed, but class names stay prefixed, for example `clock.py` defines
+`BaseClock`.
+
+## Core Rules
+
+- Every project class inherits an explicit packaged or project-local foundation
+  base.
+- Use cases accept exactly one same-file `Command` or `Query` and return DTOs,
+  not entities.
+- Commands represent state-changing operations. Queries are read-only, even
+  when the input is empty.
+- Commands, queries, DTOs, entities, and other core data classes should use
+  `@dataclass(frozen=True, kw_only=True, slots=True)` unless the user asks for
+  another model type. Keep Pydantic for delivery schemas and settings.
+- Core services inherit `BasePureService`, `BaseReadService`, or
+  `BaseEffectService`; do not add a generic `BaseService`.
+- Small injectable collaborators inherit `BaseCapability`, live under
+  `core/<scope>/capabilities/`, and do not pretend to be services,
+  repositories, gateways, helpers, or managers.
+- Gateway ports inherit `BaseGateway`, live under `core/<scope>/gateways/`,
+  declare external effects, use business language, and do not return entities.
+- Persistence use cases inject a `UnitOfWorkManager` and open an active
+  `UnitOfWork` inside `execute(...)`.
+- Services may receive an active UoW as a method argument, but they do not open
+  UoW scopes, commit, or roll back.
+- SQLAlchemy schema is managed by Alembic migrations, not application schema
+  bootstrap calls.
+- `diwire.Container` belongs in `ioc`, top-level delivery factory/entrypoint
+  code, and tests only.
+
+## Reference Service
+
+The sample service under `samples/task-db-service/` is a working generated
+project used to validate the skills. It includes:
+
+- FastAPI delivery with `task_db_service.delivery.fastapi.__main__:app`.
+- Task use cases with command/query inputs and DTO outputs.
+- Split pure/read/effect services.
+- SQLAlchemy repositories and UoW manager.
+- Alembic migrations and drift checks.
+- Architecture tests that call the rule-based `specx` guardrail package.
+
+Run it from the sample directory:
+
+```sh
+cd samples/task-db-service
+make check
+```
+
+## Contributing
+
+Developer setup, architecture notes, sample regeneration expectations, and
+validation workflow live in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Specx is released under the [MIT License](LICENSE.md).

specx-0.0.0a1/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "specx"
+version = "0.0.0a1"
+description = "Rule-based architecture guardrails for Specx Python services."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE.md"]
+dependencies = [
+    "pydantic>=2.13.0",
+    "pydantic-settings>=2.14.0",
+    "sqlalchemy>=2.0.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.1.0",
+    "pyright>=1.1.407",
+    "pyyaml>=6.0.3",
+    "ruff>=0.15.0",
+    "types-PyYAML>=6.0.12",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "specx"
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+addopts = "-vv --strict-config --strict-markers --import-mode=importlib"
+pythonpath = ["src"]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests", "scripts"]
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "B",
+    "C4",
+    "E",
+    "F",
+    "I",
+    "N",
+    "PIE",
+    "PT",
+    "PTH",
+    "RET",
+    "RUF",
+    "SIM",
+    "UP",
+]
+ignore = []
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+extra_checks = true
+mypy_path = "src"
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.11"
+include = ["src", "tests"]

specx-0.0.0a1/src/specx/__init__.py

@@ -0,0 +1 @@
+

specx-0.0.0a1/src/specx/_internal/__init__.py

@@ -0,0 +1 @@
+

specx-0.0.0a1/src/specx/_internal/exceptions.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+
+class BaseSpecxError(Exception):
+    """Base for package errors raised by Specx internals and testing APIs."""

specx-0.0.0a1/src/specx/_internal/python_ast/__init__.py

@@ -0,0 +1 @@
+

specx-0.0.0a1/src/specx/_internal/python_ast/scanner.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from fnmatch import fnmatch
+from pathlib import Path
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PythonSourceFile:
+    """Parsed Python file and its lightweight static metadata."""
+
+    path: Path
+    tree: ast.Module
+    imports: frozenset[str]
+    aliases: dict[str, str]
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PythonAstProject:
+    """Static Python source index for a project under inspection."""
+
+    files: dict[Path, PythonSourceFile]
+
+    def source_file(self, path: Path) -> PythonSourceFile:
+        return self.files[path]
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class PythonAstScanner:
+    """Parse project Python files once so rules can share AST metadata."""
+
+    project_root: Path
+    excluded_patterns: tuple[str, ...] = ()
+
+    def scan(self, roots: tuple[Path, ...]) -> PythonAstProject:
+        files: dict[Path, PythonSourceFile] = {}
+        for root in roots:
+            if not root.exists():
+                continue
+            for path in sorted(root.rglob("*.py")):
+                if self._is_excluded(path):
+                    continue
+                text = path.read_text(encoding="utf-8")
+                tree = ast.parse(text, filename=str(path))
+                files[path] = PythonSourceFile(
+                    path=path,
+                    tree=tree,
+                    imports=_imports(tree),
+                    aliases=_import_aliases(tree),
+                )
+        return PythonAstProject(files=files)
+
+    def _is_excluded(self, path: Path) -> bool:
+        relative = path.relative_to(self.project_root).as_posix()
+        return any(fnmatch(relative, pattern) for pattern in self.excluded_patterns)
+
+
+def _imports(tree: ast.Module) -> frozenset[str]:
+    modules: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            modules.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom):
+            module_name = "." * node.level + (node.module or "")
+            if module_name:
+                modules.add(module_name)
+            separator = "" if module_name == "" or module_name.endswith(".") else "."
+            modules.update(
+                f"{module_name}{separator}{alias.name}" for alias in node.names if alias.name != "*"
+            )
+    return frozenset(modules)
+
+
+def _import_aliases(tree: ast.Module) -> dict[str, str]:
+    aliases: dict[str, str] = {}
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                aliases[alias.asname or alias.name.split(".")[0]] = alias.name.split(".")[-1]
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                aliases[alias.asname or alias.name] = alias.name
+    return aliases

specx-0.0.0a1/src/specx/foundation/__init__.py

@@ -0,0 +1 @@
+

specx-0.0.0a1/src/specx/foundation/capability.py

@@ -0,0 +1,9 @@
+class BaseCapability:
+    """Base for small injectable collaborators narrower than services.
+
+    Capabilities do one focused thing, may be injected or faked, and do not own
+    application workflows, unit-of-work scopes, repositories, or gateways.
+
+    Example:
+        SlugGeneratingCapability creates slugs for display labels.
+    """

specx-0.0.0a1/src/specx/foundation/command.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+
+from specx.foundation.dto import BaseDTO
+
+
+@dataclass(frozen=True, kw_only=True, slots=True)
+class BaseCommand(BaseDTO):
+    """Base for use-case inputs that request state-changing work.
+
+    Example:
+        from dataclasses import dataclass
+
+        @dataclass(frozen=True, kw_only=True, slots=True)
+        class CreateTaskCommand(BaseCommand):
+            title: str
+    """

specx-0.0.0a1/src/specx/foundation/configurator.py

@@ -0,0 +1,8 @@
+class BaseConfigurator:
+    """Base for bootstrap objects that apply configuration to runtime systems.
+
+    Example:
+        class LoggingConfigurator(BaseConfigurator):
+            def configure(self) -> None:
+                return None
+    """

specx-0.0.0a1/src/specx/foundation/delivery/__init__.py

@@ -0,0 +1 @@
+