@aslomon/effectum 0.1.0

package/system/stacks/python-fastapi.md

@@ -0,0 +1,140 @@
+# Stack Preset: Python + FastAPI
+
+> Backend services and APIs with Python, FastAPI, Pydantic, and SQLAlchemy.
+
+## TECH_STACK
+
+```
+- Python 3.12+
+- FastAPI (latest stable)
+- Pydantic v2 for data validation and serialization
+- SQLAlchemy 2.0 with async support
+- Alembic for database migrations
+- pytest + pytest-asyncio for testing
+- httpx for async test client
+- ruff for linting and formatting
+- uv for package management (fallback: pip)
+- Docker + Docker Compose for local dev and deployment
+```
+
+## ARCHITECTURE_PRINCIPLES
+
+```
+- ASYNC BY DEFAULT: use async/await for all I/O-bound operations. Sync only for CPU-bound work.
+- TYPE HINTS EVERYWHERE: all function signatures, return types, and variables must have type annotations.
+- DEPENDENCY INJECTION: use FastAPI's Depends() for all shared resources (DB sessions, auth, config).
+- PYDANTIC MODELS: use Pydantic BaseModel for ALL request/response schemas. Never pass raw dicts across boundaries.
+- REPOSITORY PATTERN: separate data access from business logic. Services call repositories, not ORM directly.
+- MULTI-TENANT: include tenant_id/org_id in all data models from day one.
+- MIGRATIONS ONLY: DB changes through Alembic migrations exclusively. Never run raw DDL.
+- RESULT PATTERN: return typed results instead of raising exceptions for expected errors. Use exceptions only for truly exceptional situations.
+- SETTINGS VIA PYDANTIC: all configuration through pydantic-settings with env var validation.
+- STRUCTURED LOGGING: use structlog or similar. No print() or bare logging.info() in production.
+```
+
+## PROJECT_STRUCTURE
+
+````
+```
+src/
+  {project_name}/
+    __init__.py
+    main.py                 # FastAPI app factory
+    config.py               # Pydantic Settings
+    dependencies.py         # Shared FastAPI dependencies
+    api/
+      __init__.py
+      v1/
+        __init__.py
+        router.py           # API version router
+        endpoints/           # Route handlers by domain
+    models/
+      __init__.py
+      base.py               # SQLAlchemy Base, mixins
+      {domain}.py            # Domain models (e.g., user.py, team.py)
+    schemas/
+      __init__.py
+      {domain}.py            # Pydantic request/response schemas
+    services/
+      __init__.py
+      {domain}.py            # Business logic
+    repositories/
+      __init__.py
+      {domain}.py            # Data access layer
+    core/
+      __init__.py
+      security.py            # Auth, JWT, permissions
+      exceptions.py          # Custom exception classes
+      middleware.py           # Custom middleware
+    db/
+      __init__.py
+      session.py             # Async session factory
+      migrations.py          # Alembic helpers
+alembic/
+  versions/                  # Migration files
+  env.py
+  alembic.ini
+tests/
+  conftest.py                # Fixtures (test DB, client, auth)
+  test_{domain}/
+    test_endpoints.py
+    test_services.py
+    test_repositories.py
+pyproject.toml
+Dockerfile
+docker-compose.yml
+```
+````
+
+## QUALITY_GATES
+
+```
+- Build: `python -m build` or `uv build` — 0 errors
+- Types: `mypy src/` — 0 errors
+- Tests: `pytest --cov=src --cov-report=term-missing` — all pass, 80%+ coverage
+- Lint: `ruff check src/ tests/` — 0 errors
+- Format: `ruff format --check src/ tests/` — 0 differences
+- Security: `bandit -r src/` — no high-severity issues
+- Import Order: `ruff check --select I src/` — sorted
+- No Debug Logs: 0 print() statements in src/ (`grep -r "print(" src/`)
+- Type Safety: No `Any` type annotations in source code
+- File Size: No file exceeds 300 lines
+```
+
+## FORMATTER
+
+```
+ruff format
+```
+
+## FORMATTER_GLOB
+
+```
+py
+```
+
+## PACKAGE_MANAGER
+
+```
+uv
+```
+
+## STACK_SPECIFIC_GUARDRAILS
+
+```
+- **uv, not pip**: This project uses uv for package management. Avoid bare pip install — use `uv add` or `uv pip install`.
+- **Async by default**: All endpoint handlers, service methods, and repository methods must be async unless CPU-bound.
+- **Pydantic v2 syntax**: Use model_validator, field_validator (not validator, root_validator from v1).
+- **SQLAlchemy 2.0 style**: Use Mapped[], mapped_column(), select() — not legacy Column(), query() patterns.
+- **Alembic for all migrations**: Never modify the database schema outside of Alembic. Run `alembic revision --autogenerate` for changes.
+- **Settings validation**: All env vars must go through pydantic-settings. No raw os.getenv() in application code.
+- **Dependency injection**: Never instantiate DB sessions or config directly. Use FastAPI Depends().
+```
+
+## TOOL_SPECIFIC_GUARDRAILS
+
+```
+- **ruff runs automatically**: The PostToolUse hook auto-formats .py files with ruff format. Don't run ruff format manually.
+- **CHANGELOG is auto-updated**: The Stop hook handles CHANGELOG.md. Don't update it manually unless explicitly asked.
+- **Lock files are protected**: poetry.lock, Pipfile.lock cannot be written to directly. Use uv/pip/poetry commands.
+```

package/system/stacks/swift-ios.md

@@ -0,0 +1,136 @@
+# Stack Preset: Swift + iOS/macOS
+
+> Native Apple platform apps with Swift, SwiftUI, and SwiftData.
+
+## TECH_STACK
+
+```
+- Swift 6+ with strict concurrency checking
+- SwiftUI for all UI (no UIKit unless wrapping legacy components)
+- SwiftData for persistence (or CoreData for complex migration needs)
+- Swift Testing framework (preferred) + XCTest for UI tests
+- swift-format for code formatting
+- SwiftLint for linting
+- Swift Package Manager (SPM) for dependencies
+- Xcode 16+ as primary IDE/build system
+```
+
+## ARCHITECTURE_PRINCIPLES
+
+```
+- MVVM: Views -> ViewModels -> Services/Repositories. No business logic in Views.
+- PROTOCOL-ORIENTED: define protocols for services and repositories. Use concrete types only at composition root.
+- @Observable MACRO: use @Observable (Swift 5.9+) instead of ObservableObject/Published for ViewModels.
+- ACTOR ISOLATION: use actors for shared mutable state. Mark MainActor for all UI-related code.
+- STRUCTURED CONCURRENCY: use async/await and TaskGroup. No completion handlers for new code.
+- VALUE TYPES: prefer structs over classes. Use classes only for reference semantics or inheritance.
+- DEPENDENCY INJECTION: pass dependencies through initializers or environment. No singletons except at app root.
+- ERROR HANDLING: use typed throws (Swift 6) and Result type. Never force-unwrap (!) in production code.
+- SWIFTDATA MODELS: use @Model macro for persistence. Define schemas with explicit versioning.
+- PREVIEW-DRIVEN: every view must have a working #Preview with mock data.
+```
+
+## PROJECT_STRUCTURE
+
+````
+```
+{ProjectName}/
+  App/
+    {ProjectName}App.swift          # @main entry point
+    ContentView.swift               # Root navigation
+    AppState.swift                  # Global app state
+  Features/
+    {Feature}/
+      Views/
+        {Feature}View.swift
+        {Feature}DetailView.swift
+      ViewModels/
+        {Feature}ViewModel.swift
+      Models/
+        {Feature}Model.swift        # SwiftData @Model or domain model
+  Core/
+    Services/
+      {Domain}Service.swift         # Business logic services
+      NetworkService.swift          # API client
+    Repositories/
+      {Domain}Repository.swift      # Data access layer
+    Extensions/
+      View+Extensions.swift
+      String+Extensions.swift
+    Protocols/
+      {Domain}ServiceProtocol.swift
+    Utilities/
+      Logger.swift
+      Constants.swift
+  Resources/
+    Assets.xcassets
+    Localizable.xcstrings
+    Info.plist
+  Previews/
+    PreviewData.swift               # Shared mock data for previews
+{ProjectName}Tests/
+  Features/
+    {Feature}/
+      {Feature}ViewModelTests.swift
+  Core/
+    Services/
+      {Domain}ServiceTests.swift
+{ProjectName}UITests/
+  {Feature}UITests.swift
+Package.swift (if SPM-based)
+```
+````
+
+## QUALITY_GATES
+
+```
+- Build: `swift build` or `xcodebuild build` — 0 errors, 0 warnings
+- Tests: `swift test` or `xcodebuild test` — all pass
+- Lint: `swiftlint lint --strict` — 0 violations
+- Format: `swift-format lint -r Sources/` — 0 differences
+- Concurrency: strict concurrency checking enabled — 0 warnings
+- No Force Unwrap: 0 occurrences of `!` on optionals in production code
+- No Print: 0 print() statements in production code (use Logger)
+- Preview: all views have working #Preview blocks
+- File Size: No file exceeds 300 lines
+```
+
+## FORMATTER
+
+```
+swift-format format -i
+```
+
+## FORMATTER_GLOB
+
+```
+swift
+```
+
+## PACKAGE_MANAGER
+
+```
+swift package (SPM)
+```
+
+## STACK_SPECIFIC_GUARDRAILS
+
+```
+- **SPM for dependencies**: Use Swift Package Manager exclusively. No CocoaPods or Carthage.
+- **SwiftUI only**: All new UI must be SwiftUI. UIKit wrappers (UIViewRepresentable) only for components without SwiftUI equivalents.
+- **@Observable over ObservableObject**: Use the @Observable macro (Swift 5.9+) for all new ViewModels. Do not use ObservableObject/Published.
+- **Structured concurrency**: Use async/await and TaskGroup. No DispatchQueue or completion handlers in new code.
+- **Actor isolation**: Use @MainActor for all ViewModel and View-related code. Use custom actors for shared mutable state.
+- **No force unwrap**: Never use `!` to force-unwrap optionals in production code. Use guard-let, if-let, or nil-coalescing.
+- **SwiftData versioning**: Always define schema versions when modifying @Model types. Use VersionedSchema and SchemaMigrationPlan.
+- **Previews are mandatory**: Every View must have a #Preview block with representative mock data.
+- **Localization from day one**: Use String(localized:) for all user-facing strings. Never hardcode display text.
+```
+
+## TOOL_SPECIFIC_GUARDRAILS
+
+```
+- **swift-format runs automatically**: The PostToolUse hook auto-formats .swift files. Don't run swift-format manually.
+- **CHANGELOG is auto-updated**: The Stop hook handles CHANGELOG.md. Don't update it manually unless explicitly asked.
+- **Package.resolved is protected**: Package.resolved cannot be written to directly. Use `swift package resolve` or `swift package update`.
+```