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.
@@ -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
+ ![hexastack](../../docs/assets/static/logos/packages/hexastack.png)
66
+
67
+ # hexastack
68
+
69
+ > The unified distribution package and diagnostic CLI for the Hexastack framework.
70
+
71
+ [![PyPI: hexastack](https://img.shields.io/pypi/v/hexastack.svg)](https://pypi.org/project/hexastack/)
72
+ [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
73
+ [![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack)](https://codecov.io/github/TheTrueSCU/hexastack)
74
+ [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
75
+ [![Accessibility: WCAG 2.1 AA](https://img.shields.io/badge/accessibility-WCAG%202.1%20AA-brightgreen.svg)](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
76
+ [![Tested with: axe--core](https://img.shields.io/badge/tested%20with-axe--core-4353ff.svg?logo=deque)](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
+ ![hexastack](../../docs/assets/static/logos/packages/hexastack.png)
2
+
3
+ # hexastack
4
+
5
+ > The unified distribution package and diagnostic CLI for the Hexastack framework.
6
+
7
+ [![PyPI: hexastack](https://img.shields.io/pypi/v/hexastack.svg)](https://pypi.org/project/hexastack/)
8
+ [![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
9
+ [![Coverage](https://codecov.io/github/TheTrueSCU/hexastack/graph/badge.svg?component=hexastack)](https://codecov.io/github/TheTrueSCU/hexastack)
10
+ [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
11
+ [![Accessibility: WCAG 2.1 AA](https://img.shields.io/badge/accessibility-WCAG%202.1%20AA-brightgreen.svg)](https://www.w3.org/WAI/WCAG21/quickref/?levels=aa)
12
+ [![Tested with: axe--core](https://img.shields.io/badge/tested%20with-axe--core-4353ff.svg?logo=deque)](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
+ ]