hexastack 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hexastack-0.1.0/PKG-INFO +284 -0
- hexastack-0.1.0/README.md +220 -0
- hexastack-0.1.0/pyproject.toml +119 -0
- hexastack-0.1.0/pyproject.toml.orig +120 -0
- hexastack-0.1.0/src/hexastack/__init__.py +65 -0
- hexastack-0.1.0/src/hexastack/adapters/__init__.py +7 -0
- hexastack-0.1.0/src/hexastack/adapters/cli/__init__.py +40 -0
- hexastack-0.1.0/src/hexastack/adapters/cli/devtools/__init__.py +33 -0
- hexastack-0.1.0/src/hexastack/adapters/cli/devtools/commands.py +1114 -0
- hexastack-0.1.0/src/hexastack/adapters/cli/scaffolding/__init__.py +7 -0
- hexastack-0.1.0/src/hexastack/adapters/cli/scaffolding/commands.py +304 -0
- hexastack-0.1.0/src/hexastack/adapters/fastapi.py +71 -0
- hexastack-0.1.0/src/hexastack/application/__init__.py +26 -0
- hexastack-0.1.0/src/hexastack/application/diagnostics/__init__.py +13 -0
- hexastack-0.1.0/src/hexastack/application/diagnostics/handlers.py +317 -0
- hexastack-0.1.0/src/hexastack/application/scaffolding/__init__.py +13 -0
- hexastack-0.1.0/src/hexastack/application/scaffolding/generator.py +905 -0
- hexastack-0.1.0/src/hexastack/domain/__init__.py +17 -0
- hexastack-0.1.0/src/hexastack/domain/diagnostics.py +70 -0
- hexastack-0.1.0/src/hexastack/entrypoint.py +48 -0
- hexastack-0.1.0/src/hexastack/py.typed +1 -0
hexastack-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hexastack
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Hexastack - Modern Hexagonal Architecture & CQRS Framework for Python
|
|
5
|
+
Author: Richard West
|
|
6
|
+
Author-email: Richard West <dopplereffect.us@gmail.com>
|
|
7
|
+
License-Expression: Apache-2.0
|
|
8
|
+
Requires-Dist: hexastack-core
|
|
9
|
+
Requires-Dist: hexastack-cqrs
|
|
10
|
+
Requires-Dist: hexastack-logging
|
|
11
|
+
Requires-Dist: hexastack-ai ; extra == 'ai'
|
|
12
|
+
Requires-Dist: hexastack-ai ; extra == 'all'
|
|
13
|
+
Requires-Dist: hexastack-auth ; extra == 'all'
|
|
14
|
+
Requires-Dist: hexastack-cli ; extra == 'all'
|
|
15
|
+
Requires-Dist: hexastack-db ; extra == 'all'
|
|
16
|
+
Requires-Dist: hexastack-events ; extra == 'all'
|
|
17
|
+
Requires-Dist: hexastack-fastapi ; extra == 'all'
|
|
18
|
+
Requires-Dist: hexastack-flags ; extra == 'all'
|
|
19
|
+
Requires-Dist: hexastack-graphql ; extra == 'all'
|
|
20
|
+
Requires-Dist: hexastack-grpc ; extra == 'all'
|
|
21
|
+
Requires-Dist: hexastack-mcp ; extra == 'all'
|
|
22
|
+
Requires-Dist: hexastack-otel ; extra == 'all'
|
|
23
|
+
Requires-Dist: uvicorn[standard]>=0.30.0 ; extra == 'all'
|
|
24
|
+
Requires-Dist: hexastack-auth ; extra == 'auth'
|
|
25
|
+
Requires-Dist: hexastack-cli ; extra == 'cli'
|
|
26
|
+
Requires-Dist: hexastack-db ; extra == 'db'
|
|
27
|
+
Requires-Dist: hexastack-fastapi[docs] ; extra == 'docs'
|
|
28
|
+
Requires-Dist: hexastack-events ; extra == 'events'
|
|
29
|
+
Requires-Dist: hexastack-fastapi ; extra == 'fastapi'
|
|
30
|
+
Requires-Dist: hexastack-flags ; extra == 'flags'
|
|
31
|
+
Requires-Dist: hexastack-graphql ; extra == 'graphql'
|
|
32
|
+
Requires-Dist: hexastack-grpc ; extra == 'grpc'
|
|
33
|
+
Requires-Dist: hexastack-mcp ; extra == 'mcp'
|
|
34
|
+
Requires-Dist: hexastack-otel ; extra == 'otel'
|
|
35
|
+
Requires-Dist: hexastack-db ; extra == 'sql'
|
|
36
|
+
Requires-Dist: faker>=33.0.0 ; extra == 'testing'
|
|
37
|
+
Requires-Dist: hypothesis>=6.100.0 ; extra == 'testing'
|
|
38
|
+
Requires-Dist: inline-snapshot>=0.35.4 ; extra == 'testing'
|
|
39
|
+
Requires-Dist: playwright>=1.49.0 ; extra == 'testing'
|
|
40
|
+
Requires-Dist: pytest-archon>=0.0.7 ; extra == 'testing'
|
|
41
|
+
Requires-Dist: schemathesis>=3.39.0 ; extra == 'testing'
|
|
42
|
+
Requires-Dist: hexastack-fastapi[ui] ; extra == 'ui'
|
|
43
|
+
Requires-Dist: hexastack-fastapi ; extra == 'web'
|
|
44
|
+
Requires-Dist: uvicorn[standard]>=0.30.0 ; extra == 'web'
|
|
45
|
+
Requires-Python: >=3.13
|
|
46
|
+
Provides-Extra: ai
|
|
47
|
+
Provides-Extra: all
|
|
48
|
+
Provides-Extra: auth
|
|
49
|
+
Provides-Extra: cli
|
|
50
|
+
Provides-Extra: db
|
|
51
|
+
Provides-Extra: docs
|
|
52
|
+
Provides-Extra: events
|
|
53
|
+
Provides-Extra: fastapi
|
|
54
|
+
Provides-Extra: flags
|
|
55
|
+
Provides-Extra: graphql
|
|
56
|
+
Provides-Extra: grpc
|
|
57
|
+
Provides-Extra: mcp
|
|
58
|
+
Provides-Extra: otel
|
|
59
|
+
Provides-Extra: sql
|
|
60
|
+
Provides-Extra: testing
|
|
61
|
+
Provides-Extra: ui
|
|
62
|
+
Provides-Extra: web
|
|
63
|
+
Description-Content-Type: text/markdown
|
|
64
|
+
|
|
65
|
+

|
|
66
|
+
|
|
67
|
+
# hexastack
|
|
68
|
+
|
|
69
|
+
> The unified distribution package and diagnostic CLI for the Hexastack framework.
|
|
70
|
+
|
|
71
|
+
[](https://pypi.org/project/hexastack/)
|
|
72
|
+
[](https://www.python.org/downloads/)
|
|
73
|
+
[](https://codecov.io/github/TheTrueSCU/hexastack)
|
|
74
|
+
[](../../LICENSE)
|
|
75
|
+
[](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
|
|
76
|
+
[](https://github.com/dequelabs/axe-core)
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 1. Overview & Capabilities
|
|
80
|
+
|
|
81
|
+
`hexastack` acts as the umbrella distribution for the entire Hexastack monorepo, offering:
|
|
82
|
+
|
|
83
|
+
- **Scoped Extras**: Single-command installs for scoped use cases (e.g., `pip install hexastack[cli]`, `pip install hexastack[web]`, `pip install hexastack[graphql]`, `pip install hexastack[mcp]`, `pip install hexastack[grpc]`, `pip install hexastack[db]`).
|
|
84
|
+
- **Zero-Install Project Scaffolding**: `hexastack new <template> <name>` instantly scaffolds production-grade microservices adhering strictly to Hexagonal Architecture, complete with tiered CI, import-linter contracts, and passing test suites.
|
|
85
|
+
- **Interactive Diagnostic CLI**: The `hexastack` terminal command provides system health checks, package inspection, CQRS message route exploration, local FastAPI dev server launching, MCP server execution, gRPC daemon hosting, and Alembic database migration management.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## 2. Monorepo & Sibling Relationships
|
|
90
|
+
|
|
91
|
+
```mermaid
|
|
92
|
+
graph TD
|
|
93
|
+
subgraph Umbrella ["hexastack (Distribution & CLI App)"]
|
|
94
|
+
CLI_APP["hexastack CLI Entrypoint"]
|
|
95
|
+
DIAG["Diagnostics Handlers (info, inspect, ping)"]
|
|
96
|
+
DEMO_SERVER["FastAPI Demo Server (serve)"]
|
|
97
|
+
DB_CLI["Alembic Migration Tooling (db)"]
|
|
98
|
+
MCP_CLI["MCP Server Runner (mcp)"]
|
|
99
|
+
GRPC_CLI["gRPC Server Daemon (grpc)"]
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
subgraph BaseDependencies ["Default Direct Dependencies"]
|
|
103
|
+
CORE["hexastack-core"]
|
|
104
|
+
CQRS["hexastack-cqrs"]
|
|
105
|
+
LOG["hexastack-logging"]
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
subgraph ScopedExtras ["Optional Scoped Extras"]
|
|
109
|
+
AUTH["hexastack-auth (hexastack[auth])"]
|
|
110
|
+
OTEL["hexastack-otel (hexastack[otel])"]
|
|
111
|
+
EVENTS["hexastack-events (hexastack[events])"]
|
|
112
|
+
AI["hexastack-ai (hexastack[ai])"]
|
|
113
|
+
CLI["hexastack-cli (hexastack[cli])"]
|
|
114
|
+
FASTAPI["hexastack-fastapi (hexastack[fastapi])"]
|
|
115
|
+
GRAPHQL["hexastack-graphql (hexastack[graphql])"]
|
|
116
|
+
MCP["hexastack-mcp (hexastack[mcp])"]
|
|
117
|
+
GRPC["hexastack-grpc (hexastack[grpc])"]
|
|
118
|
+
DB["hexastack-db (hexastack[db])"]
|
|
119
|
+
FLAGS["hexastack-flags (hexastack[flags])"]
|
|
120
|
+
UVICORN["uvicorn[standard] (hexastack[web])"]
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
Umbrella --> CORE
|
|
124
|
+
Umbrella --> CQRS
|
|
125
|
+
Umbrella --> LOG
|
|
126
|
+
|
|
127
|
+
CLI_APP -. optional extra .-> CLI
|
|
128
|
+
DEMO_SERVER -. optional extra .-> FASTAPI
|
|
129
|
+
DEMO_SERVER -. optional extra .-> UVICORN
|
|
130
|
+
DB_CLI -. optional extra .-> DB
|
|
131
|
+
MCP_CLI -. optional extra .-> MCP
|
|
132
|
+
GRPC_CLI -. optional extra .-> GRPC
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Explicit Dependencies (Direct)
|
|
136
|
+
- `hexastack-core`: Core kernel, DI container (`rodi`), and bootstrap engine.
|
|
137
|
+
- `hexastack-cqrs`: Command, query, and event execution buses.
|
|
138
|
+
- `hexastack-logging`: Structured logging and telemetry.
|
|
139
|
+
|
|
140
|
+
### Optional Integrations (Extras)
|
|
141
|
+
- `[auth]`: Installs `hexastack-auth` for security, RBAC, JWT, PBKDF2, and `@authorize` middleware.
|
|
142
|
+
- `[otel]`: Installs `hexastack-otel` for OpenTelemetry distributed tracing and OTLP export.
|
|
143
|
+
- `[events]`: Installs `hexastack-events` for CloudEvents 1.0, Transactional Outbox, and streaming buses.
|
|
144
|
+
- `[ai]`: Installs `hexastack-ai` for LiteLLM, Instructor, PydanticAI, and reflective agent tools.
|
|
145
|
+
- `[cli]`: Installs `hexastack-cli` for interactive CLI commands.
|
|
146
|
+
- `[db]` / `[sql]`: Installs `hexastack-db` for persistence and Alembic migrations.
|
|
147
|
+
- `[fastapi]`: Installs `hexastack-fastapi`.
|
|
148
|
+
- `[flags]`: Installs `hexastack-flags` for CNCF OpenFeature enterprise feature flag providers (Flagd, Unleash, Flipt).
|
|
149
|
+
- `[graphql]`: Installs `hexastack-graphql`.
|
|
150
|
+
- `[mcp]`: Installs `hexastack-mcp` for Model Context Protocol AI agent tools.
|
|
151
|
+
- `[grpc]`: Installs `hexastack-grpc` for high-performance RPC services.
|
|
152
|
+
- `[web]`: Installs `hexastack-fastapi` and `uvicorn[standard]`.
|
|
153
|
+
- `[docs]`: Installs `zensical` for static documentation generation and hosting.
|
|
154
|
+
- `[testing]`: Installs recommended testing tools (`hypothesis`, `inline-snapshot`, `playwright`, `pytest-archon`, `schemathesis`).
|
|
155
|
+
- `[all]`: Complete installation with all adapters and development tools.
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 3. Installation
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
# Minimal installation
|
|
163
|
+
pip install hexastack
|
|
164
|
+
|
|
165
|
+
# Testing toolkit (Archon boundary checks, Hypothesis fuzzing, Schemathesis)
|
|
166
|
+
pip install "hexastack[testing]"
|
|
167
|
+
|
|
168
|
+
# CNCF OpenFeature flags
|
|
169
|
+
pip install "hexastack[flags]"
|
|
170
|
+
|
|
171
|
+
# Security & RBAC
|
|
172
|
+
pip install "hexastack[auth]"
|
|
173
|
+
|
|
174
|
+
# OpenTelemetry Tracing
|
|
175
|
+
pip install "hexastack[otel]"
|
|
176
|
+
|
|
177
|
+
# CloudEvents & Transactional Outbox
|
|
178
|
+
pip install "hexastack[events]"
|
|
179
|
+
|
|
180
|
+
# AI Integration (LiteLLM, Instructor, PydanticAI)
|
|
181
|
+
pip install "hexastack[ai]"
|
|
182
|
+
|
|
183
|
+
# CLI support
|
|
184
|
+
pip install "hexastack[cli]"
|
|
185
|
+
|
|
186
|
+
# Full web stack (FastAPI + Uvicorn)
|
|
187
|
+
pip install "hexastack[web]"
|
|
188
|
+
|
|
189
|
+
# GraphQL support
|
|
190
|
+
pip install "hexastack[graphql]"
|
|
191
|
+
|
|
192
|
+
# Model Context Protocol support
|
|
193
|
+
pip install "hexastack[mcp]"
|
|
194
|
+
|
|
195
|
+
# gRPC support
|
|
196
|
+
pip install "hexastack[grpc]"
|
|
197
|
+
|
|
198
|
+
# Database support with migrations
|
|
199
|
+
pip install "hexastack[db]"
|
|
200
|
+
|
|
201
|
+
# Complete ecosystem
|
|
202
|
+
pip install "hexastack[all]"
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## 4. Project Scaffolding & Archetypes (`hexastack new` & `hexastack init`)
|
|
208
|
+
|
|
209
|
+
Hexastack includes a production-grade scaffolding engine that creates fully functioning, decoupled microservices adhering strictly to Hexagonal Architecture, complete with pre-configured `.importlinter` boundaries, GitHub Actions CI workflows, multi-stage rootless Dockerfiles, passing test suites, and secret scanning.
|
|
210
|
+
|
|
211
|
+
### Interactive Scaffolding Wizard (`hexastack init`)
|
|
212
|
+
|
|
213
|
+
Launch an interactive terminal wizard that guides you through template selection, database drivers, auth, transports, and telemetry:
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
hexastack init
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Direct Archetype Scaffolding (`hexastack new`)
|
|
220
|
+
|
|
221
|
+
Generate microservices in a single command using one of the pre-built blueprints:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
# Web API service with FastAPI, SQLite/Postgres, and OpenAPI specs
|
|
225
|
+
hexastack new web-api order-service
|
|
226
|
+
|
|
227
|
+
# High-throughput gRPC binary RPC microservice with in-process ProtoCompiler and Buf linting
|
|
228
|
+
hexastack new grpc-service payment-gateway
|
|
229
|
+
|
|
230
|
+
# AI Agent service equipped with Model Context Protocol (MCP) server & tools
|
|
231
|
+
hexastack new mcp-agent customer-assistant
|
|
232
|
+
|
|
233
|
+
# GraphQL presentation service with Strawberry schema and CQRS bus
|
|
234
|
+
hexastack new graphql-service analytics-service
|
|
235
|
+
|
|
236
|
+
# Asynchronous event-driven microservice with CloudEvents 1.0 and Transactional Outbox
|
|
237
|
+
hexastack new event-driven billing-worker
|
|
238
|
+
|
|
239
|
+
# Enterprise grade multi-transport service (FastAPI + gRPC + GraphQL + MCP + Outbox + Auth)
|
|
240
|
+
hexastack new enterprise core-platform
|
|
241
|
+
|
|
242
|
+
# Ultra-minimal CQRS microservice
|
|
243
|
+
hexastack new minimal lightweight-worker
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### Scaffolded Service Anatomy
|
|
247
|
+
|
|
248
|
+
Every scaffolded service immediately includes:
|
|
249
|
+
1. **Strict Layer Isolation**: `domain/` (0 framework dependencies), `ports/` (abstract protocols), `adapters/driving/` (FastAPI / gRPC / CLI / MCP), `adapters/driven/` (SQLAlchemy / InMemory / Outbox), and `infra/` (bootstrappers & configuration).
|
|
250
|
+
2. **Golden-Path Multi-Stage Dockerfile**: Ultra-fast `uv`-cached builder layer, rootless non-root runtime user (`appuser:10001`), `/health` probe `HEALTHCHECK`, and `.dockerignore`.
|
|
251
|
+
3. **Automated Quality Gates**: `.importlinter` rules enforcing directional purity, pre-commit config with `detect-secrets`, `pip-audit`, and `ruff`, plus a complete `pytest` unit test suite.
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## 5. CLI Diagnostic Commands
|
|
256
|
+
|
|
257
|
+
When installed with `hexastack[all]` or `hexastack[cli]`:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
# Check installed packages and optional dependency statuses
|
|
261
|
+
hexastack info
|
|
262
|
+
|
|
263
|
+
# Inspect registered CQRS commands, queries, and configs
|
|
264
|
+
hexastack inspect registry
|
|
265
|
+
|
|
266
|
+
# Send a test ping command through the CQRS pipeline
|
|
267
|
+
hexastack ping --message "Hello Hexastack"
|
|
268
|
+
|
|
269
|
+
# Launch local FastAPI dev server with live reload (requires hexastack[web])
|
|
270
|
+
hexastack serve --host 127.0.0.1 --port 8000
|
|
271
|
+
|
|
272
|
+
# Launch MCP server in stdio mode (requires hexastack[mcp])
|
|
273
|
+
hexastack mcp run
|
|
274
|
+
|
|
275
|
+
# Launch gRPC daemon (requires hexastack[grpc])
|
|
276
|
+
hexastack grpc serve --host 0.0.0.0 --port 50051
|
|
277
|
+
|
|
278
|
+
# Manage database migrations (requires hexastack[db])
|
|
279
|
+
hexastack db init migrations/
|
|
280
|
+
hexastack db revision "add users table"
|
|
281
|
+
hexastack db upgrade head
|
|
282
|
+
hexastack db current
|
|
283
|
+
hexastack db history
|
|
284
|
+
```
|
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+

|
|
2
|
+
|
|
3
|
+
# hexastack
|
|
4
|
+
|
|
5
|
+
> The unified distribution package and diagnostic CLI for the Hexastack framework.
|
|
6
|
+
|
|
7
|
+
[](https://pypi.org/project/hexastack/)
|
|
8
|
+
[](https://www.python.org/downloads/)
|
|
9
|
+
[](https://codecov.io/github/TheTrueSCU/hexastack)
|
|
10
|
+
[](../../LICENSE)
|
|
11
|
+
[](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
|
|
12
|
+
[](https://github.com/dequelabs/axe-core)
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## 1. Overview & Capabilities
|
|
16
|
+
|
|
17
|
+
`hexastack` acts as the umbrella distribution for the entire Hexastack monorepo, offering:
|
|
18
|
+
|
|
19
|
+
- **Scoped Extras**: Single-command installs for scoped use cases (e.g., `pip install hexastack[cli]`, `pip install hexastack[web]`, `pip install hexastack[graphql]`, `pip install hexastack[mcp]`, `pip install hexastack[grpc]`, `pip install hexastack[db]`).
|
|
20
|
+
- **Zero-Install Project Scaffolding**: `hexastack new <template> <name>` instantly scaffolds production-grade microservices adhering strictly to Hexagonal Architecture, complete with tiered CI, import-linter contracts, and passing test suites.
|
|
21
|
+
- **Interactive Diagnostic CLI**: The `hexastack` terminal command provides system health checks, package inspection, CQRS message route exploration, local FastAPI dev server launching, MCP server execution, gRPC daemon hosting, and Alembic database migration management.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
## 2. Monorepo & Sibling Relationships
|
|
26
|
+
|
|
27
|
+
```mermaid
|
|
28
|
+
graph TD
|
|
29
|
+
subgraph Umbrella ["hexastack (Distribution & CLI App)"]
|
|
30
|
+
CLI_APP["hexastack CLI Entrypoint"]
|
|
31
|
+
DIAG["Diagnostics Handlers (info, inspect, ping)"]
|
|
32
|
+
DEMO_SERVER["FastAPI Demo Server (serve)"]
|
|
33
|
+
DB_CLI["Alembic Migration Tooling (db)"]
|
|
34
|
+
MCP_CLI["MCP Server Runner (mcp)"]
|
|
35
|
+
GRPC_CLI["gRPC Server Daemon (grpc)"]
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
subgraph BaseDependencies ["Default Direct Dependencies"]
|
|
39
|
+
CORE["hexastack-core"]
|
|
40
|
+
CQRS["hexastack-cqrs"]
|
|
41
|
+
LOG["hexastack-logging"]
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
subgraph ScopedExtras ["Optional Scoped Extras"]
|
|
45
|
+
AUTH["hexastack-auth (hexastack[auth])"]
|
|
46
|
+
OTEL["hexastack-otel (hexastack[otel])"]
|
|
47
|
+
EVENTS["hexastack-events (hexastack[events])"]
|
|
48
|
+
AI["hexastack-ai (hexastack[ai])"]
|
|
49
|
+
CLI["hexastack-cli (hexastack[cli])"]
|
|
50
|
+
FASTAPI["hexastack-fastapi (hexastack[fastapi])"]
|
|
51
|
+
GRAPHQL["hexastack-graphql (hexastack[graphql])"]
|
|
52
|
+
MCP["hexastack-mcp (hexastack[mcp])"]
|
|
53
|
+
GRPC["hexastack-grpc (hexastack[grpc])"]
|
|
54
|
+
DB["hexastack-db (hexastack[db])"]
|
|
55
|
+
FLAGS["hexastack-flags (hexastack[flags])"]
|
|
56
|
+
UVICORN["uvicorn[standard] (hexastack[web])"]
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
Umbrella --> CORE
|
|
60
|
+
Umbrella --> CQRS
|
|
61
|
+
Umbrella --> LOG
|
|
62
|
+
|
|
63
|
+
CLI_APP -. optional extra .-> CLI
|
|
64
|
+
DEMO_SERVER -. optional extra .-> FASTAPI
|
|
65
|
+
DEMO_SERVER -. optional extra .-> UVICORN
|
|
66
|
+
DB_CLI -. optional extra .-> DB
|
|
67
|
+
MCP_CLI -. optional extra .-> MCP
|
|
68
|
+
GRPC_CLI -. optional extra .-> GRPC
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### Explicit Dependencies (Direct)
|
|
72
|
+
- `hexastack-core`: Core kernel, DI container (`rodi`), and bootstrap engine.
|
|
73
|
+
- `hexastack-cqrs`: Command, query, and event execution buses.
|
|
74
|
+
- `hexastack-logging`: Structured logging and telemetry.
|
|
75
|
+
|
|
76
|
+
### Optional Integrations (Extras)
|
|
77
|
+
- `[auth]`: Installs `hexastack-auth` for security, RBAC, JWT, PBKDF2, and `@authorize` middleware.
|
|
78
|
+
- `[otel]`: Installs `hexastack-otel` for OpenTelemetry distributed tracing and OTLP export.
|
|
79
|
+
- `[events]`: Installs `hexastack-events` for CloudEvents 1.0, Transactional Outbox, and streaming buses.
|
|
80
|
+
- `[ai]`: Installs `hexastack-ai` for LiteLLM, Instructor, PydanticAI, and reflective agent tools.
|
|
81
|
+
- `[cli]`: Installs `hexastack-cli` for interactive CLI commands.
|
|
82
|
+
- `[db]` / `[sql]`: Installs `hexastack-db` for persistence and Alembic migrations.
|
|
83
|
+
- `[fastapi]`: Installs `hexastack-fastapi`.
|
|
84
|
+
- `[flags]`: Installs `hexastack-flags` for CNCF OpenFeature enterprise feature flag providers (Flagd, Unleash, Flipt).
|
|
85
|
+
- `[graphql]`: Installs `hexastack-graphql`.
|
|
86
|
+
- `[mcp]`: Installs `hexastack-mcp` for Model Context Protocol AI agent tools.
|
|
87
|
+
- `[grpc]`: Installs `hexastack-grpc` for high-performance RPC services.
|
|
88
|
+
- `[web]`: Installs `hexastack-fastapi` and `uvicorn[standard]`.
|
|
89
|
+
- `[docs]`: Installs `zensical` for static documentation generation and hosting.
|
|
90
|
+
- `[testing]`: Installs recommended testing tools (`hypothesis`, `inline-snapshot`, `playwright`, `pytest-archon`, `schemathesis`).
|
|
91
|
+
- `[all]`: Complete installation with all adapters and development tools.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## 3. Installation
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
# Minimal installation
|
|
99
|
+
pip install hexastack
|
|
100
|
+
|
|
101
|
+
# Testing toolkit (Archon boundary checks, Hypothesis fuzzing, Schemathesis)
|
|
102
|
+
pip install "hexastack[testing]"
|
|
103
|
+
|
|
104
|
+
# CNCF OpenFeature flags
|
|
105
|
+
pip install "hexastack[flags]"
|
|
106
|
+
|
|
107
|
+
# Security & RBAC
|
|
108
|
+
pip install "hexastack[auth]"
|
|
109
|
+
|
|
110
|
+
# OpenTelemetry Tracing
|
|
111
|
+
pip install "hexastack[otel]"
|
|
112
|
+
|
|
113
|
+
# CloudEvents & Transactional Outbox
|
|
114
|
+
pip install "hexastack[events]"
|
|
115
|
+
|
|
116
|
+
# AI Integration (LiteLLM, Instructor, PydanticAI)
|
|
117
|
+
pip install "hexastack[ai]"
|
|
118
|
+
|
|
119
|
+
# CLI support
|
|
120
|
+
pip install "hexastack[cli]"
|
|
121
|
+
|
|
122
|
+
# Full web stack (FastAPI + Uvicorn)
|
|
123
|
+
pip install "hexastack[web]"
|
|
124
|
+
|
|
125
|
+
# GraphQL support
|
|
126
|
+
pip install "hexastack[graphql]"
|
|
127
|
+
|
|
128
|
+
# Model Context Protocol support
|
|
129
|
+
pip install "hexastack[mcp]"
|
|
130
|
+
|
|
131
|
+
# gRPC support
|
|
132
|
+
pip install "hexastack[grpc]"
|
|
133
|
+
|
|
134
|
+
# Database support with migrations
|
|
135
|
+
pip install "hexastack[db]"
|
|
136
|
+
|
|
137
|
+
# Complete ecosystem
|
|
138
|
+
pip install "hexastack[all]"
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## 4. Project Scaffolding & Archetypes (`hexastack new` & `hexastack init`)
|
|
144
|
+
|
|
145
|
+
Hexastack includes a production-grade scaffolding engine that creates fully functioning, decoupled microservices adhering strictly to Hexagonal Architecture, complete with pre-configured `.importlinter` boundaries, GitHub Actions CI workflows, multi-stage rootless Dockerfiles, passing test suites, and secret scanning.
|
|
146
|
+
|
|
147
|
+
### Interactive Scaffolding Wizard (`hexastack init`)
|
|
148
|
+
|
|
149
|
+
Launch an interactive terminal wizard that guides you through template selection, database drivers, auth, transports, and telemetry:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
hexastack init
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Direct Archetype Scaffolding (`hexastack new`)
|
|
156
|
+
|
|
157
|
+
Generate microservices in a single command using one of the pre-built blueprints:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
# Web API service with FastAPI, SQLite/Postgres, and OpenAPI specs
|
|
161
|
+
hexastack new web-api order-service
|
|
162
|
+
|
|
163
|
+
# High-throughput gRPC binary RPC microservice with in-process ProtoCompiler and Buf linting
|
|
164
|
+
hexastack new grpc-service payment-gateway
|
|
165
|
+
|
|
166
|
+
# AI Agent service equipped with Model Context Protocol (MCP) server & tools
|
|
167
|
+
hexastack new mcp-agent customer-assistant
|
|
168
|
+
|
|
169
|
+
# GraphQL presentation service with Strawberry schema and CQRS bus
|
|
170
|
+
hexastack new graphql-service analytics-service
|
|
171
|
+
|
|
172
|
+
# Asynchronous event-driven microservice with CloudEvents 1.0 and Transactional Outbox
|
|
173
|
+
hexastack new event-driven billing-worker
|
|
174
|
+
|
|
175
|
+
# Enterprise grade multi-transport service (FastAPI + gRPC + GraphQL + MCP + Outbox + Auth)
|
|
176
|
+
hexastack new enterprise core-platform
|
|
177
|
+
|
|
178
|
+
# Ultra-minimal CQRS microservice
|
|
179
|
+
hexastack new minimal lightweight-worker
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Scaffolded Service Anatomy
|
|
183
|
+
|
|
184
|
+
Every scaffolded service immediately includes:
|
|
185
|
+
1. **Strict Layer Isolation**: `domain/` (0 framework dependencies), `ports/` (abstract protocols), `adapters/driving/` (FastAPI / gRPC / CLI / MCP), `adapters/driven/` (SQLAlchemy / InMemory / Outbox), and `infra/` (bootstrappers & configuration).
|
|
186
|
+
2. **Golden-Path Multi-Stage Dockerfile**: Ultra-fast `uv`-cached builder layer, rootless non-root runtime user (`appuser:10001`), `/health` probe `HEALTHCHECK`, and `.dockerignore`.
|
|
187
|
+
3. **Automated Quality Gates**: `.importlinter` rules enforcing directional purity, pre-commit config with `detect-secrets`, `pip-audit`, and `ruff`, plus a complete `pytest` unit test suite.
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## 5. CLI Diagnostic Commands
|
|
192
|
+
|
|
193
|
+
When installed with `hexastack[all]` or `hexastack[cli]`:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
# Check installed packages and optional dependency statuses
|
|
197
|
+
hexastack info
|
|
198
|
+
|
|
199
|
+
# Inspect registered CQRS commands, queries, and configs
|
|
200
|
+
hexastack inspect registry
|
|
201
|
+
|
|
202
|
+
# Send a test ping command through the CQRS pipeline
|
|
203
|
+
hexastack ping --message "Hello Hexastack"
|
|
204
|
+
|
|
205
|
+
# Launch local FastAPI dev server with live reload (requires hexastack[web])
|
|
206
|
+
hexastack serve --host 127.0.0.1 --port 8000
|
|
207
|
+
|
|
208
|
+
# Launch MCP server in stdio mode (requires hexastack[mcp])
|
|
209
|
+
hexastack mcp run
|
|
210
|
+
|
|
211
|
+
# Launch gRPC daemon (requires hexastack[grpc])
|
|
212
|
+
hexastack grpc serve --host 0.0.0.0 --port 50051
|
|
213
|
+
|
|
214
|
+
# Manage database migrations (requires hexastack[db])
|
|
215
|
+
hexastack db init migrations/
|
|
216
|
+
hexastack db revision "add users table"
|
|
217
|
+
hexastack db upgrade head
|
|
218
|
+
hexastack db current
|
|
219
|
+
hexastack db history
|
|
220
|
+
```
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "hexastack"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Hexastack - Modern Hexagonal Architecture & CQRS Framework for Python"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "Apache-2.0"
|
|
7
|
+
requires-python = ">=3.13"
|
|
8
|
+
dependencies = [
|
|
9
|
+
"hexastack-core",
|
|
10
|
+
"hexastack-cqrs",
|
|
11
|
+
"hexastack-logging",
|
|
12
|
+
]
|
|
13
|
+
|
|
14
|
+
[[project.authors]]
|
|
15
|
+
name = "Richard West"
|
|
16
|
+
email = "dopplereffect.us@gmail.com"
|
|
17
|
+
|
|
18
|
+
[project.optional-dependencies]
|
|
19
|
+
ai = ["hexastack-ai"]
|
|
20
|
+
auth = ["hexastack-auth"]
|
|
21
|
+
cli = ["hexastack-cli"]
|
|
22
|
+
db = ["hexastack-db"]
|
|
23
|
+
sql = ["hexastack-db"]
|
|
24
|
+
docs = ["hexastack-fastapi[docs]"]
|
|
25
|
+
events = ["hexastack-events"]
|
|
26
|
+
fastapi = ["hexastack-fastapi"]
|
|
27
|
+
graphql = ["hexastack-graphql"]
|
|
28
|
+
grpc = ["hexastack-grpc"]
|
|
29
|
+
mcp = ["hexastack-mcp"]
|
|
30
|
+
otel = ["hexastack-otel"]
|
|
31
|
+
web = [
|
|
32
|
+
"hexastack-fastapi",
|
|
33
|
+
"uvicorn[standard]>=0.30.0",
|
|
34
|
+
]
|
|
35
|
+
flags = ["hexastack-flags"]
|
|
36
|
+
ui = ["hexastack-fastapi[ui]"]
|
|
37
|
+
testing = [
|
|
38
|
+
"faker>=33.0.0",
|
|
39
|
+
"hypothesis>=6.100.0",
|
|
40
|
+
"inline-snapshot>=0.35.4",
|
|
41
|
+
"playwright>=1.49.0",
|
|
42
|
+
"pytest-archon>=0.0.7",
|
|
43
|
+
"schemathesis>=3.39.0",
|
|
44
|
+
]
|
|
45
|
+
all = [
|
|
46
|
+
"hexastack-ai",
|
|
47
|
+
"hexastack-auth",
|
|
48
|
+
"hexastack-cli",
|
|
49
|
+
"hexastack-db",
|
|
50
|
+
"hexastack-events",
|
|
51
|
+
"hexastack-fastapi",
|
|
52
|
+
"hexastack-flags",
|
|
53
|
+
"hexastack-graphql",
|
|
54
|
+
"hexastack-grpc",
|
|
55
|
+
"hexastack-mcp",
|
|
56
|
+
"hexastack-otel",
|
|
57
|
+
"uvicorn[standard]>=0.30.0",
|
|
58
|
+
]
|
|
59
|
+
|
|
60
|
+
[project.scripts]
|
|
61
|
+
hexastack = "hexastack.entrypoint:main"
|
|
62
|
+
|
|
63
|
+
[build-system]
|
|
64
|
+
requires = ["uv_build>=0.12.3,<0.13.0"]
|
|
65
|
+
build-backend = "uv_build"
|
|
66
|
+
|
|
67
|
+
[tool.uv.sources.hexastack-ai]
|
|
68
|
+
workspace = true
|
|
69
|
+
|
|
70
|
+
[tool.uv.sources.hexastack-auth]
|
|
71
|
+
workspace = true
|
|
72
|
+
|
|
73
|
+
[tool.uv.sources.hexastack-core]
|
|
74
|
+
workspace = true
|
|
75
|
+
|
|
76
|
+
[tool.uv.sources.hexastack-cqrs]
|
|
77
|
+
workspace = true
|
|
78
|
+
|
|
79
|
+
[tool.uv.sources.hexastack-logging]
|
|
80
|
+
workspace = true
|
|
81
|
+
|
|
82
|
+
[tool.uv.sources.hexastack-events]
|
|
83
|
+
workspace = true
|
|
84
|
+
|
|
85
|
+
[tool.uv.sources.hexastack-fastapi]
|
|
86
|
+
workspace = true
|
|
87
|
+
|
|
88
|
+
[tool.uv.sources.hexastack-flags]
|
|
89
|
+
workspace = true
|
|
90
|
+
|
|
91
|
+
[tool.uv.sources.hexastack-cli]
|
|
92
|
+
workspace = true
|
|
93
|
+
|
|
94
|
+
[tool.uv.sources.hexastack-db]
|
|
95
|
+
workspace = true
|
|
96
|
+
|
|
97
|
+
[tool.uv.sources.hexastack-graphql]
|
|
98
|
+
workspace = true
|
|
99
|
+
|
|
100
|
+
[tool.uv.sources.hexastack-grpc]
|
|
101
|
+
workspace = true
|
|
102
|
+
|
|
103
|
+
[tool.uv.sources.hexastack-mcp]
|
|
104
|
+
workspace = true
|
|
105
|
+
|
|
106
|
+
[tool.uv.sources.hexastack-otel]
|
|
107
|
+
workspace = true
|
|
108
|
+
|
|
109
|
+
[tool.importlinter]
|
|
110
|
+
root_packages = ["hexastack"]
|
|
111
|
+
|
|
112
|
+
[[tool.importlinter.contracts]]
|
|
113
|
+
name = "Hexagonal architecture layer hierarchy"
|
|
114
|
+
type = "layers"
|
|
115
|
+
containers = ["hexastack"]
|
|
116
|
+
layers = [
|
|
117
|
+
"adapters",
|
|
118
|
+
"domain",
|
|
119
|
+
]
|